Quickstart

Install the harness, register a project, and run one feature through the SDLC pipeline. For operators setting up ai-conductor for the first time.

Prerequisites

bin/install checks none of these before it starts. It fails late, partially, or silently if one is missing, so install them first.

Requirement	Needed for	Verify
`curl` — or use the manual clone path below	downloading the one-line installer	`curl --version`
`git`	cloning the harness; every worktree operation	`git --version`
`gh`, authenticated	opening spec and implementation PRs	`gh auth status`
`tmux`	`ai-conductor daemon start/stop/restart/connect/debug`	`tmux -V`
`python3`	writing permissions and hooks into `~/.claude/settings.json`	`python3 --version`
Node >= 26.0.0 (repo pins 26.7.0)	building and running the engine, and reading/writing the markdown-viewer and mermaid-renderer config	`node --version`
`npm`	`npm ci` + `npm run build` for the engine	`npm --version`
`claude`, `codex`, and/or `pi`	executing steps — at least one is required	`claude --version` / `codex --version` / `pi --version`
`rg` (ripgrep) — optional	full shell test coverage; several tests skip themselves without it. `bin/install --check` warns, never fails	`rg --version`

Node is pinned to 26.7.0 in .tool-versions and src/conductor/.tool-versions. Install it with asdf install nodejs 26.7.0 or any equivalent version manager. bin/ai-conductor exports ASDF_NODEJS_VERSION from that pin only when asdf is on PATH — without asdf, whatever node resolves first runs the engine.

Pick your provider now: claude, codex, pi, or a fallback ladder. See multiprovider for what each one changes.

One-line install

curl -fsSL https://jstoup111.github.io/ai-conductor/install.sh | sh

This clones the stable channel into ~/.ai-conductor/harness and runs ./bin/install there, so you can skip the next two sections. Choose a channel or providers with ... | sh -s -- --channel tagged --providers claude. Running it again updates the existing install.

Clone the harness

To install from a manual clone instead:

git clone --branch stable --single-branch https://github.com/jstoup111/ai-conductor.git
cd ai-conductor

Clone to a normal directory. A checkout whose physical path contains /.worktrees/ is refused by the installer — see Refusing to install from a build worktree. The stable branch advances only after release CI has published its matching tag and GitHub Release; it therefore excludes work still in flight on main.

Install

./bin/install

On a TTY with no --providers flag, the installer prompts for four things: the built-in host (Claude, Codex, Pi, or a comma-separated combination), the update channel, a markdown viewer, and a mermaid renderer. Pass the selection up front to skip the first prompt:

./bin/install --providers=claude,codex

--providers gates only the install-time readiness report. Both skill catalogs (~/.claude/skills and ~/.agents/skills) are written regardless of the value, and the flag never writes a host into any config.

You should see Installation complete. followed by a quick-start banner.

Put `~/.local/bin` on PATH

The installer symlinks ai-conductor into ~/.local/bin but never edits your shell profile. If that directory is not already on PATH it prints:

  ⚠ ~/.local/bin is NOT on PATH
  → Add to your shell profile: export PATH="$HOME/.local/bin:$PATH"

Add it yourself, then reload your shell:

export PATH="$HOME/.local/bin:$PATH"

Verify the install

./bin/install --check
ai-conductor --help

--check mutates nothing. Its exit code is the signal:

Exit code	Meaning
`0`	All checks passed. Prints `All checks passed.`
`1`	Drift: missing, stale, or duplicated skill links, or a failed host-CLI or bin-symlink check. Prints a per-category count and `Run ./bin/install to fix.`
`2`	Everything else is clean but `ai-conductor build-auth-status` failed

Exit 2 prints Build authentication check failed. instead of the All checks passed. summary — read the build-auth-status: line in the body for the underlying reason. The engine treats both 0 and 2 as passing; any other code blocks ai-conductor daemon start on a stale install.

Register a project

The target must already be a git repository.

cd /path/to/your-project
ai-conductor register

You should see Registered <name> (<absolute-path>). The record lands in ~/.ai-conductor/registry.json with status: registered; nothing is written into the project.

