Legio

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.

See It in Action

Quick Start

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

How It Works

CLAUDE.md + hooks + the legio CLI turn your Claude Code session into a multi-agent orchestrator:

1. You chat with the Gateway agent, which decomposes your request into issues on the Task Board
2. The Coordinator reads the board and dispatches Team Leads, who spawn specialist workers
3. Each worker runs in an isolated git worktree — no file conflicts between agents
4. Workers communicate via typed SQLite mail (worker_done, merge_ready, escalation)
5. Completed work flows through the merge pipeline (4-tier conflict resolution) back to your main branch
6. 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.

Key Features

• 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

Installation

npm install -g @katyella/legio

From Source

git clone https://github.com/katyella/legio.git
cd legio
npm install
npm link

Requirements

• Node.js (v22+)
• Claude Code
• git
• tmux

Optional

• 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)

Documentation

• CLI Reference — full command reference with all flags
• REST API — server endpoints and WebSocket
• Architecture — tech stack, agent types, project structure

Development

npm test && npm run lint && npm run typecheck

License

MIT

Adopted from Overstory.