[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74988":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":30,"readmeContent":31,"aiSummary":32,"trendingCount":16,"starSnapshotCount":16,"syncStatus":17,"lastSyncTime":33,"discoverSource":34},74988,"overstory","jayminwest\u002Foverstory","jayminwest","Multi-agent orchestration for AI coding agents — pluggable runtime adapters for Claude Code, Pi, and more","",null,"TypeScript",1322,213,14,16,0,2,11,33,6,67.79,"MIT License",false,"main",[26,27,28,29],"agent-swarms","ai-agents","claude-code","tmux","2026-06-12 04:01:16","# Overstory\n\nMulti-agent orchestration for AI coding agents.\n\n[![npm](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@os-eco\u002Foverstory-cli)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@os-eco\u002Foverstory-cli)\n[![CI](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Foverstory\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Foverstory\u002Factions\u002Fworkflows\u002Fci.yml)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](LICENSE)\n\n> **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](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Fwarren)**, 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](CONTRIBUTING.md#review-cadence).\n\nOverstory 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](https:\u002F\u002Fgithub.com\u002Fbadlogic\u002Fpi-mono\u002Ftree\u002Fmain\u002Fpackages\u002Fcoding-agent), [Gemini CLI](https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli), [Aider](https:\u002F\u002Faider.chat), [Goose](https:\u002F\u002Fgithub.com\u002Fblock\u002Fgoose), [Amp](https:\u002F\u002Famp.dev), or your own adapter.\n\n> **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](STEELMAN.md) for a full risk analysis and the [Agentic Engineering Book](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Fagentic-engineering-book) ([web version](https:\u002F\u002Fjayminwest.com\u002Fagentic-engineering-book)) before using this tool in production.\n\n## Install\n\nRequires [Bun](https:\u002F\u002Fbun.sh) v1.0+ and git. `tmux` is optional — only needed if you want to spawn workers with `--no-headless` or attach to a coordinator\u002Fworker pane directly. At least one supported agent runtime must be installed:\n\n- [Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code) (`claude` CLI)\n- [Pi](https:\u002F\u002Fgithub.com\u002Fbadlogic\u002Fpi-mono\u002Ftree\u002Fmain\u002Fpackages\u002Fcoding-agent) (`pi` CLI)\n- [GitHub Copilot](https:\u002F\u002Fgithub.com\u002Ffeatures\u002Fcopilot) (`copilot` CLI)\n- [Codex](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex) (`codex` CLI)\n- [Gemini CLI](https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli) (`gemini` CLI)\n- [Cursor CLI](https:\u002F\u002Fcursor.com\u002Fdocs\u002Fcli\u002Foverview) (`agent` CLI)\n- [Sapling](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Fsapling) (`sp` CLI)\n- [OpenCode](https:\u002F\u002Fopencode.ai) (`opencode` CLI)\n- [Aider](https:\u002F\u002Faider.chat) (`aider` CLI)\n- [Goose](https:\u002F\u002Fgithub.com\u002Fblock\u002Fgoose) (`goose` CLI)\n- [Amp](https:\u002F\u002Famp.dev) (`amp` CLI)\n\n```bash\nbun install -g @os-eco\u002Foverstory-cli\n```\n\nOr try without installing:\n\n```bash\nnpx @os-eco\u002Foverstory-cli --help\n```\n\n### Development\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Foverstory.git\ncd overstory\nbun install\nbun link              # Makes 'ov' available globally\n\nbun test              # Run all tests\nbun run lint          # Biome check\nbun run typecheck     # tsc --noEmit\n```\n\n## Quick Start\n\n```bash\n# Initialize overstory in your project\ncd your-project\nov init\n\n# Install hooks into .claude\u002Fsettings.local.json\nov hooks install\n\n# Start a coordinator (persistent orchestrator)\nov coordinator start\n\n# Open the web UI — primary operator surface for the swarm\nov serve   # then open http:\u002F\u002Flocalhost:7321\n```\n\n`ov serve` is where you watch the fleet, read the mail bus, and inspect\nper-agent timelines. New projects spawn Claude workers headless by default,\nso the UI sees them with full structured-event fidelity.\n\nOther common commands:\n\n```bash\n# Spawn an individual worker agent (coordinator usually does this for you)\nov sling \u003Ctask-id> --capability builder --name my-builder\n\n# Force a worker into tmux when you want to attach mid-session\nov sling \u003Ctask-id> --capability builder --name my-builder --no-headless\ntmux attach -t ov-my-builder\n\n# Inspect state from the CLI (also visible in the UI)\nov status\nov dashboard          # live TUI alternative to the web UI\nov mail check --inject\nov nudge \u003Cagent-name> # send a follow-up to a stalled agent\n```\n\n## Commands\n\nEvery command supports `--json` where noted. Global flags: `-q`\u002F`--quiet`, `--timing`, `--project \u003Cpath>`. ANSI colors respect `NO_COLOR`.\n\n### Core Workflow\n\n| Command | Description |\n|---------|-------------|\n| `ov init` | Initialize `.overstory\u002F` and bootstrap os-eco tools (`--yes`, `--name`, `--tools`, `--skip-mulch`, `--skip-seeds`, `--skip-canopy`, `--skip-onboard`, `--json`) |\n| `ov sling \u003Ctask-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`) |\n| `ov stop \u003Cagent-name>` | Terminate a running agent (`--clean-worktree`, `--json`) |\n| `ov prime` | Load context for orchestrator\u002Fagent (`--agent`, `--compact`) |\n| `ov spec write \u003Ctask-id>` | Write a task specification (`--body`) |\n| `ov discover` | Discover a brownfield codebase via coordinator-driven scout swarm (`--skip`, `--name`, `--attach`, `--watchdog`, `--json`) |\n| `ov update` | Refresh `.overstory\u002F` managed files from installed package (`--agents`, `--manifest`, `--hooks`, `--dry-run`, `--json`) |\n\n### Coordination\n\n| Command | Description |\n|---------|-------------|\n| `ov coordinator start` | Start persistent coordinator agent (`--attach`\u002F`--no-attach`, `--watchdog`, `--monitor`, `--profile`) |\n| `ov coordinator stop` | Stop coordinator |\n| `ov coordinator status` | Show coordinator state |\n| `ov coordinator send` | Fire-and-forget message to coordinator (`--subject`) |\n| `ov coordinator ask` | Synchronous request\u002Fresponse to coordinator (`--subject`, `--timeout`) |\n| `ov coordinator output` | Show recent coordinator output (`--lines`) |\n| `ov coordinator check-complete` | Evaluate exit triggers, return completion status |\n| `ov orchestrator start` | Start multi-repo orchestrator agent (`--attach`\u002F`--no-attach`, `--watchdog`, `--profile`) |\n| `ov orchestrator stop` | Stop orchestrator |\n| `ov orchestrator status` | Show orchestrator state |\n| `ov orchestrator send` | Fire-and-forget message to orchestrator (`--subject`) |\n| `ov orchestrator ask` | Synchronous request\u002Fresponse to orchestrator (`--subject`, `--timeout`) |\n| `ov orchestrator output` | Show recent orchestrator output (`--lines`) |\n| `ov supervisor start` | **[DEPRECATED]** Start per-project supervisor agent |\n| `ov supervisor stop` | **[DEPRECATED]** Stop supervisor |\n| `ov supervisor status` | **[DEPRECATED]** Show supervisor state |\n\n### Messaging\n\n| Command | Description |\n|---------|-------------|\n| `ov mail send` | Send a message (`--to`, `--subject`, `--body`, `--type`, `--priority`) |\n| `ov mail check` | Check inbox — unread messages (`--agent`, `--inject`, `--debounce`, `--json`) |\n| `ov mail list` | List messages with filters (`--from`, `--to`, `--unread`) |\n| `ov mail read \u003Cid>` | Mark message as read |\n| `ov mail reply \u003Cid>` | Reply in same thread (`--body`) |\n| `ov nudge \u003Cagent> [message]` | Send a text nudge to an agent (`--from`, `--force`, `--json`) |\n\n### Task Groups\n\n| Command | Description |\n|---------|-------------|\n| `ov group create \u003Cname>` | Create a task group for batch tracking |\n| `ov group status \u003Cname>` | Show group progress |\n| `ov group add \u003Cname> \u003Cissue-id>` | Add issue to group |\n| `ov group list` | List all groups |\n\n### Merge\n\n| Command | Description |\n|---------|-------------|\n| `ov merge` | Merge agent branches into canonical (`--branch`, `--all`, `--into`, `--dry-run`, `--json`) |\n\n### Observability\n\n| Command | Description |\n|---------|-------------|\n| `ov status` | Show all active agents, worktrees, tracker state (`--json`, `--verbose`, `--all`) |\n| `ov dashboard` | Live TUI dashboard for agent monitoring (`--interval`, `--all`) |\n| `ov inspect \u003Cagent>` | Deep per-agent inspection (`--follow`, `--interval`, `--no-tmux`, `--limit`, `--json`) |\n| `ov trace` | View agent\u002Ftask timeline (`--agent`, `--run`, `--since`, `--until`, `--limit`, `--json`) |\n| `ov errors` | Aggregated error view across agents (`--agent`, `--run`, `--since`, `--until`, `--limit`, `--json`) |\n| `ov replay` | Interleaved chronological replay (`--run`, `--agent`, `--since`, `--until`, `--limit`, `--json`) |\n| `ov feed` | Unified real-time event stream (`--follow`, `--interval`, `--agent`, `--run`, `--json`) |\n| `ov logs` | Query NDJSON logs across agents (`--agent`, `--level`, `--since`, `--until`, `--follow`, `--json`) |\n| `ov costs` | Token\u002Fcost analysis and breakdown (`--live`, `--self`, `--agent`, `--run`, `--bead`, `--by-capability`, `--last`, `--json`) |\n| `ov metrics` | Show session metrics (`--last`, `--json`) |\n| `ov run list` | List orchestration runs (`--last`, `--json`) |\n| `ov run show \u003Cid>` | Show run details |\n| `ov run complete` | Mark current run as completed |\n\n### Infrastructure\n\n| Command | Description |\n|---------|-------------|\n| `ov hooks install` | Install orchestrator hooks to `.claude\u002Fsettings.local.json` (`--force`) |\n| `ov hooks uninstall` | Remove orchestrator hooks |\n| `ov hooks status` | Check if hooks are installed |\n| `ov worktree list` | List worktrees with status |\n| `ov worktree clean` | Remove completed worktrees (`--completed`, `--all`, `--force`) |\n| `ov watch` | Start watchdog daemon — Tier 0 (`--interval`, `--background`) |\n| `ov monitor start` | Start Tier 2 monitor agent |\n| `ov monitor stop` | Stop monitor agent |\n| `ov monitor status` | Show monitor state |\n| `ov log \u003Cevent>` | Log a hook event (`--agent`) |\n| `ov clean` | Clean up worktrees, sessions, artifacts (`--completed`, `--all`, `--run`) |\n| `ov doctor` | Run health checks on overstory setup — 13 categories (`--category`, `--fix`, `--json`) |\n| `ov serve` | HTTP + WebSocket surface for the web UI (`--port`, `--host`, `--json`) |\n| `ov ecosystem` | Show os-eco tool versions and health (`--json`) |\n| `ov upgrade` | Upgrade overstory to latest npm version (`--check`, `--all`, `--json`) |\n| `ov agents discover` | Discover agents by capability\u002Fstate\u002Fparent (`--capability`, `--state`, `--parent`, `--json`) |\n| `ov completions \u003Cshell>` | Generate shell completions (bash, zsh, fish) |\n\n## Architecture\n\nOverstory uses instruction overlays and tool-call guards to turn agent sessions into orchestrated workers. Each agent runs in an isolated git worktree; new projects spawn Claude workers as headless subprocesses (stream-json over stdout) and surface them through `ov serve`'s web UI, with tmux available as an opt-in for live attach. 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](CLAUDE.md) for full technical details.\n\n### Runtime Adapters\n\nOverstory is runtime-agnostic. The `AgentRuntime` interface (`src\u002Fruntimes\u002Ftypes.ts`) defines the contract — each adapter handles spawning, config deployment, guard enforcement, readiness detection, and transcript parsing for its runtime. Set the default in `config.yaml` or override per-agent with `ov sling --runtime \u003Cname>`.\n\nClaude Code agents can run in **headless mode** (the default for new projects — `-p --output-format stream-json` subprocess, NDJSON events parsed by `ClaudeRuntime.parseEvents`, surfaced through `ov serve`'s web UI) or **tmux mode** (escape hatch for live attach — operator can `tmux attach` to watch and steer mid-session). `ov init` writes `runtime.claudeHeadlessByDefault: true` for new projects; legacy projects upgrading from earlier overstory versions keep tmux until they edit config. Override per-spawn with `ov sling --no-headless` (force tmux) or `--headless` (force headless). Sapling is statically headless; Pi, Codex, and Cursor have no `buildDirectSpawn` and reject `--headless`.\n\n| Runtime | CLI | Guard Mechanism | Stability |\n|---------|-----|-----------------|-----------|\n| Claude Code | `claude` | `settings.local.json` hooks | Stable |\n| Sapling | `sp` | `.sapling\u002Fguards.json` | Stable |\n| Pi | `pi` | `.pi\u002Fextensions\u002F` guard extension | Experimental |\n| Copilot | `copilot` | (none — `--allow-all-tools`) | Experimental |\n| Cursor | `agent` | (none — `--yolo`) | Experimental |\n| Codex | `codex` | OS-level sandbox (Seatbelt\u002FLandlock) | Experimental |\n| Gemini | `gemini` | `--sandbox` flag | Experimental |\n| Aider | `aider` | (none — `--yes-always`) | Experimental |\n| Goose | `goose` | Profile-based permissions | Experimental |\n| Amp | `amp` | Built-in approval system | Experimental |\n| OpenCode | `opencode` | (none) | Experimental |\n\n## How It Works\n\nInstruction overlays + tool-call guards + the `ov` CLI turn your coding session into a multi-agent orchestrator. A persistent coordinator agent manages task decomposition and dispatch, while a mechanical watchdog daemon monitors agent health in the background.\n\n```\nOrchestrator (multi-repo coordinator of coordinators)\n  --> Coordinator (persistent orchestrator at project root)\n        --> Supervisor \u002F Lead (team lead, depth 1)\n              --> Workers: Scout, Builder, Reviewer, Merger (depth 2)\n```\n\n### Agent Types\n\n| Agent | Role | Access |\n|-------|------|--------|\n| **Orchestrator** | Multi-repo coordinator of coordinators — dispatches coordinators per sub-repo | Read-only |\n| **Coordinator** | Persistent orchestrator — decomposes objectives, dispatches agents, tracks task groups | Read-only |\n| **Supervisor** | Per-project team lead — manages worker lifecycle, handles nudge\u002Fescalation | Read-only |\n| **Scout** | Read-only exploration and research | Read-only |\n| **Builder** | Implementation and code changes | Read-write |\n| **Reviewer** | Validation and code review | Read-only |\n| **Lead** | Team coordination, can spawn sub-workers | Read-write |\n| **Merger** | Branch merge specialist | Read-write |\n| **Monitor** | Tier 2 continuous fleet patrol — ongoing health monitoring | Read-only |\n\n### Key Architecture\n\n- **Agent Definitions**: Two-layer system — base `.md` files define the HOW (workflow), per-task overlays define the WHAT (task scope). Base definition content is injected into spawned agent overlays automatically.\n- **Messaging**: Custom SQLite mail system with typed protocol — 8 message types (`worker_done`, `merge_ready`, `dispatch`, `escalation`, etc.) for structured agent coordination, plus broadcast messaging with group addresses (`@all`, `@builders`, etc.)\n- **Worktrees**: Each agent gets an isolated git worktree — no file conflicts between agents\n- **Merge**: FIFO merge queue (SQLite-backed) with 4-tier conflict resolution\n- **Watchdog**: Tiered health monitoring — Tier 0 mechanical daemon (tmux\u002Fpid liveness), Tier 1 AI-assisted failure triage, Tier 2 monitor agent for continuous fleet patrol\n- **Tool Enforcement**: Runtime-specific guards (hooks for Claude Code, extensions for Pi) mechanically block file modifications for non-implementation agents and dangerous git operations for all agents\n- **Task Groups**: Batch coordination with auto-close when all member issues complete\n- **Session Lifecycle**: Checkpoint save\u002Frestore for compaction survivability, handoff orchestration for crash recovery\n- **Token Instrumentation**: Session metrics extracted from runtime transcript files (JSONL)\n\n## Project Structure\n\n```\noverstory\u002F\n  src\u002F\n    index.ts                      CLI entry point (Commander.js program)\n    types.ts                      Shared types and interfaces\n    config.ts                     Config loader + validation\n    errors.ts                     Custom error types\n    json.ts                       Standardized JSON envelope helpers\n    commands\u002F                     One file per CLI subcommand (38 commands)\n      agents.ts                   Agent discovery and querying\n      coordinator.ts              Persistent orchestrator lifecycle\n      supervisor.ts               Team lead management [DEPRECATED]\n      dashboard.ts                Live TUI dashboard (ANSI via Chalk)\n      hooks.ts                    Orchestrator hooks management\n      sling.ts                    Agent spawning\n      group.ts                    Task group batch tracking\n      nudge.ts                    Agent nudging\n      mail.ts                     Inter-agent messaging\n      monitor.ts                  Tier 2 monitor management\n      merge.ts                    Branch merging\n      status.ts                   Fleet status overview\n      prime.ts                    Context priming\n      init.ts                     Project initialization\n      worktree.ts                 Worktree management\n      watch.ts                    Watchdog daemon\n      log.ts                      Hook event logging\n      logs.ts                     NDJSON log query\n      feed.ts                     Unified real-time event stream\n      run.ts                      Orchestration run lifecycle\n      trace.ts                    Agent\u002Ftask timeline viewing\n      clean.ts                    Worktree\u002Fsession cleanup\n      doctor.ts                   Health check runner (13 check modules)\n      inspect.ts                  Deep per-agent inspection\n      spec.ts                     Task spec management\n      errors.ts                   Aggregated error view\n      replay.ts                   Interleaved event replay\n      stop.ts                     Agent termination\n      costs.ts                    Token\u002Fcost analysis\n      metrics.ts                  Session metrics\n      ecosystem.ts                os-eco tool dashboard\n      update.ts                   Refresh managed files\n      upgrade.ts                  npm version upgrades\n      discover.ts                 Brownfield codebase discovery via coordinator-driven scout swarm\n      orchestrator.ts             Multi-repo coordination (PersistentAgentSpec)\n      completions.ts              Shell completion generation (bash\u002Fzsh\u002Ffish)\n      serve.ts                    HTTP + WebSocket surface for the web UI\n      serve\u002F                      REST handlers, WebSocket broadcaster, static SPA fallback\n    canopy\u002F\n      client.ts                   Canopy client (prompt rendering, listing, emission)\n    agents\u002F                       Agent lifecycle management\n      manifest.ts                 Agent registry (load + query)\n      overlay.ts                  Dynamic CLAUDE.md overlay generator\n      identity.ts                 Persistent agent identity (CVs)\n      checkpoint.ts               Session checkpoint save\u002Frestore\n      lifecycle.ts                Handoff orchestration\n      hooks-deployer.ts           Deploy hooks + tool enforcement\n      copilot-hooks-deployer.ts   Deploy hooks config to Copilot worktrees\n      guard-rules.ts              Shared guard constants (tool lists, bash patterns)\n      mail-poll-detect.ts         Bash mail-poll pattern detector (runtime backstop)\n      scope-detect.ts             Soft FILE_SCOPE violation detection (builder\u002Fmerger)\n    worktree\u002F                     Git worktree + tmux management\n    mail\u002F                         SQLite mail system (typed protocol, broadcast)\n    merge\u002F                        FIFO queue + conflict resolution + sentinel-file lock + dry-run prediction\n    watchdog\u002F                     Tiered health monitoring (daemon, triage, health)\n    logging\u002F                      Multi-format logger + sanitizer + reporter + color control + shared theme\u002Fformat\n    metrics\u002F                      SQLite metrics + pricing + transcript parsing\n    doctor\u002F                       Health check modules (13 checks)\n    utils\u002F                        Shared utilities (bin, fs, pid, time, version)\n    insights\u002F                     Session insight analyzer + quality-gate runner (success\u002Fpartial\u002Ffailure)\n    runtimes\u002F                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot, Codex, Gemini, Sapling, OpenCode, Cursor, Aider, Goose, Amp)\n    tracker\u002F                      Pluggable task tracker (beads + seeds backends)\n    mulch\u002F                        mulch client (programmatic API + CLI wrapper)\n    e2e\u002F                          End-to-end lifecycle tests\n  agents\u002F                         Base agent definitions (.md, 9 roles) + skill definitions\n  templates\u002F                      Templates for overlays and hooks\n```\n\n## Configuration\n\n### Gateway Providers\n\nRoute agent API calls through custom gateway endpoints (z.ai, OpenRouter, self-hosted proxies). Configure providers in `.overstory\u002Fconfig.yaml`:\n\n```yaml\nproviders:\n  anthropic:\n    type: native\n  zai:\n    type: gateway\n    baseUrl: https:\u002F\u002Fapi.z.ai\u002Fv1\n    authTokenEnv: ZAI_API_KEY\n  openrouter:\n    type: gateway\n    baseUrl: https:\u002F\u002Fopenrouter.ai\u002Fapi\u002Fv1\n    authTokenEnv: OPENROUTER_API_KEY\nmodels:\n  builder: zai\u002Fclaude-sonnet-4-6\n  scout: openrouter\u002Fopenai\u002Fgpt-4o\n```\n\n**How it works:** Model refs use `provider\u002Fmodel-id` format. Overstory sets `ANTHROPIC_BASE_URL` to the gateway `baseUrl`, `ANTHROPIC_AUTH_TOKEN` from the env var named in `authTokenEnv`, and `ANTHROPIC_API_KEY=\"\"` to prevent direct Anthropic calls. The agent receives `\"sonnet\"` as a model alias and Claude Code routes via env vars.\n\n**Environment variable notes:**\n- `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_API_KEY` are mutually exclusive per-agent\n- Gateway agents get `ANTHROPIC_API_KEY=\"\"` and `ANTHROPIC_AUTH_TOKEN` from provider config\n- Direct Anthropic API calls (merge resolver, watchdog triage) still need `ANTHROPIC_API_KEY` in the orchestrator env\n\n**Validation:** `ov doctor --category providers` checks reachability, auth tokens, model-provider refs, and tool-use compatibility.\n\n**`ProviderConfig` fields:**\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `type` | `native` or `gateway` | Yes | Provider type |\n| `baseUrl` | string | Gateway only | API endpoint URL |\n| `authTokenEnv` | string | Gateway only | Env var name holding auth token |\n\n## Troubleshooting\n\n### Recovering a dead lead (or any agent that exited mid-task)\n\nIf a lead exits without sending `merge_ready` (process termination, watchdog kill, manual `ov stop`) and the task was already closed, both `ov nudge` and `ov sling` would normally refuse to re-engage:\n\n- `ov nudge \u003Cname>` reports `No active session for agent \"...\" (state: completed)`. The agent's process is gone, so there's nothing to send keystrokes to.\n- `ov sling \u003Ctask-id> --capability lead` reports `Task \"...\" is not workable (status: closed)`.\n\nTo re-dispatch a fresh lead against the same task, pass `--recover`:\n\n```bash\nov sling \u003Ctask-id> --capability lead --recover --name \u003Cfresh-name>\n```\n\n`--recover` bypasses the workable-status check so the new lead can pick up where the dead one left off (the task remains closed; the new lead reads the spec and proceeds). The terminal-state nudge error itself includes a copy-paste hint to this exact form.\n\n### Coordinator died during startup\n\nThis error means the coordinator tmux session exited before the TUI became ready. The most common cause is slow shell initialization.\n\n**Step 1: Measure shell startup time**\n\n```bash\ntime zsh -i -c exit   # For zsh\ntime bash -i -c exit  # For bash\n```\n\nIf startup takes more than 1 second, slow shell init is likely the cause.\n\n**Step 2: Common slow-startup causes**\n\n| Cause | Typical delay | Fix |\n|-------|---------------|-----|\n| oh-my-zsh with many plugins | 1-5s | Reduce plugins, switch to lighter framework (zinit with lazy loading) |\n| nvm (Node Version Manager) | 1-3s | Use `--no-use` + lazy-load nvm, or switch to fnm\u002Fvolta |\n| pyenv init | 0.5-2s | Lazy-load pyenv |\n| rbenv init | 0.5-1s | Lazy-load rbenv |\n| starship prompt | 0.5-1s | Check starship timings |\n| conda auto-activate | 1-3s | `auto_activate_base: false` in `.condarc` |\n| Homebrew shellenv | 0.5-1s | Cache output instead of evaluating every shell start |\n\n**Step 3: Configure `shellInitDelayMs`** in `.overstory\u002Fconfig.yaml`:\n\n```yaml\nruntime:\n  shellInitDelayMs: 3000\n```\n\n- Default: `0` (no delay)\n- Typical values: `1000`–`5000` depending on shell startup time\n- Values above `30000` (30s) trigger a warning\n- Inserts a delay between tmux session creation and TUI readiness polling\n\n**Step 4: Optimization examples**\n\nLazy-load nvm (add to `~\u002F.zshrc` or `~\u002F.bashrc`):\n\n```bash\n# Lazy-load nvm — only activates when you first call nvm\u002Fnode\u002Fnpm\nexport NVM_DIR=\"$HOME\u002F.nvm\"\nnvm() { unset -f nvm node npm npx; [ -s \"$NVM_DIR\u002Fnvm.sh\" ] && . \"$NVM_DIR\u002Fnvm.sh\"; nvm \"$@\"; }\nnode() { unset -f nvm node npm npx; [ -s \"$NVM_DIR\u002Fnvm.sh\" ] && . \"$NVM_DIR\u002Fnvm.sh\"; node \"$@\"; }\nnpm()  { unset -f nvm node npm npx; [ -s \"$NVM_DIR\u002Fnvm.sh\" ] && . \"$NVM_DIR\u002Fnvm.sh\"; npm  \"$@\"; }\nnpx()  { unset -f nvm node npm npx; [ -s \"$NVM_DIR\u002Fnvm.sh\" ] && . \"$NVM_DIR\u002Fnvm.sh\"; npx  \"$@\"; }\n```\n\nReduce oh-my-zsh plugins (edit `~\u002F.zshrc`):\n\n```bash\n# Before: plugins=(git zsh-autosuggestions zsh-syntax-highlighting node npm python ruby rbenv pyenv ...)\n# After: keep only what you use regularly\nplugins=(git)\n```\n\n## Part of os-eco\n\nOverstory is part of the [os-eco](https:\u002F\u002Fgithub.com\u002Fjayminwest\u002Fos-eco) AI agent tooling ecosystem.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fraw.githubusercontent.com\u002Fjayminwest\u002Fos-eco\u002Fmain\u002Fbranding\u002Flogo.png\" alt=\"os-eco\" width=\"444\" \u002F>\n\u003C\u002Fp>\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT\n","Overstory 是一个多代理编排工具，用于协调 AI 编码代理的工作。它通过在隔离的 git 工作树中生成工作代理，并使用自定义的 SQLite 邮件系统进行协调，最终通过分层冲突解决机制合并代码。该项目支持多种运行时环境，如 Claude Code、Pi 和 Gemini CLI 等，用户可以通过插件式 `AgentRuntime` 接口轻松切换。Overstory 适用于需要多个 AI 代理协同工作的复杂编码任务场景，但需要注意的是，多代理编排会带来错误率增加、成本上升、调试复杂度提高以及合并冲突等问题。因此，在生产环境中部署前应充分评估风险。","2026-06-11 03:51:52","high_star"]