Overstory Documentation

Overstory uses a hierarchical inheritance model for agent prompts. Prompts are organized into trees where child agents inherit sections from their parents, allowing for specialized behavior while maintaining universal principles.

Main Agent Tree

• base-agent: The root containing universal principles.
• leaf-worker: Single-worker agents (e.g., builder, merger, scout, reviewer).
• coordinator-base: Leadership and orchestration agents (e.g., lead, orchestrator, coordinator-agent).
• monitor: Tier 2 fleet patrol.

Profile / Delivery Prompts

A separate chain used to define the session style:

• ov-delivery: Base guidance.
• Specialized profiles: ov-architecture, ov-co-creation, ov-discovery, ov-research, ov-red-hat (adversarial/risk analysis).

Standalone Utility Prompts

Prompts that do not participate in the inheritance chain:

• prioritize, release, pr-reviews, issue-reviews.

base-agent                          (root — universal principles)
│
├── leaf-worker                     (single-worker constraints)
│   ├── builder                     (implementation specialist)
│   ├── merger                      (branch merge specialist)
│   └── read-only-worker            (read-only restriction layer)
│       ├── scout                   (exploration, no writes)
│       └── reviewer                (validation, no writes)
│
├── coordinator-base                (leadership/orchestration)
│   ├── lead                        (team lead, spawns sub-workers)
│   ├── orchestrator                (multi-repo coordinator)
│   └── coordinator-agent           (top-level coordinator)
│
└── monitor                         (Tier 2 fleet patrol)

Overstory categorizes agent runtimes into two main types based on how they interact with the orchestrator:

TUI Runtimes (e.g., Claude Code, Pi, Copilot)

These runtimes maintain a persistent interactive process inside a tmux pane. The orchestrator manages their lifecycle by:

• Creating a tmux session.
• Using detectReady() to poll the pane content (looking for "loading", "dialog", or "ready") to ensure the TUI has rendered.
• Sending prompts and beacons via tmux send-keys.
• Verifying beacons to ensure the TUI didn't swallow the input (common in Claude Code/Copilot).
• Using mail hooks (like ov mail check --inject for Claude Code) for mid-session communication.
• Persisting across multiple exchanges until killSession() is called.

Headless Runtimes (e.g., Codex)

These runtimes spawn a process, execute a single task, and exit. They are non-persistent:

• detectReady() returns ready immediately.
• Prompts are passed as execution arguments rather than via tmux keys.
• No mid-execution mail delivery is possible; the process runs to completion.
• Events and token usage are captured via NDJSON on stdout (using the --json flag).

Overstory is transitioning from a single-swarm model to a multi-swarm architecture. This allows an operator to manage multiple concurrent, isolated swarms from a single, always-running UI surface.

Key Architectural Shifts

• Run-id as the Primary Primitive: Instead of a single current-run.txt file, the system uses a run-id to namespace all activities. This allows multiple active runs to coexist.
• Run-Namespaced Storage: To prevent collisions between different swarms, storage is moved from global paths to run-specific directories:
  • Host Mode: .overstory/runs/<run-id>/
  • Container Mode: /workspace/.overstory/ (exposed via bind mount)
• Namespacing: Worktrees, mail.db, sessions.db, events.db, and logs are all scoped under the specific run-id.

Operator Workflow

1. Setup: Run ov setup to start a persistent daemon (ov serve) and a stable local UI URL.
2. Manage Swarms: Use the UI sidebar (Run picker) to view all past and active runs.
3. Spawn Swarms: Use the "New run" affordance in the UI to spawn a new coordinator under a unique run-id without using the terminal.
4. Interact: Click into any running coordinator to engage in a chat session, similar to tmux attach.

In Overstory, when running Claude Code in headless mode (using flags like --permission-mode bypassPermissions), security guards behave differently than in TUI mode.

Key distinction:

• In TUI mode: Overstory uses .claude/settings.local.json PreToolUse hooks to mechanically intercept and block tool calls that violate path boundaries, capability rules, or bash danger patterns.
• In Headless mode: While PreToolUse hooks are still deployed and dispatched, they are supplemented by a headless-specific subset. Non-PreToolUse hooks (like SessionStart or UserPromptSubmit) are replaced by the orchestrator's internal stream-json parser and mail injection loop.

Security Model: Because headless mode often bypasses standard permission prompts, the primary enforcement mechanism is the CLAUDE.md overlay. Agents are instructed via this overlay to operate only within their designated worktree. While the mechanical PreToolUse guards provide defense-in-depth, the system relies on agent alignment with these instructions.

When running in headless mode, Overstory modifies how hooks are deployed and executed compared to standard tmux-based agents.

Key Deployment Rules

• PreToolUse guards: These are still deployed but use a specific headlessOnly mode (identified by overstory-e24b).
• PostToolUse (ov log): Skipped; the stream parser handles this instead.
• PostToolUse (mail check): Subsumed by the server-side injection loop.
• Stop (ov log session-end): Skipped; handled by the result event from the parser.
• Stop (ml learn): Omitted; agents are instead instructed via the CLAUDE.md overlay to call ml record before completion.

Hook Mapping Summary

Canopy prompts are assembled through a three-stage resolution process when an agent is spawned (e.g., via ov sling). The final instruction set is written to CLAUDE.md at the agent's {{INSTRUCTION_PATH}}. The resulting prompt combines three distinct layers of guidance:

1. Base Definition (HOW): Resolved via cn render builder --json. This defines the core agent capabilities (e.g., leaf-worker -> builder).
2. Profile Guidance (STYLE): Resolved via cn render <profile-name> --json. This applies specific behavioral or architectural profiles (e.g., ov-architecture).
3. Overlay Specifics (WHAT): Built from templates/overlay.md.tmpl. This contains task-specific context (e.g., TASK_ID, BRANCH_NAME) provided at spawn time.

The system joins these sections, substitutes variables (like QUALITY_GATE_* and TRACKER_CLI), and delivers a single cohesive instruction set to the agent.

Overstory uses an abstraction layer called AgentRuntime to interact with various agent CLIs (like Claude Code, Codex, or Copilot). The orchestration engine never calls a runtime's CLI directly; instead, it interacts exclusively with AgentRuntime methods. This decoupling allows the orchestrator to manage different agent types using a unified interface.

To use a specific runtime, the orchestrator resolves the appropriate adapter via the getRuntime() method from the runtime registry. The adapter then handles the specific CLI commands, configuration deployment, readiness detection, and transcript parsing for that particular tool.

Orchestrator / Lead Agent
        |
        | calls AgentRuntime methods only
        v
+---------------------------+
|     AgentRuntime          |
|  (src/runtimes/types.ts)  |
+---------------------------+
        |
        +--- ClaudeRuntime  (src/runtimes/claude.ts)
        |     claude --model ... --permission-mode ...
        |
        +--- CodexRuntime   (src/runtimes/codex.ts)
        |     codex exec --full-auto --json ...
        |
        +--- PiRuntime      (src/runtimes/pi.ts)
        |     pi --model <provider>/<model> ...
        |
        +--- CopilotRuntime (src/runtimes/copilot.ts)
        |     copilot --model ... --allow-all-tools
        |
        +--- CursorRuntime  (src/runtimes/cursor.ts)
              agent --model ... --yolo