Archon

Multi-agent development orchestrator powered by Claude Code.

Archon coordinates a team of specialized AI agents — frontend, backend, database, DevOps, testing, and security — that work in parallel on isolated git branches, then merges their output in a deterministic order.

How It Works

1. Write a spec — drop a markdown file into .archon/specs/requirements/
2. Run it — archon run my-feature
3. Archon decomposes the spec into tasks and assigns them to agents
4. Agents work in parallel on isolated agent/<name> branches via Claude Code subprocesses
5. Branches merge in a fixed order (dbadmin → backend → frontend → devops → security → tester)

Each agent has persistent memory (decisions, patterns, task history) that carries context across runs.

Quick Start

# Prerequisites: Node.js 20+, pnpm, git

# Clone and install
pnpm install

# Build
pnpm build

# Initialize a project
cd /path/to/your/project
archon init .

# Start the orchestrator
archon start

# Or run a single spec
archon run my-feature-spec

CLI Commands

| Command | Description | |---------|-------------| | archon init <path> | Scaffold .archon/ directory with agent configs, spec dirs, and git branches | | archon start | Start the orchestrator in foreground mode | | archon start --daemon | Start as a background daemon process | | archon stop | Stop a running daemon | | archon status | Show project config and agent status table | | archon run <spec-id> | Load a spec, decompose into tasks, and execute | | archon manifest | Generate a Slack app manifest JSON | | archon tui | Launch the interactive terminal dashboard |

Project Structure After archon init

your-project/
└── .archon/
    ├── archon.config.json          # Project configuration
    ├── agents/
    │   ├── project-manager/
    │   │   ├── agent.json          # Agent config (role, model, capabilities)
    │   │   └── memory/
    │   │       ├── context.md      # Running context notes
    │   │       ├── patterns.md     # Learned patterns
    │   │       ├── decisions.jsonl  # Decision log
    │   │       └── task-history.jsonl
    │   ├── frontend/
    │   ├── backend/
    │   ├── dbadmin/
    │   ├── devops/
    │   ├── tester/
    │   └── security/
    ├── specs/
    │   ├── requirements/           # Feature requirements
    │   ├── features/               # Feature specs
    │   ├── architecture/           # Architecture decisions
    │   └── bugs/                   # Bug reports
    └── activity/
        ├── events.jsonl            # Activity log
        └── dag.json                # Current task dependency graph

Writing Specs

Specs are markdown files with YAML frontmatter:

---
title: User Authentication
type: requirement
priority: high
status: draft
assignedAgents: [backend, frontend, security]
---

# User Authentication

Implement JWT-based authentication with login, registration, and password reset.

## Acceptance Criteria

- POST /api/auth/login returns a JWT
- POST /api/auth/register creates a new user
- Protected routes return 401 without a valid token

Place the file in .archon/specs/requirements/user-auth.md, then run:

archon run user-auth

Agent Types

| Agent | Role | Works On | |-------|------|----------| | project-manager | Decomposes specs into tasks, coordinates agents | Task planning | | frontend | UI components, styles, client-side logic | src/components/, src/pages/ | | backend | API endpoints, services, server-side logic | src/api/, src/server/ | | dbadmin | Schemas, migrations, query optimization | migrations/, src/db/ | | devops | CI/CD, Docker, infrastructure | infrastructure/, .github/ | | tester | Test writing and execution | tests/, src/**/*.test.* | | security | Code auditing, vulnerability scanning | Read-only across codebase |

Slack Integration

Archon includes a full Slack bot (Socket Mode) for team collaboration:

• /archon-status — project dashboard
• /archon-run <spec> — trigger orchestration
• /archon-agents — agent status grid
• /archon-spec <id> — view a spec
• /archon-merge — merge status and approval actions

Configure in .env:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_SIGNING_SECRET=your-signing-secret

Configuration

.archon/archon.config.json:

{
  "version": "1.0.0",
  "projectName": "my-app",
  "agents": ["project-manager", "frontend", "backend", "dbadmin", "devops", "tester", "security"],
  "defaultModel": "claude-sonnet-4-20250514",
  "mergeStrategy": "sequential",
  "maxConcurrentAgents": 3,
  "slack": {
    "botToken": "",
    "appToken": "",
    "signingSecret": "",
    "mainChannel": "archon",
    "notifyChannel": null,
    "threadPerTask": true,
    "agentChannels": false
  }
}

Development

pnpm build          # Build with tsup
pnpm dev            # Build in watch mode
pnpm test           # Run vitest test suite
pnpm lint           # TypeScript type checking

Documentation

See the docs/ directory:

• Architecture — system design and data flow
• Agents — agent configuration and memory system
• Specs & Tasks — writing specs and task lifecycle
• CLI Reference — full command reference
• Slack Bot — Slack integration setup and commands
• Configuration — all configuration options

License

MIT