Turn one Claude Code session into a multi-agent fleet.
Claude Code is powerful — but it works one task at a time. One agent, one context window, one thread of execution.
Legio changes that. It spawns specialized agents in isolated git worktrees, coordinates them through a typed SQLite messaging system, and merges their work back automatically. Your session becomes the orchestrator. The agents do the work in parallel.
- Parallel execution — 5-10 agents working simultaneously, each in its own tmux session
- Conflict-free isolation — every agent in its own git worktree with exclusive file ownership
- Structured coordination — typed SQLite mail system with protocol-level message types, not ad-hoc prompts
- Automatic merge pipeline — FIFO queue with 4-tier conflict resolution
- Real-time visibility — browser dashboard shows every agent's status, cost, and output live
- Tiered health monitoring — mechanical watchman catches stalls and crashes before you do
Heads up: Multi-agent swarms burn through tokens fast — a single session can push the limits of a 20x Max Claude subscription.
Dashboard: live view of agent status, mail feed, merge queue, and system metrics
Inspect: deep dive into any agent's activity, tool calls, and terminal output
Costs: token usage by model, per-agent breakdown, and daily cost trends
Tasks: kanban board with issue tracking, priority filters, and dispatch controls
cd your-project
# Bootstrap everything — init, start server, open browser
legio up
# Verify setup is healthy
legio doctor
# When you're done, shut it all down
legio down
The full pipeline: Chat → Gateway → Task Board → Coordinator → Workers → Mail → Merge → Main Branch
CLAUDE.md + hooks + the legio CLI turn your Claude Code session into a multi-agent orchestrator:
- You chat with the Gateway agent, which decomposes your request into issues on the Task Board
- The Coordinator reads the board and dispatches Team Leads, who spawn specialist workers
- Each worker runs in an isolated git worktree — no file conflicts between agents
- Workers communicate via typed SQLite mail (
worker_done,merge_ready,escalation) - Completed work flows through the merge pipeline (4-tier conflict resolution) back to your main branch
- The Dashboard gives real-time visibility into the entire fleet
10 agent types: Coordinator, Lead, Gateway, Supervisor, Scout, Builder, Reviewer, Merger, Monitor, CTO — each with defined access levels and hierarchy constraints. See docs/architecture.md for details.
- Messaging system — SQLite-backed typed mail with protocol messages (
worker_done,merge_ready,dispatch,escalation), broadcast groups (@all,@builders), and auto-nudge on high priority - Merge pipeline — FIFO queue with 4-tier conflict resolution, from fast-forward through AI-assisted merge
- Web dashboard — Real-time agent monitoring, mail feed, cost tracking, terminal access, and setup wizard via browser UI (Preact + HTM, zero build step)
- Health monitoring — Tier 0 mechanical daemon (tmux/pid liveness), Tier 1 AI-assisted failure triage, Tier 2 continuous monitor agent
- Tool enforcement — PreToolUse hooks mechanically block dangerous operations per agent role
- Task groups — Batch coordination with auto-close when all member issues complete
- Session lifecycle — Checkpoint save/restore for compaction survivability, crash recovery handoffs
npm install -g @katyella/legiogit clone https://github.com/katyella/legio.git
cd legio
npm install
npm link- Node.js (v22+)
- Claude Code
- git
- tmux
- sd (seeds) — issue tracking CLI (
bun install -g @os-eco/seeds-cli) — requires Bun - mulch — structured expertise management CLI (
bun install -g @os-eco/mulch-cli) — requires Bun - bd (beads) — legacy issue tracker (alternative to seeds)
- CLI Reference — full command reference with all flags
- REST API — server endpoints and WebSocket
- Architecture — tech stack, agent types, project structure
npm test && npm run lint && npm run typecheckMIT
Adopted from Overstory.