$catarchon-setup.md

// Archon

Workflow orchestration for AI coding agents. Archon makes AI-driven development deterministic and repeatable using YAML-defined workflows, isolated git worktrees, and a web dashboard — powered by Claude Code under the hood.

v1.0|9 sections|terminal|free + subscription

01# Overview

Archon is an open-source workflow engine by Cole Medin that turns AI coding from unpredictable to deterministic. Instead of giving an AI agent a vague instruction and hoping for the best, you define your development process as structured YAML workflows — planning, implementation, validation, PR creation — and Archon executes them repeatably every time.

Think of it as CI/CD for AI-assisted development: you define the pipeline, Archon runs it with Claude Code as the execution engine.

YAML Workflows

Define dev processes as version-controlled, repeatable pipelines

Git Worktree Isolation

Every run gets an isolated branch — no conflicts with main

Hybrid Nodes

AI reasoning, deterministic bash, loops, and human approval gates

Web Dashboard

Visual workflow builder, chat interface, and execution monitor

Claude Code Powered

Uses Claude Code as the underlying AI coding agent

Auto PR Creation

Generates pull requests with clean diffs when workflows complete

02# Prerequisites

Before installing Archon, make sure you have the following tools ready:

Bun

bun --version

JavaScript runtime used by Archon. Install from bun.sh

Claude Code

claude --version

The AI coding agent that powers Archon workflows. Requires a Claude subscription.

GitHub CLI (gh)

gh --version

Required for repository management and PR creation.

bash

# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Install GitHub CLI
# macOS:
brew install gh

# Ubuntu/Debian:
sudo apt install gh

# Authenticate with GitHub:
gh auth login

⚠️Claude Subscription Required

Archon uses Claude Code as its execution engine. You need an active Claude subscription (Pro, Team, or Enterprise) for Claude Code to work. No separate API key is needed — just your subscription.

03# Installation

There are two installation paths. Choose based on your needs:

A. Quick Install (CLI only)

If you already have Claude Code configured and just want the standalone CLI:

quick-install.sh

bash

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

# Windows (PowerShell):
irm https://archon.diy/install.ps1 | iex

# Or via Homebrew:
brew install coleam00/archon/archon

B. Full Install (Recommended)

For the complete experience with web dashboard, project integration, and guided setup:

full-install.sh

bash

# Clone the repository
git clone https://github.com/coleam00/Archon
cd Archon

# Install dependencies
bun install

📌Binary Path

If using compiled binaries (quick install), make sure CLAUDE_BIN_PATH is exported or configured in ~/.archon/config.yaml to point to your local Claude Code binary.

04# Full Project Setup

After the full install, run Claude Code inside the Archon directory to trigger the interactive setup wizard:

setup-wizard.sh

bash

# Inside the Archon directory:
claude

# When prompted, say:
# "Set up Archon"

The guided wizard walks you through:

CLI installation and authentication

Platform selection and configuration

Copying the Archon skill into your target repository

Setting up credentials and environment

💡Project Skill

The setup copies an Archon "skill" into your project's repository. This skill tells Claude Code how to find and execute your workflows. Once installed, you can use Archon from any project directory.

05# YAML Workflows

Workflows are the heart of Archon. They live in .archon/workflows/ and define your development process as a Directed Acyclic Graph (DAG) of nodes.

Node Types

AI Nodes

Reasoning and coding powered by Claude — planning, implementation, code review

Deterministic Nodes

Bash commands — run tests, linters, build steps with predictable output

Loop Nodes

Iterate on implementation until validation passes (e.g., fix → test → repeat)

Interactive Nodes

Human-in-the-loop approval gates — pause and wait for sign-off

Example Workflow

.archon/workflows/feature.yaml

yaml

# .archon/workflows/feature.yaml
name: feature-development
description: Plan, implement, test, and create PR

nodes:
  - id: plan
    type: ai
    prompt: |
      Analyze the feature request and create
      a detailed implementation plan.

  - id: implement
    type: ai
    depends_on: [plan]
    prompt: |
      Implement the feature based on the plan.
      Follow existing code patterns.

  - id: test
    type: bash
    depends_on: [implement]
    command: npm test

  - id: review-loop
    type: loop
    depends_on: [test]
    max_iterations: 3
    nodes:
      - id: fix
        type: ai
        prompt: Fix any failing tests.
      - id: retest
        type: bash
        command: npm test

  - id: create-pr
    type: ai
    depends_on: [review-loop]
    prompt: Create a PR with a clean description.

💡Version Control

Workflow YAML files live in your repo and are version-controlled alongside your code. Changes to workflows go through the same PR process as code changes.

06# Web Dashboard

Archon includes a web-based dashboard for visual workflow management. If you used the binary install, start it with:

bash

# Start the web dashboard
archon serve

# The dashboard opens at http://localhost:3000
# (port may vary — check the terminal output)

The dashboard gives you:

→

Visual drag-and-drop workflow builder

→

Chat interface for natural language interaction

→

Execution monitor showing live workflow progress

→

Run history with logs and diffs

📌Full Install Dashboard

If you used the full install (cloned the repo), the dashboard is already part of the monorepo. Run bun dev in the Archon directory to start it.

07# Usage & Commands

Once Archon is set up in your project, usage is natural-language driven through Claude Code:

bash

# Navigate to your project
cd my-project

# Start Claude Code — Archon skill is auto-detected
claude

# Describe what you want to build:
# "Add a user settings page with dark mode toggle"
#
# Archon automatically:
# 1. Selects the appropriate workflow
# 2. Creates an isolated worktree branch
# 3. Executes the workflow nodes
# 4. Opens a PR when done

CLI Commands

bash

# List available workflows
archon list

# Run a specific workflow
archon run feature-development

# Start the web dashboard
archon serve

# Check Archon version and config
archon info

08# Git Isolation

One of Archon's strongest features: every workflow run gets its own isolated git worktree. This means:

✓

Your main branch is never touched during AI execution

✓

Multiple workflows can run in parallel without conflicts

✓

Failed runs can be discarded cleanly — no messy rollbacks

✓

Completed runs produce clean PRs with isolated diffs

git-isolation.sh

bash

# Under the hood, Archon does:
git worktree add .archon/runs/<run-id> -b archon/<workflow>/<timestamp>

# After completion, if successful:
gh pr create --title "feat: <description>" --body "<auto-generated>"

# The worktree is cleaned up automatically

💡Safe Experimentation

Because of worktree isolation, you can let Archon run experimental or risky tasks without worrying about breaking your working branch. If it fails, nothing changes.

09# Best Practices

Start with simple workflows

Begin with a basic plan → implement → test pipeline before adding loops and approval gates. Get comfortable with the YAML structure first.

Always include validation nodes

Add deterministic bash nodes (tests, linters, type checks) after AI implementation nodes. This catches errors before they reach your PR.

Use loop nodes with max_iterations

When an AI fix-and-test loop is needed, always set a max_iterations cap (3-5 is reasonable) to prevent infinite loops.

Version control your workflows

Treat .archon/workflows/ like any other code — review changes in PRs, document workflow decisions, keep them in sync with your codebase.

Add human approval for critical paths

For workflows that touch production configs, database migrations, or security-sensitive code, add interactive approval nodes.

Review AI-generated PRs carefully

Archon creates clean PRs, but always review the diff. The AI is a tool, not a replacement for code review.

💡Learn More

Check out the Archon documentation at archon.diy and the source code at github.com/coleam00/Archon. Cole Medin also has a video walkthrough covering the full setup and workflow concepts.