FFFF GitHub - katyella/legio: Turn one Claude Code session into a multi-agent fleet — spawn workers in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution · GitHub
[go: up one dir, main page]

Skip to content
katyellaPublic

About

Turn one Claude Code session into a multi-agent fleet — spawn workers in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution

Resources

Contributing

Security policy

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

Legio

Legio mascot

npm CI License: MIT Node GitHub release

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

Legio Dashboard — real-time agent monitoring
Dashboard: live view of agent status, mail feed, merge queue, and system metrics

Inspect — deep per-agent inspection
Inspect: deep dive into any agent's activity, tool calls, and terminal output

Costs — token usage and cost breakdown
Costs: token usage by model, per-agent breakdown, and daily cost trends

Tasks — issue tracking kanban board
Tasks: kanban board with issue tracking, priority filters, and dispatch controls

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

Legio architecture — agent pipeline from chat to main branch
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:

  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

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

Development

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

License

MIT


Adopted from Overstory.

About

Turn one Claude Code session into a multi-agent fleet — spawn workers in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution

Resources

Contributing

Security policy

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0