Archon for Beginners: Git Worktrees for Isolation + DAG Workflows, Taming Uncertainty in AI Coding

Beginner-friendly | About 20 minutes | You’ll learn Archon’s core concepts (Worktree isolation, DAG node types, YAML workflow syntax), installation and setup, and practice 3 common real-world workflows

---

Project Overview

First, let’s face a truth: if you ask an AI to fix a bug, it might also change things you never intended to touch; if you ask it to add a feature, it may get one run working and then go off track the next time you say the same thing; if you ask it to write a PR, every description comes out in a different style.

These aren’t signs of the AI “messing around on purpose”—it’s that the whole process lacks structure. The AI receives a vague instruction, and the output depends entirely on the model’s mood and the context at that moment.

What Archon does is add structure to AI coding. It uses YAML to define your development workflow—planning, validation, code review, and PR creation—spelling out what happens in each step, what it depends on, and when a step counts as complete. Then it puts the AI into that framework so it can improvise within structure, rather than wandering all over the place.

Its other core capability is Git Worktree isolation: each workflow runs in its own isolated git branch and working directory, so even if 5 tasks run in parallel, they won’t step on each other. When tasks are done, Archon merges back to the main branch; if tasks fail, it simply deletes the Worktree—clean and tidy.

---

Target Audience

• Developers using Claude Code or Codex
• Teams that need to standardize AI coding workflows
• Anyone who wants AI output to be repeatable and reviewable

Core Dependencies and Environment

• Bun
• Git
• Claude Code (CLI)
• GitHub CLI (required for full installation)

Complete Project Directory Structure

.archon/                     # Project-level (generated by the setup wizard)
├── commands/                # Custom commands (Markdown files)
├── workflows/               # Custom workflows (YAML)
│   └── defaults/            # Built-in workflow templates
└── config.yaml              # Project configuration (assistant model, etc.)

~/.archon/                   # User-level global config
├── workspaces/owner/repo/  # Isolated environment organized by GitHub user/repo
│   ├── source/             # Repo clone or local path
│   ├── worktrees/          # Git Worktree isolation directory
│   └── artifacts/          # Workflow outputs (not committed to git)
└── config.yaml             # Global configuration

---

Step-by-Step Guide

Step 1: Install Archon

There are two installation methods—pick the one that fits your situation.

Method 1: Full installation (recommended, ~5 minutes)

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

Then tell Claude Code: "Set up Archon". It will launch an interactive guided setup, help you configure GitHub credentials, choose platform integrations, test the connection, and finally copy Archon skill files into your target project.

Method 2: Quick installation (~30 seconds, already have Claude Code)

# 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

Quick installation only installs the CLI. It won’t automatically configure credentials and workflows into your project—you’ll need to complete initialization manually.

Step 2: Run the Setup Wizard (for full-install users)

If you used the full installation, the setup wizard will guide you through these steps:

1. CLI installation — install the archon binary into your PATH
2. GitHub authentication — run gh auth login so Archon has permission to operate on your repo
3. Platform selection — whether to connect Telegram / Slack / Discord (optional)
4. Target project — select the project directory to register; the wizard copies the .archon/ skill files into it

After that, your target project will include:

.archon/
├── commands/       # Command files callable by AI
└── workflows/      # Workflow definitions

Step 3: Initialize the target project

If you used quick installation, you’ll need to initialize manually:

cd your-project
archon init
# Or in Claude Code: "Use archon to set up"

After initialization, verify:

archon workflow list
# You should see 17 built-in workflows

Step 4: Understand the YAML workflow structure

An Archon workflow is a DAG (Directed Acyclic Graph). Each node is an execution step. Dependencies between nodes are declared via depends_on. Archon executes nodes in topological order—nodes without dependencies can run in parallel.

A full workflow looks like this:

# .archon/workflows/my-feature.yaml
nodes:
  # Node 1: Planning (no dependencies, runs directly)
  - id: plan
    prompt: "Explore the codebase and draft an implementation plan"

  # Node 2: Implementation (depends on plan)
  - id: implement
    depends_on: [plan]
    loop:                                    # AI loop node
      prompt: "Read the plan, implement the next task, run validation"
      until: ALL_TASKS_COMPLETE
      fresh_context: true                    # Use a new AI session every loop

  # Node 3: Run tests (depends on implement; bash node, deterministic execution)
  - id: run-tests
    depends_on: [implement]
    bash: "bun run validate"

  # Node 4: Code review (depends on tests passing)
  - id: review
    depends_on: [run-tests]
    prompt: "Review all changes against the plan and fix any issues"

  # Node 5: Manual approval (interactive gate)
  - id: approve
    depends_on: [review]
    loop:
      prompt: "Show the changes and respond to any feedback"
      until: APPROVED
    interactive: true                        # Pause and wait for human input

  # Node 6: Create PR
  - id: create-pr
    depends_on: [approve]
    prompt: "Push the code and create a Pull Request"

Node types at a glance:

Step 5: Practice — From a GitHub Issue to a PR

This is one of the most common workflows: input a GitHub Issue and output a PR.

In Claude Code, just say:

Use archon to fix issue #42

Archon will automatically:

1. Create an isolated Worktree branch (archon/fix-42-xxx)
2. Run the archon-fix-github-issue workflow: classify the issue → investigate → plan → implement → validate → create PR
3. If tests fail, automatically enter the self-fix loop
4. Operate inside the Worktree so it won’t affect your local main branch

What you’ll see roughly looks like this:

→ Creating isolated worktree on branch archon/fix-42-abc...
→ Planning...
→ Investigating issue #42...
→ Implementing (task 1/3)...
→ Implementing (task 2/3)...
→ Tests failing - iterating...
→ Tests passing after 2 iterations
→ Code review complete - 0 issues
→ PR ready: https://github.com/you/project/pull/47

