Archon turns AI coding runs into YAML workflows with gates, queues and worktrees

A workflow is a graph of nodes, and code decides when a loop ends

Archon does not ship its own coding agent. It runs Claude Code, Codex and Pi through their own CLIs and SDKs, and wraps them in a workflow file you keep in your repository under .archon/workflows/. Each node is an agent prompt, a bash command, a script, a loop, a wait for a person or a child workflow, and depends_on fixes the order.

The interesting part is who decides when a step is finished. In the example build-feature workflow, the implement node loops on an agent prompt, but the exit condition is a shell command:

  - id: implement
    depends_on: [plan]
    loop:
      prompt: "Implement the next step of the plan."
      until_bash: "bun run test"          # your test command; code decides when it is done
      max_iterations: 10
      fresh_context: true

until_bash means the agent cannot declare victory on its own; your test command does. max_iterations caps the loop at 10 rounds, and fresh_context starts each round without the previous transcript. The next node, approve, is a wait node: the run pauses until you approve or reject, and a rejection routes to stop instead of opening the pull request.

Each repository run gets its own git worktree

Once the file is saved, you start a run from the CLI with the workflow name and a request:

archon workflow run build-feature "Add dark mode to the settings page"

Repository runs get their own git worktree by default, so several runs can work on one repository at once without overwriting each other's checkout. Every run keeps a full event log, a transcript and its cost in your own database, which is what Archon means by governance: you can see afterwards what each agent did and what it cost.

When a run hits a decision it cannot make, it does not stall silently. It becomes one attention item that states what the decision is, why it matters, a recommendation and the choices. You answer and the run continues. The project calls this being on the loop rather than in it.

The sdlc pack moves an issue through four queues to a merged PR

The bundled sdlc pack is the worked example of the engine. archon-intake checks a new issue against the current code and sends it to a plan, an investigation, straight to delivery, or to a maintainer. archon-build-queue claims the next ready issue, writes a brief and runs archon-ship: plan, implement, review through specialist lenses, fix the findings and wait for CI. archon-merge-queue merges ready pull requests that merge cleanly, after a gate checks the review verdict, CI at the head commit and that the base branch is not red; a conflicting pull request goes back to the build queue. archon-discoveries files anything a run noticed outside its task.

The project uses this on itself: of the 524 pull requests merged into the Archon repository between 1 and 19 October 2026, Archon runs built 363. Two consequences for a new user. The pack binds nothing by default, so no queue runs until you start it by hand or attach a trigger to a schedule or issue events. And the pack works through the GitHub CLI (gh) today; other code hosts go through the forge plugin route, so a team on another host has more setup before the factory does anything.

Archon does not bundle Claude Code, and compiled binaries need its path

The installer asks which providers to add, but the agents themselves are separate installs. The first quickstart step is to install Claude Code and sign in, or install Codex. Archon itself installs one of three ways:

curl -fsSL https://archon.diy/install | bash        # macOS / Linux
irm https://archon.diy/install.ps1 | iex             # Windows (PowerShell)
brew install coleam00/archon/archon                 # Homebrew, then: archon setup

The .env.example file marks CLAUDE_BIN_PATH as required for compiled Archon binaries, because Archon does not bundle Claude Code. Dev mode under bun run resolves it through node_modules, so a setup that works from a source checkout can fail after switching to the compiled binary. The fix is to set CLAUDE_BIN_PATH, for example to $HOME/.local/bin/claude for the native installer, or to set assistants.claude.claudeBinaryPath in ~/.archon/config.yaml. Codex needs its own login, with credentials taken from ~/.codex/auth.json after running codex login.

A set CLAUDE_API_KEY overrides your subscription login

Claude authentication has three modes. CLAUDE_USE_GLOBAL_AUTH=true uses the login from claude /login and is the recommended value in .env.example. false uses explicit tokens. Leaving it unset auto-detects: tokens if present, otherwise global auth.

The trap is precedence. CLAUDE_CODE_OAUTH_TOKEN wins over CLAUDE_API_KEY, and a set API key is used even when CLAUDE_USE_GLOBAL_AUTH=true. That means metered API billing, not your claude /login subscription. CLAUDE_API_KEY is also mirrored to ANTHROPIC_API_KEY for the Claude subprocess. If you run long loops with max_iterations set high and an API key left in the environment, every round is billed per token. Check the environment before the first queue run, and use the per-run cost Archon records to confirm which account paid.

SQLite is the default until runs get heavily parallel

With no configuration, Archon stores state in SQLite at ~/.archon/archon.db. The .env.example comment recommends PostgreSQL for heavy parallel usage of 20 or more concurrent workflows. Since worktrees make parallel runs the normal case, a team that turns on both queues should plan the database before it needs it.

The Docker Compose file exposes this through profiles:

docker compose up -d
docker compose --profile with-db up -d
docker compose --profile cloud up -d

The with-db profile adds a local PostgreSQL container, which you still have to point at with DATABASE_URL in .env; you can also aim DATABASE_URL at an external database such as Supabase or Neon. The cloud profile adds Caddy, which obtains a Let's Encrypt certificate once DOMAIN is set and a DNS A record points at the server. ARCHON_DATA moves data to a host path instead of the archon_data volume, and ARCHON_USER_HOME does the same for /home/appuser, where Claude Code skills, Codex and Pi auth state and ~/.gitconfig persist across container rebuilds.

Plugins install from GitHub repositories, and only a few ship in the box

The core is kept to the workflow engine, isolation, durable state, the attention queue and an audit trail. Everything that talks to the outside world is a plugin: workflow packs, providers, forges and chat surfaces. GitHub acts as the registry, and you install a plugin from someone's repository:

archon plugin add owner/repo

The maintained set is short. The only maintained workflow pack is sdlc, the providers are Claude Code, Codex and Pi, the only forge is GitHub and the only chat surface is Slack. Anything outside that list is either a third party plugin you have to vet yourself or one you write against the published contract. For a team on another code host or chat tool, the factory is not usable out of the box.

The repository is under heavy development: v0.13.0, v0.13.1 and v0.13.2 of the CLI all shipped between 28 and 29 October 2026, and the last push landed on 2 November 2026. Pre-1.0 version numbers and that release pace mean workflow files and plugin contracts can change between upgrades, so pin a version for anything you depend on.

Editorial conclusion

Archon suits teams that already pay for Claude Code or Codex, host code on GitHub, and want every agent run to follow the same plan, test, review and approval steps with a stored event log and cost. It is a poor fit if your code lives on another forge without a plugin, or if you want a bundled agent. Before adopting it, confirm that CLAUDE_BIN_PATH points at a working Claude Code install, that no CLAUDE_API_KEY is set unless you want metered billing, and that SQLite is enough for the number of runs you plan to keep in parallel.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes