Archon: a YAML workflow engine that puts structure around AI coding agents

The problem Archon solves is run-to-run variance, not model quality

Ask an AI agent to fix a bug and the result depends on the run. The README states this plainly: the agent "might skip planning. It might forget to run tests. It might write a PR description that ignores your template." Archon's answer is to move the development process out of the prompt and into a file you own.

A workflow defines phases, validation gates and artifacts. The agent supplies reasoning inside each phase, but the sequence is fixed and versioned with your code. That distinction matters when you are paying for agent time: a skipped test run is not a creativity problem, it is a process problem, and process problems respond to structure rather than better prompts.

The intended audience is a team that already uses Claude Code as its coding agent and wants the same five-step routine (plan, implement, validate, review, PR) to happen the same way on every task. It is not aimed at people who want a general-purpose agent framework, and it is not a chat interface. The README positions it explicitly against Dockerfiles and GitHub Actions: a declarative file that makes an otherwise improvised process repeatable.

How a workflow run actually executes: YAML nodes, dependencies, worktrees

A workflow is a list of nodes under `.archon/workflows/`. Each node has an `id`, and `depends_on` establishes the order. Nodes come in two flavours. A node with a `prompt` invokes the AI assistant. A node with a `bash` key runs a shell command and no model at all, which is how the README keeps deterministic steps deterministic: `bash: "bun run validate"` always runs the same command.

The `loop` construct is the more interesting mechanism. A loop node carries a `prompt`, an `until` condition, and a `fresh_context` flag. In the README example the condition is `ALL_TASKS_COMPLETE`, and `fresh_context: true` means each iteration starts a new session rather than carrying the accumulated conversation forward. That is a deliberate trade: fresh context avoids the drift and token growth of a long session, at the cost of the agent re-reading state it might otherwise have remembered.

Isolation is handled by git worktrees. The README states that every workflow run gets its own worktree, so five fixes can run in parallel without conflicting. The worked example shows a branch named `archon/task-dark-mode` and a PR opened at the end. The repository layout is consistent with this: `packages/isolation`, `packages/git` and `packages/workflows` are separate workspace packages, and `packages/adapters` and `packages/providers` sit alongside them, which suggests platform integrations (Slack, Telegram, GitHub) are adapter-shaped rather than baked into the engine.

Installing Archon and running a first workflow

There are two paths. The full setup clones the repository and uses a guided wizard that configures credentials, platform integrations and copies the Archon skill into your target project. The prerequisites listed are Bun, Claude Code and the GitHub CLI.

git clone https://github.com/coleam00/Archon
cd Archon
bun install
claude

After `claude` starts, the README says to type "Set up Archon" and the wizard takes over. The second path is the standalone CLI, which skips the wizard. On macOS and Linux:

curl -fsSL https://archon.diy/install | bash

Homebrew users can install from the project's tap instead:

brew install coleam00/archon/archon

One constraint applies to the quick install: the README notes that macOS and Linux binaries require AVX2 on x64 CPUs, and that older Intel or AMD hardware and virtual machines masking AVX2 should use the source installation guide. ARM64 is unaffected. Compiled binaries also do not bundle Claude Code, so the binary needs to be told where it is:

export CLAUDE_BIN_PATH="$HOME/.local/bin/claude"

The same value can be set as `assistants.claude.claudeBinaryPath` in `~/.archon/config.yaml`. With that in place, the first real use is to change into your own project, start Claude Code there (not in the Archon repository, which the README calls out as important), and ask for a workflow by name:

cd /path/to/your/project
claude

Then, inside the session, `Use archon to fix issue #42`. Projects are registered automatically the first time they are used, and the agent picks the workflow, the branch name and the worktree.

Where Archon is the wrong tool, and what it does not do for you

Archon does not write your workflows. The engine executes YAML you author; if the workflow encodes a bad process, Archon will reproduce that bad process reliably. The README's framing of determinism is about sequence and gates, not about correctness of the plan the model produces inside a node.

