Getting Started with Archon: Define Your First AI Coding Workflow in 5 Minutes

Get Archon Running in 5 Minutes — Then Build Your First AI Coding Workflow

I spent a solid 30 minutes on my first Archon setup because I missed one prerequisite. Don't be me. Here's exactly what worked, what didn't, and how to go from zero to a running workflow that plans, codes, validates, and opens a PR — all automatically.

Archon is written in TypeScript and runs on Bun, not Node. That tripped me up first. Also, you need Claude Code installed separately if you're using the compiled binary. The Docker image ships with everything pre-bundled, which is my recommended path if you just want to try it.

Prerequisites (Don't Skip This)

Install Bun

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

That's it. Add ~/.bun/bin to your PATH if the script doesn't do it automatically. Run bun --version to confirm.

Install Claude Code

curl -fsSL https://claude.ai/install.sh | bash

Install GitHub CLI

# macOS
brew install gh
# Linux
sudo apt install gh
# Then authenticate
gh auth login

Step 1: Clone and Install

git clone https://github.com/coleam00/Archon
cd Archon
bun install

What I learned the hard way: If bun install fails, check your Bun version. I was running an old 1.0.x that didn't support some lockfile features. bun upgrade fixed it instantly.

Once installed, start the guided setup:

claude

Then inside Claude Code, say: "Set up Archon"

The wizard walks through: authentication (GitHub, Claude), platform selection (CLI only or Web UI too), and copies the Archon skill to your target project. This takes about 2 minutes.

Step 2: Define Your First Workflow

Create .archon/workflows/fix-bug.yaml in your project:

nodes:
  - id: plan
    prompt: "Explore the codebase and create a fix plan"

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

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

  - id: pr
    depends_on: [validate]
    prompt: "Commit changes and create a pull request"

This is a minimal workflow: plan → implement (with loop until all tasks complete) → run tests → create PR. Each node is self-contained and the AI starts fresh at each step.

Step 3: Run It

cd /path/to/your/project
claude

Inside Claude Code:

Use archon to fix issue #42

Archon creates an isolated git worktree on a branch like archon/task-fix-issue-42, runs through your workflow nodes in order, and... you wait. Go make coffee. This takes 30-90 seconds depending on the complexity.

Going Further: Human Approval Gate

For sensitive changes, add an interactive: true node before the PR step:

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

  - id: pr
    depends_on: [approve]
    prompt: "Create the pull request"

Archon pauses at the approve node, shows you the diff, and waits for your input. Say "looks good" to continue or "change X" to iterate. This is my favorite feature — I never merge without reviewing, and now Archon doesn't either.

Quick Install Alternative (30 Seconds)

If you already have Claude Code set up and just want the CLI binary:

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

Or via Homebrew:

brew install coleam00/archon/archon

Then set your Claude binary path:

export CLAUDE_BIN_PATH="$HOME/.local/bin/claude"