To scaffold a new repository instead, ai-conductor create <name> runs git init and writes a skeleton CLAUDE.md, a .gitignore, and a project-safe .ai-conductor/config.yml before registering it. Both commands are detailed in reference/cli.md.

Bootstrap the project

register writes no project artifacts. create writes the minimal scaffold described above. bootstrap detects the stack and generates the remaining project instruction files, .docs/ tree, and memory store. It is a skill, not a CLI command, so run it inside a host session:

claude

Then, in-session:

/bootstrap

Under Codex the same skill is invoked as $bootstrap. You should end with CLAUDE.md (and/or AGENTS.md) referencing the harness, plus a populated .docs/ directory.

For an existing Git repository, bootstrap runs the idempotent ai-conductor config init primitive. You can also run that command directly before bootstrap. It creates .ai-conductor/config.yml from the project-safe template and preserves an existing file byte-for-byte. See reference/configuration.md.

Run your first feature with the daemon

ai-conductor compose --idea "add a CSV export to the reporting page"

The composer authors the DECIDE artifacts in an isolated worktree and opens a spec PR. Review and merge that PR, then start the daemon:

ai-conductor daemon start

The daemon drains merged specs, builds each feature in an isolated worktree, retains its logs, and opens an implementation PR. Watch it with ai-conductor daemon logs --follow or check it with ai-conductor daemon status.

Continue with first feature for the complete idea → spec PR → daemon build → implementation PR walkthrough.

For a supervised foreground run, use ai-conductor inline --interactive "add a CSV export to the reporting page". The foreground --auto mode is deprecated; use the daemon for unattended work. Inline flags are enumerated in reference/cli.md.

First-run blockers

Each of these is a real guard in the code, with the text it emits.

Missing engine bundle

The engine is gitignored, so a fresh clone has no dist until bin/install (or npm run build) runs.

ai-conductor: missing <harness>/src/conductor/dist/index.js
ai-conductor: run 'npm run build' in src/conductor/

A half-finished publish leaves a dangling symlink instead:

ai-conductor: dist symlink is broken (<harness>/src/conductor/dist)
ai-conductor: run 'npm run build' to rebuild, or republish the engine, to fix it

Both exit 1. Fix by re-running ./bin/install, or npm run build inside src/conductor/. Never run tsup directly — the publish guard refuses it.

Wrong Node version

