Archon: YAML Workflow Engine for Deterministic AI Coding Agents

Archon is an open-source workflow engine for AI coding agents. It addresses the non-determinism of LLM-based agents by defining development processes as YAML Directed Acyclic Graphs (DAGs): explicit, ordered sequences of steps the agent must follow. Each workflow runs in an isolated Git worktree, preventing merge conflicts when multiple agents work on the same repository. Reusable skills package workflows for specific tasks so process knowledge persists in version-controlled files rather than ephemeral chat logs.

The problem Archon addresses

AI coding agents powered by LLMs produce probabilistic output. Running the same prompt twice can yield different code logic, different approaches to edge cases, and different quality.

This inconsistency prevents building reliable development pipelines around raw agents. A further problem is context drift: as a conversation progresses, the agent's understanding of the original goal can shift, causing it to abandon a workable approach mid-task.

Scaling to multiple agents introduces merge conflicts. Two agents working on the same repository without isolation overwrite each other's changes, leaving a codebase in disarray.

Core components

YAML DAG workflows

Workflows are defined in YAML as Directed Acyclic Graphs: sequences of steps where each step can depend on prior steps but the graph does not loop. There are two step types.

Fixed steps run deterministic shell commands such as git diff, pytest tests/, or ls -l. For the same input they always produce the same output, providing reliable checks and actions.

AI steps call a language model for tasks requiring judgment: writing code (implement), reviewing existing code (review_code), or summarizing changes (write_summary).

Mixing fixed and AI steps prevents context drift and keeps the agent on track through the entire task.

Git worktree isolation

Every workflow run gets its own Git worktree: a separate directory containing a separate branch checkout, sharing the same underlying .git database. Agents operating in separate worktrees cannot overwrite each other's files, making merge conflicts impossible regardless of how many agents run in parallel. Completed work is presented as a clean branch ready for pull request and review.

Skills

Skills are pre-packaged instruction sets that map to specific workflows. When prompted to use a named skill such as fix-local-issue, the agent detects the reference, loads the associated workflow, and executes it. This removes the need to include extensive process context in every prompt. The knowledge of how to perform a task lives in the skill's workflow file, version-controlled alongside the codebase.

Installation

On macOS and Linux:

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

On macOS with Homebrew:

brew install colean-ai/archon/archon

On Windows via PowerShell:

irm https://archon.sh/install.ps1 | iex

Set API keys for the models Archon will use:

export ANTHROPIC_API_KEY="your-api-key-here"

Launch the local web UI from a project directory:

archon serve

This opens the Archon Mission Control dashboard in the browser.

Example: fixing a bug with a workflow

The following example uses Archon to fix a ZeroDivisionError in a Python calculator script. The prompt instructs the agent to use a specific skill:

The calculator.py file has a bug. The divide() function crashes on zero. Fix this by adding proper ZeroDivisionError handling. Also improve the subtract() function if needed and add proper tests to cover all edge cases. Use the fix-local-issue workflow to manage this.

Archon identifies the fix-local-issue skill reference, loads the associated workflow, and begins execution.

The fix-local-issue workflow executes its predefined steps in order:

1. Read calculator.py to understand the current code (fixed step)
2. Modify the divide function to include ZeroDivisionError handling and create test_calculator.py (AI step)
3. Run pytest to confirm the fix and check for regressions (fixed step)
4. Generate a summary of changes made and tests added (AI step)

The workflow graph view

The Archon UI displays the workflow as a connected graph of nodes, one per step. Completed steps show a checkmark; failed steps are marked in red.

Each step exposes the full prompts sent to the LLM, the raw model output, shell commands and their output, file diffs, and test results. This audit trail makes it straightforward to diagnose workflow definition errors: once a workflow is fixed, the fix applies to all future runs.

Summary of advantages

Workflows defined in YAML produce consistent outputs because the agent follows the same process each time. Git worktree isolation makes parallel agent execution safe. Skills and workflow files are version-controlled assets that accumulate institutional knowledge instead of being lost in chat history. The UI and logging provide full observability into agent behavior.

When to use Archon

Archon requires upfront investment in workflow design. For simple one-shot prompts, it is unnecessary overhead. Its value emerges in multi-step, multi-agent processes common in professional software development: feature implementation, bug fixing pipelines, code review automation, and CI/CD integration.

The quality of AI step outputs still depends on the underlying model. Archon provides structure; model capability determines how well the agent executes within that structure.

Documentation and workflow examples are available at archon.sh and github.com/colean-ai/archon.

Got an article suggestion? Let us know

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.