Install Construct

Prerequisites

• Node.js 20+ (node --version)
• A git repo to play in. Construct expects .git/ so it can wire pre-commit hooks.

No database or Docker is required. Retrieval runs on an embedded LanceDB index and traces write to .construct/traces/*.jsonl — everything is local files.

Install

Project dependency (recommended)

cd ~/your-project
npm install -D @geraldmaron/construct

That's it. The postinstall hook stages .construct/ (launcher) and .claude/ (agents, hooks, slash commands) into your project. Peers who clone your repo and run npm install get the same setup automatically — Construct travels with your project like Tailwind or ESLint.

If you want to opt into Construct in a project that doesn't yet pin it:

cd ~/your-project
npx -y @geraldmaron/construct init .

init does what the postinstall does, plus scaffolds AGENTS.md, plan.md, .construct/, a local issue tracker, docs/, and construct_guide.md (a friendly orientation file you can keep or edit). See durable state → for how that issue tracker fits into session continuity once you're past the basics.

Homebrew (for users without Node)

brew install geraldmaron/construct/construct

Drops a single binary into /opt/homebrew/bin/. No Node required. For per-project wiring you still add @geraldmaron/construct to your package.json (or run construct init in the project). If brew install reports that bin/construct already exists, resolve the path conflict explicitly with brew link --overwrite construct after you confirm you want the Homebrew-managed binary to win.

Run setup (one time per machine)

construct install --footprint=user

What setup does, in order:

1. Creates ~/.config/construct/config.env and seeds default model tier assignments.
2. Configures the embedded LanceDB vector path and pre-warms the embedding model. Use --yes to accept detected defaults non-interactively.
3. Generates shell completions (bash + zsh) so construct <tab> works.
4. Installs optional CLIs (cm, cass) if Homebrew or cargo is available and you consent.
5. Installs the Pressure Guard background service (macOS LaunchAgent) so Construct can manage helper processes. Use --no-launch-agent to skip this.
6. Wires core.hooksPath to your project's local hook directory if it has one — activates the local pre-commit policy gates.
7. Prints a "Local services" summary block with local trace capture and the embedded LanceDB index path.

Service consent is cached in ~/.config/construct/config.env as BOOTSTRAP_<NAME>=yes|no. Re-running construct install --footprint=user won't re-prompt for services you already answered about. Delete those keys to re-prompt.

Flags

Flag	Description
--footprint=project|user|both	Define the installation footprint — where Construct writes on this machine. Required — a bare construct install with no --footprint hard-errors naming the flag rather than writing nothing silently. Unrelated to the construct scope org-profile command; ADR-0071 renamed this flag from --scope.
--scope=project|user|both	Deprecated alias for --footprint (same values). Prints a one-line deprecation notice; kept working for existing scripts. See ADR-0071.
--yes	Accept all defaults without prompting.
--dry-run	Preview the install plan (footprints, files, services) without writing anything.
--no-launch-agent	Skip background macOS LaunchAgent registration.
--reconfigure	Re-prompt for service consent, ignoring cached answers.
--with-docling	Install the Docling runtime for local document extraction.

What you have when setup finishes

Everything is local files — setup opens no host ports and stands up no database.

Traces — local-first observability

• Local: .construct/traces/*.jsonl
• Remote export: optional with CONSTRUCT_TRACE_BACKEND=langfuse|http|otel

Vector storage — semantic search on embedded LanceDB

• Embedded LanceDB index at ~/.local/state/construct/vector/lancedb (override with CONSTRUCT_LANCEDB_PATH; a project can keep it under .construct/lancedb)
• 384-dim embeddings via Xenova/all-MiniLM-L6-v2
• The embedding model auto-downloads to ~/.cache/construct/embeddings/ on first use (~22 MB, one time)
• No database, no Docker: retrieval is a local file-backed index

Any services construct dev starts later (memory, the OpenCode bridge) bind to 127.0.0.1 only — nothing is reachable from other machines on your network.

Cloud telemetry is opt-in: set CONSTRUCT_TRACE_BACKEND plus the matching endpoint/key variables before running construct init and Construct will respect them.

Verify

construct doctor

doctor runs ~35 health checks across config, services, agents, hooks, and integrations. Anything green is healthy. Warnings explain themselves. Failures point at a fix.

You're installed in solo mode — everything runs locally, telemetry is optional. Two other modes (team and enterprise) promote local state and memory to shared, centrally-routed infrastructure for a whole team. Switch with construct config mode [solo|team|enterprise]. See deployment model.

EXECUTE vs PLAN: do specialists actually run an LLM?

construct init and construct doctor both end with one of two lines:

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

PLAN means Construct prepares specialist prompts/tasks but never calls an LLM to reason over them — nothing came back. EXECUTE means a specialist run actually reasoned and returned real output. Read that line at the end of construct init/construct doctor output — don't assume EXECUTE just because setup finished cleanly.

Claude Code and OpenCode run the specialist chain natively (a host session is attached), so they get real reasoning without any provider key. Every other host (Codex, Copilot, VS Code, Cursor) has no native subagent primitive and needs orchestration.workerBackend=provider plus a provider key to EXECUTE — see connect your editor.

To force EXECUTE anywhere — including inside Claude Code, if you don't want to rely on the host's own model — set in construct.config.json:

{ "orchestration": { "workerBackend": "provider" } }

and export a materialized (not op://...) key for the provider family you want: ANTHROPIC_API_KEY, OPENROUTER_API_KEY, or OPENAI_API_KEY. workerBackend defaults to inline, which never runs specialist LLM reasoning regardless of any key present.

You're installed. Now do your first task →

Uninstall (when you're done)

construct uninstall          # interactive — pick what to remove
npm uninstall @geraldmaron/construct

construct uninstall removes Construct-owned state (launcher, agents, hooks). Ask-risk items (API keys, the embedding model cache, AGENTS.md/plan.md) are skipped unless you opt in. It never touches Homebrew or anything you didn't put through Construct.

For full reference: construct uninstall --help.