Archon: YAML workflows for deterministic AI coding agents

Introduction

Archon is an open-source workflow engine for AI coding agents: you describe multi-step development flows in YAML (planning, implementation, tests, review, opening a PR), check those definitions into the repo, and run the same graph from the CLI, web UI, or integrations such as Slack, Telegram, Discord, and GitHub. The project bills itself as a way to make agent-assisted coding deterministic and repeatable—same sequence every time, with explicit gates where humans approve or where scripts run without the model (GitHub: coleam00/Archon, site).

This post is a concise tour of what the maintainers document today: why structured workflows matter, how a workflow file is shaped, what ships by default, and what to expect from setup and telemetry. It is not a substitute for the full documentation or CLI reference.

Hero image: project logo from upstream assets/logo.png (MIT-licensed repository).

The problem Archon targets

Ad-hoc prompts to an agent are brittle: one run might skip planning, another might forget validation, and PR descriptions may ignore your team template. Archon’s pitch is to own the process as data—workflows live under .archon/workflows/ (and commands under .archon/commands/), so the order of steps and validation is stable while the model supplies judgment inside each step (README).

The analogy the project uses is deliberately infrastructural: like Dockerfiles for environments or GitHub Actions for CI, but for agent orchestration—with a nod to n8n-style DAGs, applied to software delivery (README).

Core ideas: repeatability, isolation, composition

From the README and landing page, the design stresses:

• Repeatable graphs — Dependencies, loops, and conditional structure live in YAML; runs follow that graph instead of improvising.
• Git worktrees — Each workflow run gets an isolated worktree, which is how the project supports parallel efforts (several fixes or features) without stepping on the same working tree (README).
• Mixed nodes — AI nodes (prompt-driven) sit beside deterministic nodes (e.g. bash for tests or scripts). The model is not required where a command suffices (README).
• Portability — Same workflow files are meant to run from CLI, Web UI, or connected chat platforms after setup; the README links per-platform guides (for example Telegram and Slack) (README).

The site also highlights multi-provider assistant support (e.g. Claude Code SDK and Codex SDK); assistant-specific setup is covered under AI assistants.

What a workflow looks like

Workflows are YAML lists of nodes with id, optional depends_on, and either a prompt (AI step), bash (shell), or control structures such as loop. The README’s example chains plan → implement (loop) → tests → review → human approval (interactive loop) → create PR (README):

Copy
# .archon/workflows/build-feature.yaml (illustrative; see upstream for full semantics)
nodes:
  - id: plan
    prompt: "Explore the codebase and create an implementation plan"

  - id: implement
    depends_on: [plan]
    loop:
      prompt: "Read the plan. Implement the next task. Run validation."
      until: ALL_TASKS_COMPLETE
      fresh_context: true

  - id: run-tests
    depends_on: [implement]
    bash: "bun run validate"

  - id: review
    depends_on: [run-tests]
    prompt: "Review all changes against the plan. Fix any issues."

  - id: approve
    depends_on: [review]
    loop:
      prompt: "Present the changes for review. Address any feedback."
      until: APPROVED
      interactive: true

  - id: create-pr
    depends_on: [approve]
    prompt: "Push changes and create a pull request"

Authoring details—every supported key, loop until values, and overrides—belong in the project’s Authoring Workflows guide; treat the snippet as illustrative, not an exhaustive schema.

Getting started (high level)

The README describes two entry paths (README):

1. Full setup — Clone the repo, install Bun, use Claude Code and the GitHub CLI as documented, run bun install, then invoke the guided “Set up Archon” flow in Claude. That path configures credentials, optional platforms, and copies the Archon skill into target projects.
2. Quick install — Standalone CLI via install scripts or Homebrew (brew install coleam00/archon/archon), as listed on archon.diy and the README. Compiled binaries expect a separate Claude Code install and a CLAUDE_BIN_PATH (or assistants.claude.claudeBinaryPath in ~/.archon/config.yaml); the Docker image is documented as shipping Claude pre-installed (README).

Operational note repeated in the README: run Claude Code from your application repo, not from the Archon repo, after the skill is installed there (README).

Web UI: archon serve (binary installs) or bun run dev from source starts the dashboard—project registration, chat, workflow builder, and execution progress (README).

Bundled workflows and customization

The README lists many default workflows (issue → PR, idea → PR, PR review pipelines, conflict resolution, refactor loops, etc.) and states there are 17 shipped defaults, discoverable with archon workflow list (README). You can copy from .archon/workflows/defaults/ and override by placing same-named files in your repository (README).

Architecture and persistence (documented)

The README’s architecture diagram shows platform adapters feeding an orchestrator, then command, workflow, and AI assistant paths, persisting to SQLite or PostgreSQL with seven tables (codebases, conversations, sessions, workflow runs, isolation environments, messages, workflow events) (README). For internals beyond that summary, see Architecture.

Telemetry and privacy

Archon documents anonymous telemetry: a single workflow_invoked event per workflow start, including workflow name, workflow description (from your YAML), triggering platform, Archon version, and a random install id—no code, prompts, tokens, or detailed node payloads (README). Opt-out is via ARCHON_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1 (README).

Historical note: the “v1” branch

If you encounter older write-ups about a Python-based Archon focused on task management and RAG, that codebase is preserved on the branch archive/v1-task-management-rag, while the current product is the TypeScript/Bun workflow engine described above (README).

When Archon is (and is not) the right abstraction

Archon fits teams that want shared, reviewable playbooks for agent work—especially when parallel worktrees, mixed shell and LLM steps, and cross-surface triggers (CLI + web + chat) matter. It is still a heavyweight orchestration layer: you accept YAML authoring, local or deployed services, and assistant credentials management as the price of repeatability.

For a contrasting take on terminal-native harnesses (smaller scope, different goals), you might compare with our notes on Pi as a minimal terminal coding harness or Terax—complementary topics, not direct substitutes.

Conclusion

Archon encodes AI coding workflows as YAML, runs them in isolated git worktrees, and exposes them through CLI, web, and optional chat adapters, with documented support for Claude Code-style assistants and Codex. Defaults cover common issue → PR and review flows; customization is repo-local under .archon/. For install specifics, adapter setup, and exact workflow keys, use archon.diy and the GitHub repository as the source of truth—especially if you are reading this after mid-2026, when flags and workflow names may have evolved.