section · guides

Your first task

Initialize a project and dispatch one task end-to-end.

3 min read·guides / start / first-task

Pick a project

cd ~/code/your-project

It needs to be a git repo (Construct uses .git/ to wire pre-commit hooks). Branch state doesn't matter.

Initialize Construct in the project

construct init --yes

One command does all of it:

Scaffolds the project — .construct/context.md and .construct/context.json (durable per-project state Construct reads at session start), .construct/handoffs/ (gitignored, session handoffs land here), docs/ documentation lanes if your project doesn't have them yet, a local issue-tracking directory if your project doesn't already track issues (see durable state →).
Syncs agent adapters into whichever editor configs it finds on disk — ~/.claude/agents/*.md for Claude Code, ~/.config/opencode/opencode.json for OpenCode, ~/.codex/agents/*.toml for Codex, ~/.github/prompts/*.prompt.md for Copilot prompt profiles, ~/.cursor/mcp.json for Cursor MCP registrations if Cursor is already configured, VS Code user settings.json for GitHub Copilot MCP registrations if VS Code is already configured.
Starts the local runtime by default — local dashboard at http://localhost:<port> (port auto-selected), memory MCP server at 127.0.0.1:8765, local trace capture in .construct/traces/*.jsonl. Pass --no-start to skip service startup, or --interactive for the guided flow.

Re-running construct init on an existing project is safe; it's idempotent. Re-run construct sync on its own any time you only need to refresh adapters (after a registry, prompt, or config change), and construct dev on its own any time you only need to (re)start services without touching adapters.

Dispatch a task

Open your editor. Two modes depending on the request:

Simple ask

Address @construct directly. The persona answers without a full specialist chain.

@construct read the README and summarize what this project is.

Good for: questions, summaries, small lookups, one-file changes.

Involved work

Construct routes through the specialist chain: architect → researcher → reviewer → security.

@construct review the auth flow in src/auth/ and flag risks.

Good for: code review, architectural decisions, security-sensitive changes, PRDs.

Confirm specialists will actually run

Both dispatch paths above route through specialists — but a specialist chain only runs a real LLM (EXECUTE) when a provider is attached; otherwise it only prepares prompts (PLAN) and returns no reasoned output. construct init printed a line telling you which one you're in:

specialists will EXECUTE (provider <family> + key found)
specialists will only PLAN (fix: set orchestration.workerBackend=provider + a key)

If you're in Claude Code or OpenCode, a host session is already attached, so specialists EXECUTE with no extra setup. On any other host (Codex, Copilot, VS Code, Cursor), or if you want Claude Code to use a specific provider model instead of the host's own, set orchestration.workerBackend: "provider" in construct.config.json and export a materialized provider key (ANTHROPIC_API_KEY, OPENROUTER_API_KEY, or OPENAI_API_KEY). Rerun construct doctor and check the last line before trusting specialist output. See install → EXECUTE vs PLAN.

When you need more: working from files instead of chat

Everything above assumes you're typing requests directly. For work that arrives as a file instead — a bug report, a customer comment, a competitor scan, a postmortem draft — Construct can pick it up automatically, classify it, and route it to the right specialist without you retyping it as a prompt. See processing incoming files → once you're comfortable with the basics above.

What just happened

Construct's persona held the conversation, but behind the scenes it routed work through specialists and enforced policy gates on any mutations. Session state was persisted to .construct/context.md so the next session resumes mid-flight.

Next: connect your editor →