Overstory

Multi-agent orchestration for AI coding agents.

No longer maintained. Overstory is no longer actively maintained and this repository is archived (read-only) — I am not reviewing issues or merging pull requests here anymore. Thank you to everyone who contributed. The code stays MIT-licensed, so feel free to fork and carry it forward. Active development has moved to Warren, a self-hostable control plane for sandboxed cloud agents and overstory's spiritual successor — start there for anything new.

Overstory turns a single coding session into a multi-agent team by spawning worker agents in isolated git worktrees, coordinating them through a custom SQLite mail system, and merging their work back with tiered conflict resolution. New projects spawn Claude agents headless and surface them through a web UI (ov serve); tmux attach is the opt-in escape hatch for live steering. A pluggable AgentRuntime interface lets you swap between 11 runtimes — Claude Code, Pi, Gemini CLI, Aider, Goose, Amp, or your own adapter.

Warning: Agent swarms are not a universal solution. Do not deploy Overstory without understanding the risks of multi-agent orchestration — compounding error rates, cost amplification, debugging complexity, and merge conflicts are the normal case, not edge cases. Read STEELMAN.md for a full risk analysis and the Agentic Engineering Book (web version) before using this tool in production.

Install

Requires Bun v1.0+ and git. tmux is optional — only needed if you want to spawn workers with --no-headless or attach to a coordinator/worker pane directly. At least one supported agent runtime must be installed:

• Claude Code (claude CLI)
• Pi (pi CLI)
• GitHub Copilot (copilot CLI)
• Codex (codex CLI)
• Gemini CLI (gemini CLI)
• Cursor CLI (agent CLI)
• Sapling (sp CLI)
• OpenCode (opencode CLI)
• Aider (aider CLI)
• Goose (goose CLI)
• Amp (amp CLI)

bun install -g @os-eco/overstory-cli

Or try without installing:

npx @os-eco/overstory-cli --help

Development

git clone https://github.com/jayminwest/overstory.git
cd overstory
bun install
bun link              # Makes 'ov' available globally

bun test              # Run all tests
bun run lint          # Biome check
bun run typecheck     # tsc --noEmit

Quick Start

# Initialize overstory in your project
cd your-project
ov init

# Install hooks into .claude/settings.local.json
ov hooks install

# Start a coordinator (persistent orchestrator)
ov coordinator start

# Open the web UI — primary operator surface for the swarm
ov serve   # then open http://localhost:7321

ov serve is where you watch the fleet, read the mail bus, and inspect per-agent timelines. New projects spawn Claude workers headless by default, so the UI sees them with full structured-event fidelity.

Other common commands:

# Spawn an individual worker agent (coordinator usually does this for you)
ov sling <task-id> --capability builder --name my-builder

# Force a worker into tmux when you want to attach mid-session
ov sling <task-id> --capability builder --name my-builder --no-headless
tmux attach -t ov-my-builder

# Inspect state from the CLI (also visible in the UI)
ov status
ov dashboard          # live TUI alternative to the web UI
ov mail check --inject
ov nudge <agent-name> # send a follow-up to a stalled agent

Commands

Every command supports --json where noted. Global flags: -q/--quiet, --timing, --project <path>. ANSI colors respect NO_COLOR.

Core Workflow

Coordination

Messaging

Task Groups

Merge

Observability

Infrastructure