The heavier constraint is the dependency on Claude Code. The README's setup instructions install it, the quick-install section warns that binaries need `CLAUDE_BIN_PATH`, and the `.env.example` documents `CLAUDE_USE_GLOBAL_AUTH`, `CLAUDE_CODE_OAUTH_TOKEN` and `CLAUDE_API_KEY` with a stated precedence order. Codex appears in the same environment file as an alternative assistant, but the documented happy path is Claude. If your organisation has standardised on a different agent, the install story is not the one written down.

There is also an operational ceiling that the project names itself. The `.env.example` comments describe SQLite as the default at `~/.archon/archon.db` with no setup required, and recommend PostgreSQL "for heavy parallel usage (20+ concurrent workflows)". That number is the project's own guidance, and it implies that the default single-file database is not the configuration for a large parallel fleet. Anyone planning to fan out many concurrent runs should plan the database migration before, not after.

Finally, the README does not document rollback for a failed or half-finished workflow run. It describes worktree isolation and PR creation, but not what state a run leaves behind when a node fails midway.

Archon compared with a plain CI pipeline or a hand-written agent script

The closest thing to Archon is not another agent framework. It is the combination most teams already have: a shell script that calls the agent, plus a CI pipeline that runs the tests afterwards.

The difference is where the loop lives. In a CI pipeline, the agent produces a diff and the pipeline judges it once. In Archon, the validation node is inside the workflow, and the README's example workflow places `run-tests` after an `implement` loop that iterates with `until: ALL_TASKS_COMPLETE`. The agent can therefore see failing tests and retry within the same run, as the worked example shows ("Tests failing - iterating... Tests passing after 2 iterations"). A CI pipeline cannot feed that failure back into the agent because the agent has already exited.

The second difference is portability of the definition. A hand-written script lives on someone's machine or in a private dotfiles repository. Archon workflows live in `.archon/workflows/` inside the project and are committed, so the same definition is what the CLI, the web UI, Slack, Telegram and GitHub integrations execute. Whether you value that depends on how many entry points your team actually uses. If everything already goes through one terminal, the portability claim buys you less than the validation loop does.

Maintenance status, licence and what an upgrade costs

The repository is not archived, and the last push was on 2026-08-17, which is recent enough that the project is being worked on rather than parked. The release history is dense: v0.7.1 on 2026-08-04, v0.8.0 on 2026-08-06, and v0.9.0 on 2026-08-17. The root `package.json` carries version 0.10.1, which is ahead of the latest release tag listed. That gap is worth knowing before you pin anything.

That release cadence is also the upgrade cost. A project that ships three versions in two weeks will move config keys and default files. The `package.json` scripts hint at the internal surface area that changes: there are paired generate and check scripts for bundled defaults, a bundled schema, a capability matrix, a vendor map and SQLite vintages, plus a `check:schema-upgrades` script. Those checks exist because the schema and bundled artifacts do change between versions. Budget for reading the changelog before each bump rather than tracking a branch.

The licence is MIT, stated in the repository and in the LICENSE file. MIT is permissive, so modification and redistribution are permitted with the licence text retained, but this is not legal advice and the `.env.example` is the place to check what credentials the software expects you to supply. Note that Archon does not bundle Claude Code; using it means accepting Anthropic's terms for that separate component, which is a different licence question from Archon's own.

Editorial conclusion

Adopt Archon if your team already runs Claude Code and keeps losing time to agents that skip planning or forget validation, and you want those phases committed to the repository instead of living in someone's prompt history. Do not adopt it if you want a model-agnostic orchestrator, or if you cannot commit to maintaining a Claude Code installation and a Bun toolchain alongside it. Before rolling it out, verify three things on your own hardware: that `archon` resolves the Claude binary you expect, that your workflow YAML passes validation, and that a single workflow run produces the branch and PR you intended.

Frequently asked questions

Official sources

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