The installer still links the skills, permissions and hooks — those work on any Node — but it cannot build the engine, so the run fails:

  ✗ ai-conductor requires Node >=26 — found v20.11.0
  → This repo pins nodejs 26.7.0 via .tool-versions; install it (e.g. 'asdf install nodejs
    26.7.0'), then re-run bin/install

and the run ends with the reason restated:

Installation incomplete — ai-conductor was not installed.
  ✗ ai-conductor requires Node >=26 but found v20.11.0. Install the pinned nodejs 26.7.0
    (.tool-versions), then re-run ./bin/install.

./bin/install exits 1, and so does ./bin/install --check while the bundle is missing or ai-conductor is off PATH. A missing npm, or a failing npm ci/npm run build, fails the same way. Install Node 26.7.0 and re-run ./bin/install.

Missing `gh` authentication

Nothing checks gh at install time. It surfaces when a spec is landed:

Cannot land spec: identity unresolved. Resolve one of:
  1. Set spec_owner in ~/.ai-conductor/config.yml
  2. Authenticate via: gh auth login

Exit 1. Run gh auth login, or set spec_owner in the user config. The daemon’s backlog scan fails closed on the same identity — an unidentified daemon builds nothing and logs daemon identity unresolved: … building NOTHING (fail-closed). See running the daemon.

Refusing to install from a build worktree

bin/install matches its own resolved physical path against */.worktrees/*:

  ✗ Refusing to install from a build worktree.

  Resolved harness root: <physical_root>

  Installing from a worktree would repoint your global bins, skills, and
  settings.json hooks at a directory that is deleted when the build ships.

  Fix: run bin/install from the main checkout, or pass --allow-worktree-root
  if you really mean to install from this worktree.

Exit 1. The guard applies to the default and --update modes only; --check, --uninstall, and --help are unaffected. Install from the main checkout.

Missing or broken `ai-conductor` at viewer/renderer configuration time

The markdown-viewer and mermaid-renderer prompts write their selection through ai-conductor config write, not Python/YAML. If ai-conductor is not yet on PATH (for example the engine build failed — see Missing engine bundle above), the prompts are skipped:

  ⚠ ai-conductor is required to save the markdown viewer; install or restore it, then re-run bin/install

and if the write itself fails (e.g. the target directory is unwritable), the installer warns and the step fails rather than silently reporting success:

  ⚠ Could not save markdown viewer configuration

Either way, ~/.ai-conductor/config.yml gets no viewer or renderer block, and install continues with a warning rather than aborting. Fix the underlying ai-conductor problem and re-run ./bin/install. ./bin/install --check reports the configured viewer and renderer, or ai-conductor not on PATH / configuration unreadable when it cannot read them back.

Missing tmux

The daemon builds without tmux but cannot be hosted by it:

tmux is not installed or not found on PATH. Please install tmux to use daemon hosting.

Install tmux before ai-conductor daemon start. Recovery for a daemon that started and then broke is in runbooks/daemon-recovery.md.

Updates

The installer writes conductor.update_channel — stable (default), tagged, or main — to ~/.ai-conductor/config.yml; it does not create the legacy JSON configuration file. stable fast-forwards a branch only to fully published releases, tagged uses semver tag checkouts, and main follows every merge. Existing tag-pinned installations are not switched automatically.

ai-conductor spawns bin/update --auto on startup and swallows every failure. Force an attended check, or update a stable checkout manually:

cd /path/to/ai-conductor
bin/update
# or:
git pull --ff-only origin stable && bin/migrate

A major version crossing — v0.104.0 → v1.0.0, or any change to the leading semver component — is held to a stricter approval than an ordinary update, because a major is by definition a breaking change to skill contracts, the CLI, or the settings.json schema:

The startup --auto check reports that one is available and stops there. It never applies a major update, so a breaking upgrade cannot be accepted by reflex at the start of a session.
An attended bin/update requires typing the target version (v1.0.0) to confirm. A bare y does not apply it.
With no TTY, the command to run is printed and nothing is applied, as with any other update.

Ordinary patch and minor updates keep the single [y/n] prompt. The main channel has no semver identity to compare, so it is unaffected.

If a stable checkout ends up in detached HEAD — a pre-v1 updater moved stable installs with git checkout vX.Y.Z — bin/update offers to re-attach the stable branch instead of stopping. Answer the prompt, or run the git checkout -B stable <sha> && bin/migrate command it prints when there is no TTY. A detached checkout you made yourself, off the stable lineage, is left alone.

Choose the first-run channel during installation with bin/install --channel tagged (or main or stable), or set AI_CONDUCTOR_CHANNEL when passing a flag is inconvenient. The flag takes precedence over the environment variable; an unattended install with neither uses stable.

Choose a different channel explicitly with bin/update --set-channel tagged or bin/update --set-channel main. Changing the configured channel does not move the current checkout. To move an existing branch-based installation to stable deliberately:

git fetch origin stable:refs/remotes/origin/stable
git switch --track origin/stable
bin/update --set-channel stable
bin/migrate

Removing the harness

./bin/install --uninstall

--uninstall removes harness-owned skill and reference links, the conduct, conduct-ts, and ai-conductor launchers, the harness’s entries in ~/.claude/settings.json, and the global rate-card link when it points at this checkout. It preserves operator-authored settings, links, and rate cards.

The command keeps ~/.ai-conductor/, including operator configuration and runtime data such as the project registry and memory. Remove that state only when you want a clean slate:

./bin/install --uninstall --purge

--purge is valid only with --uninstall. It removes ~/.ai-conductor/; if that path is a symlink, it removes only the symlink. Legacy ~/.claude/ai-conductor.config.json and ~/.claude/ai-conductor.config.json.migrated files are not installer-owned and remain unchanged. See settings and hooks for the global settings surface.