coleam00/Archon

Archon – Deterministic AI‑Coding Workflows

What it is – Archon is an open‑source workflow engine that lets you orchestrate AI‑assisted software‑development tasks (bug‑fixes, feature implementation, code review, PR creation, etc.) in a repeatable, isolated, and composable way. You describe a development process as a YAML workflow; Archon runs the steps, invoking an LLM only where you need intelligence, while the rest (bash scripts, tests, git operations) stays deterministic.

Key ideas

• Deterministic runs – The same workflow always follows the same sequence, eliminating the “model mood” problem.
• Isolation – Each run gets its own Git worktree, allowing parallel executions without conflicts.
• Human‑in‑the‑loop – Loops can pause for approval or feedback, mixing AI and manual steps.
• Portability – Workflows live in a project’s .archon/workflows/ folder and can be triggered from the CLI, a web UI, or chat platforms (Slack, Telegram, Discord, GitHub webhooks).

Typical workflow (simplified):

nodes:
  - id: plan        # AI generates a plan
    prompt: "Explore the codebase and create an implementation plan"
  - id: implement   # AI iterates until tasks are done
    depends_on: [plan]
    loop:
      prompt: "Read the plan. Implement the next task. Run validation."
      until: ALL_TASKS_COMPLETE
      fresh_context: true
  - id: run-tests   # deterministic bash step
    depends_on: [implement]
    bash: "bun run validate"
  - id: review      # AI reviews changes
    depends_on: [run-tests]
    prompt: "Review all changes against the plan. Fix any issues."
  - id: approve     # human approval gate
    depends_on: [review]
    loop:
      prompt: "Present the changes for review. Address any feedback."
      until: APPROVED
      interactive: true
  - id: create-pr   # AI creates the PR
    depends_on: [approve]
    prompt: "Push changes and create a pull request"

Running archon-ship on an issue will automatically:

1. Create an isolated branch/worktree
2. Plan, implement (looping until tests pass), review, wait for human approval, and finally open a PR.

Installation & getting started

• Full setup (≈5 min) – Clone the repo, run bun install, install Claude Code, then run archon and follow the interactive wizard (sets up credentials, copies the Archon skill into your target repo, etc.).
• Quick install (≈30 s) – If Claude Code is already installed, you can fetch a pre‑compiled binary:

  curl -fsSL https://archon.diy/install | bash   # macOS/Linux
  # or PowerShell on Windows
  irm https://archon.diy/install.ps1 | iex
  

  (Homebrew formula also available.)
• Run a workflow – Inside a project directory: archon workflow run archon-ship or simply ask the assistant: Use archon to fix issue #42.

Web UI – archon serve launches a console where you can browse runs, view workflow graphs, chat with the assistant, and manage projects. Adapters for Slack, Telegram, Discord, and GitHub webhooks let you trigger runs from those platforms.

Built‑in workflow packs – The sdlc pack ships ready‑made workflows such as:

• archon-ship – end‑to‑end issue → PR
• archon-triage, archon-investigate, archon-plan, archon-implement, archon-review, archon-validate, archon-upkeep You can list them with archon workflow list and customize or author your own YAML workflows.

Architecture snapshot

Platform adapters (Web UI, CLI, Slack, …) → Orchestrator →
   Command handler, Workflow executor, AI assistant clients (Claude, Codex, Pi)
   ↕
   SQLite / PostgreSQL persistence (runs, projects, sessions, etc.)

Telemetry – Archon sends anonymous usage events (workflow name, outcome, node counts, provider/model IDs, cost, etc.) but never any code, prompts, or personal data. Telemetry can be disabled via ARCHON_TELEMETRY_DISABLED=1 or standard DO_NOT_TRACK.

Who might use it – Developers who rely on LLMs for code generation and want a reproducible, CI‑like pipeline; teams looking to embed AI assistants into their existing development workflow without sacrificing auditability or repeatability.

---

TL;DR – Archon is a deterministic, Git‑aware workflow engine that lets you script AI‑assisted development steps in YAML, run them from the CLI or chat platforms, and get reliable PRs without the randomness that usually comes with “let the AI fix the bug.”