Overstory

Multi-agent orchestration for AI coding agents.

Overstory turns a single coding session into a multi-agent team by spawning worker agents in git worktrees via tmux, coordinating them through a custom SQLite mail system, and merging their work back with tiered conflict resolution. 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+, git, and tmux. 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

# Or spawn individual worker agents
ov sling <task-id> --capability builder --name my-builder

# Check agent status
ov status

# Live dashboard for monitoring the fleet
ov dashboard

# Nudge a stalled agent
ov nudge <agent-name>

# Check mail from agents
ov mail check --inject

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, --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 | Start Tier 2 monitor agent | | ov monitor stop | Stop monitor agent | | ov monitor status | Show monitor state | | ov log <event> | Log a hook event (--agent) | | ov clean | Clean up worktrees, sessions, artifacts (--completed, --all, --run) | | ov doctor | Run health checks on overstory setup — 12 categories (--category, --fix, --json) | | ov ecosystem | Show os-eco tool versions and health (--json) | | ov upgrade | Upgrade overstory to latest npm version (--check, --all, --json) | | ov agents discover | Discover agents by capability/state/parent (--capability, --state, --parent, --json) | | ov completions <shell> | Generate shell completions (bash, zsh, fish) |

Architecture

Overstory uses instruction overlays and tool-call guards to turn agent sessions into orchestrated workers. Each agent runs in an isolated git worktree via tmux. Inter-agent messaging is handled by a custom SQLite mail system (WAL mode, ~1-5ms per query) with typed protocol messages and broadcast support. A FIFO merge queue with 4-tier conflict resolution merges agent branches back to canonical. A tiered watchdog system (Tier 0 mechanical daemon, Tier 1 AI-assisted triage, Tier 2 monitor agent) ensures fleet health. See CLAUDE.md for full technical details.

Runtime Adapters

Overstory is runtime-agnostic. The AgentRuntime interface (src/runtimes/types.ts) defines the contract —