Archon

---

Archon is a factory builder. You describe how work should get done as YAML workflows, and Archon runs them with AI agents, scripts and your decisions in the places that need them. Software is the first factory: the bundled SDLC pack takes an issue to a merged pull request. The same engine runs any process you can describe.

Take yourself out of the loop and sit on top of it. Runs do the work, queues keep it moving, and a run comes to you only when it needs a decision you own.

Why Archon

Ask a coding agent to fix a bug and the result depends on the run. It may skip the plan, forget the tests or ignore your PR template. You end up supervising every step.

Archon turns your process into a workflow you own. The workflow fixes the steps, the checks and the gates. The agent supplies the judgment inside each step. That gives you:

• The same process every time. Plan, implement, review, validate, open the PR, in the order you wrote down.
• Human on the loop, not in it. Queues take work forward on their own. When a run reaches a decision it can't make, it pauses as one attention item: what it is, why it matters, a recommendation and the choices. You answer and it carries on.
• Governance built in. Approval gates, a full event log and transcript for every run, and the cost of every run, all stored in your own database.
• Your agents, your subscriptions. Archon is not another coding agent. It runs Claude Code, Codex and Pi through their own CLIs and SDKs, with the accounts and project guidance you already have.
• Self-hosted. One install on your machine or server. SQLite by default, PostgreSQL if you want it.

What it looks like

A workflow is a graph of nodes. Agents judge, code computes, and you decide where it matters:

# .archon/workflows/build-feature.yaml
name: build-feature
description: Plan, implement until the tests pass, ask for approval, open the PR.
nodes:
  - id: plan
    prompt: "Read the request and the code. Write an implementation plan."

  - 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

  - id: approve
    depends_on: [implement]
    wait:                                 # the run pauses and asks you
      attention: "Review the change. Approve, or reject to stop."
      form: approval

  - id: stop
    depends_on: [approve]
    when: "$approve.output.decision == 'reject'"
    cancel: "Rejected at review."

  - id: pr
    depends_on: [approve]
    when: "$approve.output.decision == 'approve'"
    prompt: "Push the branch and open a pull request."

flowchart LR
  plan["plan<br/>(agent)"] --> implement["implement<br/>(agent, loops until the tests pass)"]
  implement --> approve{"approve<br/>(waits for you)"}
  approve -- reject --> stop["stop"]
  approve -- approve --> pr["pr<br/>(agent)"]

Save it in your repository's .archon/workflows/, swap bun run test for your own test command, and run it:

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

Repository runs get their own git worktree by default, so several can work on one repository at once.

A software factory: issue in, merged PR out

The bundled sdlc pack is a working factory for a repository:

1. You open an issue. archon-intake checks it against the current code and decides what it needs: a plan, an investigation, straight to delivery, or a maintainer's look.
2. The build queue picks it up. archon-build-queue claims the next ready issue, writes the brief and runs archon-ship: plan, implement, review through specialist lenses, fix the findings, wait for CI. It stops at a pull request whose review says Ready, asking once for any check no round can run, or at one a maintainer's ready answer hands on; the merge gate checks either the same way.
3. The merge queue lands it. archon-merge-queue merges the clear ready pull requests that merge cleanly, through a gate that checks the review verdict and CI at the head commit and that the base branch is not red. The queue judges open review threads itself and sends a pull request that conflicts back to the build queue.
4. You answer what's unclear. A scope question, a schema change or a stuck round becomes one attention item with a recommendation. Your answer is written into the issue as the new scope.
5. Nothing found along the way is lost. archon-discoveries reads what runs noticed outside their task and files it, tracks it on an existing issue, or drops it.

Archon builds Archon: of the 524 pull requests merged into this repository between 1 and 19 October 2026, Archon runs built 363.

You start the queues by hand or bind them to a schedule or issue events with a trigger. The pack binds nothing by default. The pack reaches GitHub through the forge plugin (archon plugin add coleam00/Archon/plugins/forge-github); see the forge path. The SDLC factory introduces it and links its setup guide, and SDLC pack workflows describes every workflow in it.

Build any factory

Workflows are not tied to code. A node can be an agent prompt, a bash command, a script, a loop, a wait for a person or a child workflow, so any process with steps, checks and decisions fits: content production, research, operations, support. Write it as YAML, keep its commands and scripts beside it, and share it as a pack.

A reliable core, extensible at the seams

The core stays small: the workflow engine, isolation, durable state, the attention queue and an audit trail. Everything that talks to the outside world plugs in through a published contract, and you can build your own plugin for any of them:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