Archon 快速入门

What is Archon?

Archon is an open-source AI coding workflow engine that makes AI programming deterministic and repeatable.

Its core idea: encode the software development process (planning, implementation, verification, code review, PR creation) into YAML workflow files, defining phases, validation gates, and artifacts. AI fills in the intelligence at each step, but you control the overall structure.

Archon’s positioning analogy:

• Dockerfiles changed infrastructure
• GitHub Actions changed CI/CD
• Archon changes AI coding workflows

For AI coding, Archon is like n8n (but for software development): combining deterministic nodes (bash scripts, tests, git operations) with AI nodes (planning, code generation, review).

Core Features

• 🏗️ Workflow Engine: YAML-defined, DAG execution, supports bash/prompt/command/loop nodes
• 🔄 AI Loop: fresh_context: true avoids token accumulation
• 🌿 Git Worktree Isolation: Run multiple workflows in parallel, zero branch conflicts
• 👤 Human-in-the-loop Gates: Supports Slack, Telegram, GitHub Webhooks for approval
• 📡 Multi-platform Adapters: Web UI, CLI, Telegram, Slack, GitHub Webhooks, Discord
• 📦 17 Built-in Workflows: Covering the complete flow from idea to PR

Getting Started

Prerequisites

Tool	Install
Bun	curl -fsSL https://bun.sh/install | bash
Claude Code	curl -fsSL https://claude.ai/install.sh | bash
GitHub CLI	brew install gh (macOS)

Installation

Option 1: Full Install (5 min)

git clone https://github.com/coleam00/Archon
cd Archon
bun install
claude
# In Claude Code, type: "Set up Archon"

Option 2: Quick Install (30 sec)

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

# Homebrew
brew install coleam00/archon/archon

First Example

cd /path/to/your/project
claude

Then tell it:

Use archon to add dark mode to the settings page

Archon automatically completes:

→ Creating isolated worktree on branch archon/task-dark-mode...
→ Planning...
→ Implementing (task 1/4)...
→ Tests passing after 2 iterations
→ Code review complete - 0 issues
→ PR ready: https://github.com/you/project/pull/47

Common Usage

Built-in Workflows Reference

Workflow	Use Case
archon-assist	General Q&A, debugging, code exploration
archon-fix-github-issue	End-to-end issue fixing
archon-idea-to-pr	Idea → PR (with 5 parallel reviews)
archon-smart-pr-review	Smart PR review by complexity
archon-architect	Architecture optimization
archon-refactor-safely	Safe refactoring with type checks

Viewing Available Workflows

What archon workflows do I have? When would I use each one?

Starting Web UI

archon serve    # or from source
bun run dev

Advanced Topics

Workflow File Structure

.archon/
├── workflows/          # Custom workflow YAML
│   └── defaults/       # Built-in default workflows
├── commands/           # Reusable AI command Markdown
│   └── defaults/
├── config.yaml         # Project-level config
└── (artifacts: worktrees/, outputs/)

YAML Workflow Node Types

nodes:
  # Bash Node - Deterministic command
  - id: run-tests
    bash: "bun run validate"

  # Prompt Node - AI generation
  - id: plan
    prompt: "Explore the codebase and create an implementation plan"

  # Loop Node - AI loop
  - id: implement
    depends_on: [plan]
    loop:
      prompt: "Read the plan. Implement the next task. Run validation."
      until: ALL_TASKS_COMPLETE
      fresh_context: true

  # Interactive Node - Human approval
  - id: approve
    depends_on: [review]
    loop:
      prompt: "Present the changes for review."
      until: APPROVED
      interactive: true

Configuration

workflows:
  default_model: claude-sonnet-4-7b
  max_iterations: 10

isolation:
  auto_cleanup: true
  branch_prefix: archon/

platforms:
  github:
    auto_create_pr: true

Deployment

Method	Description
Docker Compose	Production recommended
Cloud Server	cloud-init support
Binary	archon serve for Web UI

Best Practices

1. Small nodes first: Each node should do one thing, easy to debug and retry
2. Use bash nodes over AI nodes: For tests, lint, build — deterministic tasks don’t need AI
3. Always set validation gates: Add bash: "bun run validate" after implementation nodes
4. Use fresh_context: true: Avoid token accumulation in long loops
5. Leverage worktree isolation: Run multiple workflows in parallel on different branches
6. Use PostgreSQL in production: SQLite for development, PostgreSQL for teams

FAQ

Q: What’s the difference between Archon and Claude Code?

A: Claude Code is an AI coding assistant. Archon is a structured workflow engine that adds deterministic execution, DAG orchestration, and parallelization on top of Claude Code.

Q: Does it support AI models other than Claude Code?

A: Officially supports Claude Code SDK and Codex SDK (OpenAI).

Q: How to troubleshoot workflow failures?

A: Use archon workflow view <run-id> to check detailed logs. Verify bash node commands work locally and GitHub token has sufficient permissions.

Next Steps

• Official Docs — Complete documentation
• The Book of Archon — 10-chapter tutorial
• GitHub Repository — Source code and examples