Overstory
Multi-agent orchestration for AI coding agents.
Maintenance status. Overstory is in maintenance mode: bug fixes and small PRs only, reviewed in roughly 2-week batches. PRs inactive for 30+ days are closed (reopen anytime). For features larger than ~200 lines, open an issue or discussion first. Active development has moved to Warren, a self-hostable control plane for sandboxed cloud agents that I expect to grow into overstory's successor. If you're starting something new, look at warren first. See CONTRIBUTING.md.
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 (
claudeCLI) - Pi (
piCLI) - GitHub Copilot (
copilotCLI) - Codex (
codexCLI) - Gemini CLI (
geminiCLI) - Cursor CLI (
agentCLI) - Sapling (
spCLI) - OpenCode (
opencodeCLI) - Aider (
aiderCLI) - Goose (
gooseCLI) - Amp (
ampCLI)
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
| Command | Description |
|---------|-------------|
| ov init | Initialize .overstory/ and bootstrap os-eco tools (--yes, --name, --tools, --skip-mulch, --skip-seeds, --skip-canopy, --skip-onboard, --json) |
| ov sling <task-id> | Spawn a worker agent (--capability, --name, --spec, --files, --parent, --depth, --skip-scout, --skip-review, --max-agents, --dispatch-max-agents, --skip-task-check, --no-scout-check, --runtime, --base-branch, --profile, --headless, --no-headless, --recover, --json) |
| ov stop <agent-name> | Terminate a running agent (--clean-worktree, --json) |
| ov prime | Load context for orchestrator/agent (--agent, --compact) |
| ov spec write <task-id> | Write a task specification (--body) |
| ov discover | Discover a brownfield codebase via coordinator-driven scout swarm (--skip, --name, --attach, --watchdog, --json) |
| ov update | Refresh .overstory/ managed files from installed package (--agents, --manifest, --hooks, --dry-run, --json) |
Coordination
| Command | Description |
|---------|-------------|
| ov coordinator start | Start persistent coordinator agent (--attach/--no-attach, --watchdog, --monitor, --profile) |
| ov coordinator stop | Stop coordinator |
| ov coordinator status | Show coordinator state |
| ov coordinator send | Fire-and-forget message to coordinator (--subject) |
| ov coordinator ask | Synchronous request/response to coordinator (--subject, --timeout) |
| ov coordinator output | Show recent coordinator output (--lines) |
| ov coordinator check-complete | Evaluate exit triggers, return completion status |
| ov orchestrator start | Start multi-repo orchestrator agent (--attach/--no-attach, --watchdog, --profile) |
| ov orchestrator stop | Stop orchestrator |
| ov orchestrator status | Show orchestrator state |
| ov orchestrator send | Fire-and-forget message to orchestrator (--subject) |
| ov orchestrator ask | Synchronous request/response to orchestrator (--subject, --timeout) |
| ov orchestrator output | Show recent orchestrator output (--lines) |
| ov supervisor start | [DEPRECATED] Start per-project supervisor agent |
| ov supervisor stop | [DEPRECATED] Stop supervisor |
| ov supervisor status | [DEPRECATED] Show supervisor state |
Messaging
| Command | Description |
|---------|-------------|
| ov mail send | Send a message (--to, --subject, --body, --type, --priority) |
| ov mail check | Check inbox — unread messages (--agent, --inject, --debounce, --json) |
| ov mail list | List messages with filters (--from, --to, --unread) |
| ov mail read <id> | Mark message as read |
| ov mail reply <id> | Reply in same thread (--body) |
| ov nudge <agent> [message] | Send a text nudge to an agent (--from, --force, --json) |
Task Groups
| Command | Description |
|---------|-------------|
| ov group create <name> | Create a task group for batch tracking |
| ov group status <name> | Show group progress |
| ov group add <name> <issue-id> | Add issue to group |
| ov group list | List all groups |
Merge
| Command | Description |
|---------|-------------|
| ov merge | Merge agent branches into canonical (--branch, --all, --into, --dry-run, --json) |
Observability
| Command | Description |
|---------|-------------|
| ov status | Show all active agents, worktrees, tracker state (--json, --verbose, --all) |
| ov dashboard | Live TUI dashboard for agent monitoring (--interval, --all) |
| ov inspect <agent> | Deep per-agent inspection (--follow, --interval, --no-tmux, --limit, --json) |
| ov trace | View agent/task timeline (--agent, --run, --since, --until, --limit, --json) |
| ov errors | Aggregated error view across agents (--agent, --run, --since, --until, --limit, --json) |
| ov replay | Interleaved chronological replay (--run, --agent, --since, --until, --limit, --json) |
| ov feed | Unified real-time event stream (--follow, --interval, --agent, --run, --json) |
| ov logs | Query NDJSON logs across agents (--agent, --level, --since, --until, --follow, --json) |
| ov costs | Token/cost analysis and breakdown (--live, --self, --agent, --run, --bead, --by-capability, --last, --json) |
| ov metrics | Show session metrics (--last, --json) |
| ov run list | List orchestration runs (--last, --json) |
| ov run show <id> | Show run details |
| ov run complete | Mark current run as completed |
Infrastructure
| Command | Description |
|---------|-------------|
| ov hooks install | Install orchestrator hooks to .claude/settings.local.json (--force) |
| ov hooks uninstall | Remove orchestrator hooks |
| ov hooks status | Check if hooks are installed |
| ov worktree list | List worktrees with status |
| ov worktree clean | Remove completed worktrees (--completed, --all, --force) |
| ov watch | Start watchdog daemon — Tier 0 (--interval, --background) |
| `ov monitor start