Step 6: Practice — From an Idea to a PR

If you don’t have an existing Issue—just an idea:

Use archon to add dark mode to the settings page

Archon uses the archon-idea-to-pr workflow:

→ Feature idea → plan → implement → validate → PR → 5 parallel reviews → self-fix

Along the way, the AI will:

1. Explore the codebase first to understand the current architecture
2. Draft an implementation plan (you can step in mid-way to modify it)
3. Use loop nodes to implement repeatedly until all tasks are complete
4. Run validation (bun run validate)
5. Run 5 code-review Agents in parallel (style, safety, performance, maintainability, docs)
6. Apply self-fix based on review feedback
7. Create the PR and attach a complete review summary

Step 7: Write a Custom Workflow

The built-in workflows are a great starting point—copy one and edit it:

cp .archon/workflows/defaults/archon-feature-development.yaml \
   .archon/workflows/my-feature.yaml

Then edit the YAML file. For example, if you want to remove the manual approval step and merge automatically:

# .archon/workflows/my-feature.yaml
nodes:
  - id: plan
    prompt: "Analyze requirements and draft an implementation plan"

  - id: implement
    depends_on: [plan]
    loop:
      prompt: "Read the plan, implement the next task, and mark it complete"
      until: ALL_TASKS_COMPLETE
      fresh_context: true

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

  - id: create-pr
    depends_on: [run-tests]
    prompt: "Push the code, create a Pull Request, using the following template: ..."

Variable substitution: workflows can use these built-in variables:

- id: log-context
  bash: "echo $WORKFLOW_ID $ARTIFACTS_DIR $BASE_BRANCH"

• $1, $2, $3 — positional parameters
• $ARGUMENTS — all parameters
• $ARTIFACTS_DIR — the output directory for the current workflow run
• $WORKFLOW_ID — workflow run ID
• $BASE_BRANCH — main branch name
• $LOOP_USER_INPUT — human feedback entered at the approval gate

Step 8: Web UI + Multi-platform Integration

Archon isn’t just a CLI—it also comes with a full Web Dashboard. Quick start:

archon serve
# Download the Web UI (first time), then launch at http://localhost:4000

The Web UI provides:

• Chat page — real-time AI chat with streaming output and tool calls
• Dashboard — monitor the run status of all workflows (from all platforms: CLI, Slack, Telegram, etc.)
• Workflow Builder — a visual DAG editor to create workflows via drag-and-drop
• Workflow Execution — step-by-step inspection of any workflow’s execution

Chat platform integrations (optional):

After integration, you can trigger workflows directly from Slack or Telegram, and the results will be pushed in real time into the same conversation.

---

Troubleshooting

1. Claude Code can’t find the Archon command

This usually happens after a quick install without running the setup wizard:

# Re-run setup
cd your-project
claude
# Say "Set up Archon" or "Use archon to set up"

# Or update skill files manually
archon update

2. Worktree creation fails

The most common causes are insufficient disk space or permission issues:

# Check disk space
df -h

# Check git version (Worktree requires 2.23+)
git --version

# Manually clean up old Worktrees
archon isolation cleanup

3. Workflow list is empty

# Confirm the .archon/workflows/ directory exists
ls .archon/workflows/

# Discover and trigger workflows manually
archon workflow list --verbose

If built-in workflows are also missing, check your Archon version:

archon --version

4. YAML node dependency cycles

If depends_on creates a cycle, Archon will error:

Error: Circular dependency detected in workflow

Fix: check the YAML file to ensure no nodes depend on each other—specifically, don’t point a node’s depends_on to itself or to its downstream nodes.

5. Interactive Approval Gate doesn’t respond in the CLI

The Approval Gate requires human intervention. In the CLI, the workflow pauses and waits for input:

Workflow paused: awaiting approval
Type /workflow approve <run-id> [comment] to approve
Type /workflow reject <run-id> <reason> to reject

If you run from the Web UI, nodes with interactive: true will automatically show approval buttons.

6. PostgreSQL vs SQLite switching

Archon uses SQLite by default (zero config). Data is stored in ~/.archon/archon.db. If you want to switch to PostgreSQL:

# Start PostgreSQL (Docker)
docker-compose --profile with-db up -d postgres

# Set the connection string in .env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/archon

# Restart Archon
archon serve

---

Further Reading / Advanced Directions

Detailed guide to the 17 built-in workflows: Archon provides a complete toolchain ranging from everyday assistance (archon-assist) to complex reviews (archon-comprehensive-pr-review). In particular, archon-refactor-safely includes type-check hooks, archon-architect performs architecture health scans, and archon-ralph-dag supports PRD iteration implementations.

Custom Node Types: In addition to built-in nodes, you can write command: to call a custom command file (Markdown), script: to run TypeScript/Python scripts (supporting deps: for dependency installation and timeout: for timeouts), and approval: to define custom human-approval flows.

Adapter development for platforms: Archon’s adapter layer (IPlatformAdapter) supports connecting any chat platform. Check the implementations under packages/adapters/src/ (Slack, Telegram, Discord) and you can integrate other domestic platforms like WeCom and Feishu.

Deep dive into Archon’s architecture: the core is the DAG execution engine in the @archon/workflows package (dag-executor.ts) plus the Orchestrator in @archon/core (message routing and session management). Workflow YAML is parsed and validated via loader.ts, dependencies are used to build the topology graph via depends_on, and then nodes run in topological order.

Standardizing workflows for teams: commit .archon/workflows/ to Git. After each team member clones, they automatically receive the same workflow definitions. Combined with .archon/config.yaml to inject the team’s coding standards, all content generated by the AI will follow the team’s agreements.