### Install Dependencies and Start Dev Server

Source: https://github.com/jayminwest/overstory/blob/main/ui/README.md

Use these commands to install project dependencies and start the development server with Hot Module Replacement (HMR). The server runs on port 3000 and uses Tailwind v4 processed via `bun-plugin-tailwind`.

```bash
bun install
bun run dev
```

--------------------------------

### Build Print Command Examples

Source: https://github.com/jayminwest/overstory/blob/main/docs/runtime-adapters.md

Examples of argv arrays generated for headless, one-shot AI calls passed to Bun.spawn().

```typescript
// Claude Code
["claude", "--print", "-p", "Resolve this conflict...", "--model", "sonnet"]

// Codex (--ephemeral disables session persistence)
["codex", "exec", "--full-auto", "--ephemeral", "--model", "gpt-4o", "Resolve this conflict..."]

// Pi (prompt is the last positional argument)
["pi", "--print", "--model", "anthropic/claude-sonnet-4-6", "Resolve this conflict..."]

// Copilot
["copilot", "-p", "Resolve this conflict...", "--allow-all-tools", "--model", "gpt-4o"]

// Cursor
["agent", "-p", "Resolve this conflict...", "--yolo", "--model", "sonnet"]
```

--------------------------------

### Install Dependencies

Source: https://github.com/jayminwest/overstory/blob/main/CONTRIBUTING.md

Install project dependencies using Bun.

```bash
bun install
```

--------------------------------

### Build Spawn Command Examples

Source: https://github.com/jayminwest/overstory/blob/main/docs/runtime-adapters.md

Examples of shell command strings generated for different AI agent adapters based on SpawnOpts.

```typescript
// Claude Code — bypass mode with appended system prompt
claude --model claude-sonnet-4-6 --permission-mode bypassPermissions \
  --append-system-prompt 'You are a builder agent...'

// Codex — headless exec with AGENTS.md instruction
codex exec --full-auto --json --model gpt-4o \
  'Read AGENTS.md for your task assignment and begin immediately.'

// Pi — model alias expanded, appended system prompt
pi --model anthropic/claude-sonnet-4-6 \
  --append-system-prompt 'You are a builder agent...'

// Copilot — bypass mode via --allow-all-tools; appendSystemPrompt ignored
copilot --model gpt-4o --allow-all-tools

// Cursor — bypass mode via --yolo; appendSystemPrompt ignored
agent --model sonnet --yolo
```

--------------------------------

### Docker Run Command Example

Source: https://github.com/jayminwest/overstory/blob/main/docs/design/containerize-swarms.md

This is an example of how to run the Overstory swarm container, mapping port 8080.

```bash
docker run -p 8080:8080 overstory-swarm
```

--------------------------------

### Configuration File

Source: https://context7.com/jayminwest/overstory/llms.txt

Example YAML configuration for Overstory projects.

```yaml
# .overstory/config.yaml
project:
  name: my-project
  canonicalBranch: main
  qualityGates:
    - name: Tests
      command: bun test
      description: all tests must pass
    - name: Lint
      command: bun run lint
      description: zero errors

agents:
  maxConcurrent: 25
  staggerDelayMs: 2000
  maxDepth: 2
  maxSessionsPerRun: 0  # 0 = unlimited
  maxAgentsPerLead: 5

worktrees:
  baseDir: .overstory/worktrees

taskTracker:
  backend: auto  # auto, seeds, or beads
  enabled: true

mulch:
  enabled: true
  domains: []
  primeFormat: markdown

merge:
  aiResolveEnabled: true
  reimagineEnabled: false
```

--------------------------------

### Monitor and Start Coordinators

Source: https://github.com/jayminwest/overstory/blob/main/agents/orchestrator.md

Commands to verify the status of a sub-repo coordinator and initiate its startup process.

```bash
ov coordinator status --project <repo-path>
```

```bash
ov coordinator start --project <repo-path>
```

--------------------------------

### Install Overstory CLI Globally

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Installs the Overstory command-line interface globally using Bun. Requires Bun v1.0+.

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

--------------------------------

### Install Orchestrator Hooks

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Installs orchestrator hooks to `.claude/settings.local.json`. Use `--force` to overwrite existing hooks.

```bash
ov hooks install --force
```

--------------------------------

### Start Overstory Coordinator

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Starts the Overstory coordinator, which acts as a persistent orchestrator for the AI agent swarm.

```bash
ov coordinator start
```

--------------------------------

### Runtime Resolution Examples

Source: https://github.com/jayminwest/overstory/blob/main/docs/runtime-adapters.md

Demonstrates how to invoke the registry to retrieve specific runtime instances.

```typescript
// Default runtime for the project
const runtime = getRuntime(undefined, config);

// Explicit override (from ov sling --runtime flag)
const runtime = getRuntime("codex", config);

// Pi with model alias expansion from config
const runtime = getRuntime("pi", config);
// => new PiRuntime(config.runtime.pi)
```

--------------------------------

### Set Up Overstory for Development

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Clones the Overstory repository, installs dependencies, links the CLI globally, and provides commands for running tests and linting.

```bash
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
```

--------------------------------

### Example Test Structure

Source: https://github.com/jayminwest/overstory/blob/main/CONTRIBUTING.md

An example of a test file structure using Bun's testing utilities. Emphasizes using real filesystems and databases, with cleanup in afterEach.

```typescript
import { mkdtemp, rm } from "node:fs/promises";
import { join } from "node:path";
import { tmpdir } from "node:os";
import { afterEach, beforeEach, describe, it, expect } from "bun:test";

describe("my-feature", () => {
  let testDir: string;

  beforeEach(async () => {
    testDir = await mkdtemp(join(tmpdir(), "overstory-test-"));
  });

  afterEach(async () => {
    await rm(testDir, { recursive: true });
  });

  it("does the thing", async () => {
    // Write real files, run real code, assert real results
  });
});
```

--------------------------------

### Overstory CLI: Serve Web UI

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Starts the HTTP + WebSocket surface for the web UI. Specify the port with '--port' and the bind host with '--host'. JSON output is available.

```bash
ov serve
  --port <n>                             Port (default: 7321)
  --host <addr>                          Bind host (default: 127.0.0.1)
  --json                                 JSON output
  Routes: /healthz, /api/runs, /api/agents, /api/events, /api/mail,
          /ws (per-run/per-agent/mail rooms), SPA fallback to ui/dist
```

--------------------------------

### Start Watchdog Daemon

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Starts the watchdog daemon for Tier 0 monitoring. Options include `--interval` for checking frequency and `--background` to run in the background.

```bash
ov watch --interval 5s --background
```

--------------------------------

### Configure Mixed Swarms

Source: https://github.com/jayminwest/overstory/blob/main/docs/runtime-adapters.md

Example commands for launching agents with different runtimes within a single swarm.

```bash
ov sling task-001 --capability builder --name claude-builder --runtime claude
ov sling task-002 --capability builder --name codex-builder --runtime codex
ov sling task-003 --capability scout   --name pi-scout       --runtime pi
```

--------------------------------

### Serve Overstory Web UI

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Starts the Overstory web UI, providing the primary interface for monitoring and interacting with the agent swarm. Access it at http://localhost:7321.

```bash
ov serve
```

--------------------------------

### Serve Overstory Web UI

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Starts the HTTP and WebSocket server for the Overstory web UI. Specify `--port`, `--host`, or `--json` for configuration.

```bash
ov serve --port 8080 --host 0.0.0.0 --json
```

--------------------------------

### SQLite Database Setup with Bun:SQL

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Configure SQLite databases using bun:sqlite, ensuring WAL mode and a busy timeout for concurrent access.

```typescript
import { Database } from "bun:sqlite";
const db = new Database(dbPath);
db.exec("PRAGMA journal_mode=WAL");
db.exec("PRAGMA busy_timeout=5000");
```

--------------------------------

### Run Overstory CLI Without Installation

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Executes the Overstory command-line interface without a global installation using npx. Useful for trying out commands.

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

--------------------------------

### Install Overstory Hooks

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Installs Overstory hooks, likely for integrating with your project's workflow or version control. Configuration is saved to .claude/settings.local.json.

```bash
ov hooks install
```

--------------------------------

### Pi JSONL Event Example

Source: https://github.com/jayminwest/overstory/blob/main/docs/runtime-abstraction.md

Example of a JSONL formatted event message from the Pi agent in JSON mode, showing message end with token counts.

```jsonl
{"type":"message_end","message":{...},"inputTokens":1500,"outputTokens":420}
```

--------------------------------

### Mulch - Priming Project Expertise

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Command to prime the session context with project-specific conventions, patterns, and guides using Mulch.

```bash
ml prime
```

--------------------------------

### Dispatch Parallel Scouts for Exploration

Source: https://github.com/jayminwest/overstory/blob/main/agents/lead.md

This example shows how to dispatch two scouts in parallel for tasks spanning multiple areas. One scout focuses on implementation files, and the other on tests and interfaces. This approach avoids redundant work and allows for concurrent exploration.

```bash
# Scout 1: implementation files
{{TRACKER_CLI}} create --title="Scout: explore implementation for <objective>" --type=task --priority=2
ov sling <scout1-bead-id> --capability scout --name <scout1-name> \
  --parent $OVERSTORY_AGENT_NAME --depth <current+1>
ov mail send --to <scout1-name> --subject "Explore: implementation" \
  --body "Investigate implementation files: <files>. Report: patterns, types, dependencies." \
  --type dispatch

# Scout 2: tests and interfaces
{{TRACKER_CLI}} create --title="Scout: explore tests/types for <objective>" --type=task --priority=2
ov sling <scout2-bead-id> --capability scout --name <scout2-name> \
  --parent $OVERSTORY_AGENT_NAME --depth <current+1>
ov mail send --to <scout2-name> --subject "Explore: tests and interfaces" \
  --body "Investigate test files and type definitions: <files>. Report: test patterns, type contracts." \
  --type dispatch
```

--------------------------------

### Shell Completion Generation

Source: https://context7.com/jayminwest/overstory/llms.txt

Commands to generate and install shell completion scripts for bash, zsh, and fish.

```bash
# Generate bash completions
ov completions bash > /etc/bash_completion.d/ov

# Generate zsh completions
ov completions zsh > ~/.zsh/completions/_ov

# Generate fish completions
ov completions fish > ~/.config/fish/completions/ov.fish
```

--------------------------------

### Initialize Canopy Prompt Workflow

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Run this command at the start of every session to inject prompt workflow context, including commands, conventions, and common workflows.

```bash
cn prime
```

--------------------------------

### Initialize Overstory Project

Source: https://context7.com/jayminwest/overstory/llms.txt

Sets up the .overstory/ directory structure and configuration files.

```bash
# Initialize overstory in your project
ov init

# Initialize with specific options
ov init --name my-project --yes

# Skip specific ecosystem tools during bootstrap
ov init --skip-mulch --skip-seeds

# Reinitialize existing project (preserves data, updates config)
ov init --force

# Output result as JSON
ov init --json
```

--------------------------------

### Commit Message Examples

Source: https://github.com/jayminwest/overstory/blob/main/CONTRIBUTING.md

Examples of commit messages following the conventional commit style, prefixed with category.

```git
fix: resolve merge conflict detection for renamed files
```

```git
feat: add dashboard live-refresh interval option
```

```git
docs: update CLI reference with new nudge flags
```

--------------------------------

### Build Static Bundle

Source: https://github.com/jayminwest/overstory/blob/main/ui/README.md

Execute this command to create a static bundle of the UI application. The output is placed in `ui/dist/` and is served by the `ov serve` command.

```bash
bun run build
```

--------------------------------

### Load Expertise Context with ml prime

Source: https://github.com/jayminwest/overstory/blob/main/agents/lead.md

Prime the expertise system with context. Use '--files' to scope expertise to specific files or provide a domain name for broader context.

```bash
ml prime --files <file1,file2,...>
```

```bash
ml prime [domain]
```

--------------------------------

### Initialize New Overstory Project

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Initializes a new Overstory project, setting `runtime.claudeHeadlessByDefault: true` in `config.yaml` by default.

```bash
ov init
```

--------------------------------

### Codex Agent Event Stream Examples

Source: https://github.com/jayminwest/overstory/blob/main/docs/runtime-abstraction.md

Examples of NDJSON events emitted by a Codex agent when using the --json flag. Overstory parses these events for lifecycle tracking and metrics.

```json
{"type":"thread.started","thread_id":"...","session_id":"..."}
```

```json
{"type":"turn.started"}
```

```json
{"type":"item.created","item":{"type":"message","role":"assistant","content":[{"type":"text","text":"..."}]}}
```

```json
{"type":"item.created","item":{"type":"command","command":"bash","args":["bun test"]}}
```

```json
{"type":"item.created","item":{"type":"file_change","path":"src/foo.ts","action":"edit"}}
```

```json
{"type":"turn.completed","usage":{"input_tokens":1234,"output_tokens":567}}
```

```json
{"type":"thread.completed"}
```

--------------------------------

### Manage Orchestrator Hooks

Source: https://context7.com/jayminwest/overstory/llms.txt

Installs or removes orchestrator hooks for integration with tools like Claude Code.

```bash
# Install hooks to .claude/settings.local.json
ov hooks install

# Force overwrite existing hooks
ov hooks install --force

# Check if hooks are installed
ov hooks status

# Remove orchestrator hooks
ov hooks uninstall
```

--------------------------------

### Load Project Conventions

Source: https://github.com/jayminwest/overstory/blob/main/agents/reviewer.md

Load project-specific conventions and standards using the 'ml prime' command. Optionally specify a domain to focus the loaded expertise.

```bash
ml prime [domain]
```

--------------------------------

### Run ID from SwarmContext

Source: https://github.com/jayminwest/overstory/blob/main/docs/design/containerize-swarms.md

Example demonstrating how to obtain the run ID from SwarmContext instead of reading from a file.

```typescript
// All 9 callsites take runId from SwarmContext instead of reading the file.
```

--------------------------------

### Overstory CLI: Ecosystem Version Check

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Displays the versions and health of the os-eco tools. Use '--json' for JSON output.

```bash
ov ecosystem
  --json                                 JSON output
```

--------------------------------

### Configure Anthropic Provider in Overstory

Source: https://github.com/jayminwest/overstory/blob/main/docs/runtime-adapters.md

Define the configuration for the Anthropic AI provider. This example shows a 'native' type provider.

```yaml
providers:
  anthropic:
    type: native
```

--------------------------------

### Observability and Logging

Source: https://context7.com/jayminwest/overstory/llms.txt

Query logs, traces, metrics, and costs across the agent fleet.

```bash
# Query NDJSON logs across agents
ov logs --agent builder-123 --level error

# Follow logs in real-time
ov logs --follow

# View agent/task timeline
ov trace --agent builder-123

# View timeline since a specific time
ov trace --since "2024-01-01T00:00:00Z" --limit 100

# Aggregated error view
ov errors --agent builder-123

# Unified real-time event stream
ov feed --follow

# Interleaved chronological replay
ov replay --run run-2024-01-01

# Token/cost analysis
ov costs --live
ov costs --by-capability
ov costs --agent builder-123

# Session metrics
ov metrics --last 10
```

--------------------------------

### Seeds - Session Priming

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Command to run at the start of every session to inject session context, including rules, command reference, and workflows.

```bash
sd prime
```

--------------------------------

### Run Build and Test Commands

Source: https://github.com/jayminwest/overstory/blob/main/CONTRIBUTING.md

Commands to run tests, lint, format, and type check the project. Ensure all quality gates pass before submitting a PR.

```bash
bun test
```

```bash
bun test src/config.test.ts
```

```bash
biome check .
```

```bash
biome check --write .
```

```bash
tsc --noEmit
```

```bash
bun test && biome check . && tsc --noEmit
```

--------------------------------

### RuntimeConnection Interface Definition

Source: https://github.com/jayminwest/overstory/blob/main/docs/runtime-adapters.md

Defines the methods for managing an RPC connection to an agent process, including sending prompts, aborting, and getting state.

```typescript
export interface RuntimeConnection {
  /** Send initial prompt after spawn. */
  sendPrompt(text: string): Promise<void>;
  /** Send follow-up message — replaces tmux send-keys. */
  followUp(text: string): Promise<void>;
  /** Clean shutdown — replaces SIGTERM. */
  abort(): Promise<void>;
  /** Query current state — replaces tmux capture-pane. */
  getState(): Promise<ConnectionState>;
  /** Release connection resources. */
  close(): void;
}
```

--------------------------------

### Coordinator Agent Commands

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Commands for managing the persistent coordinator agent, including starting, stopping, checking status, sending messages, and retrieving output.

```APIDOC
## ov coordinator <sub>

### Description
Persistent coordinator agent commands.

### Commands
- **start**
  - Description: Start coordinator (spawns Claude Code at root).
  - Options:
    - `--attach / --no-attach`: Control tmux attach (default: attach on TTY).
    - `--watchdog`: Auto-start watchdog daemon.
    - `--monitor`: Auto-start Tier 2 monitor agent.
    - `--profile <name>`: Named profile for canopy prompt overlay.
- **stop**
  - Description: Stop coordinator (kills tmux session).
- **status**
  - Description: Show coordinator state.
- **send <body>**
  - Description: Fire-and-forget message to coordinator (mail + auto-nudge).
  - Options:
    - `--subject <text>`: Message subject (required).
- **ask <body>**
  - Description: Synchronous request/response to coordinator.
  - Options:
    - `--subject <text>`: Message subject (required).
    - `--timeout <seconds>`: Reply timeout (default: 120).
- **output**
  - Description: Show recent coordinator output (tmux pane content).
  - Options:
    - `--lines <n>`: Number of lines to capture (default: 100).
- **check-complete**
  - Description: Evaluate exit triggers, return completion status.
  - Options:
    - `--json`: JSON output.
```

--------------------------------

### Mulch - Learning and Syncing

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Commands to discover what to record by showing changed files and suggesting domains, and to validate and commit recorded insights.

```bash
ml learn
ml sync
```

--------------------------------

### Serve Command Project Resolution

Source: https://github.com/jayminwest/overstory/blob/main/docs/design/containerize-swarms.md

This code block in 'ov serve' resolves a single project at startup. Fleet mode requires a Map keyed by swarmId to handle multiple projects.

```typescript
src/commands/serve.ts:312-324
```

--------------------------------

### Link CLI for Local Development

Source: https://github.com/jayminwest/overstory/blob/main/CONTRIBUTING.md

Link the Overstory CLI for local development to test changes without publishing.

```bash
bun link
```

--------------------------------

### Quality Gate Checks via package.json Scripts

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Alternative commands to run quality gates using npm scripts defined in package.json.

```bash
bun run test                          # bun test
bun run lint                          # biome check .
bun run typecheck                     # tsc --noEmit
```

--------------------------------

### Overstory CLI: Hooks Management

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Commands for managing orchestrator hooks, including installation, uninstallation, and status checks. Use '--force' to overwrite existing hooks.

```bash
ov hooks install
  --force                              Overwrite existing hooks
ov hooks uninstall
ov hooks status
  --json                                 JSON output
```

--------------------------------

### Manage Expertise

Source: https://github.com/jayminwest/overstory/blob/main/agents/supervisor.md

Commands for loading domain context, recording insights, and searching the knowledge base.

```bash
ml prime [domain]
```

```bash
ml record <domain> --type <type> --description "<insight>"
```

```bash
ml search <query>
```

```bash
ml search <query> --file <path>
```

--------------------------------

### Run Overstory Health Checks

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Runs health checks on the Overstory setup. Use `--category`, `--fix`, or `--json` to customize the check or output.

```bash
ov doctor --fix --json
```

--------------------------------

### Deploy Pi Configuration Files

Source: https://github.com/jayminwest/overstory/blob/main/docs/runtime-abstraction.md

Deploys necessary configuration files for the Pi agent, including CLAUDE.md, guard extensions, and settings.json. Creates directories as needed.

```typescript
async deployConfig(worktreePath, overlay, hooks) {
    // Pi reads .claude/CLAUDE.md natively — use existing overlay path
    const claudeDir = join(worktreePath, ".claude");
    await mkdir(claudeDir, { recursive: true });
    await Bun.write(join(claudeDir, "CLAUDE.md"), overlay.content);

    // Deploy guard extension instead of settings.local.json hooks
    const piExtDir = join(worktreePath, ".pi", "extensions");
    await mkdir(piExtDir, { recursive: true });
    await Bun.write(
      join(piExtDir, "overstory-guard.ts"),
      generatePiGuardExtension(hooks)
    );

    // Deploy Pi settings (model, tools config)
    const piDir = join(worktreePath, ".pi");
    await Bun.write(
      join(piDir, "settings.json"),
      JSON.stringify({ extensions: ["./extensions"] }, null, 2)
    );
  }
```

--------------------------------

### Overstory CLI: Watchdog Daemon

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Starts the watchdog daemon for Tier 0 monitoring. The '--interval' flag sets the check interval in milliseconds, and '--background' runs it in the background.

```bash
ov watch
  --interval <ms>  --background
```

--------------------------------

### buildPrintCommand

Source: https://github.com/jayminwest/overstory/blob/main/docs/runtime-adapters.md

Builds an argv array for a headless, one-shot AI call, suitable for passing to Bun.spawn().

```APIDOC
## buildPrintCommand(prompt: string, model?: string)

### Description
Builds an argv array for a headless, one-shot AI call. Used for AI-assisted conflict resolution and failure classification.

### Parameters
#### Query Parameters
- **prompt** (string) - Required - The prompt to send to the AI
- **model** (string) - Optional - The model to use for the call
```

--------------------------------

### Lazy-load NVM for Shell Initialization

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Optimize shell startup by lazy-loading NVM (Node Version Manager). This ensures NVM is only activated when you first use `nvm`, `node`, or `npm` commands.

```bash
# Lazy-load nvm — only activates when you first call nvm/node/npm
export NVM_DIR="$HOME/.nvm"
nvm() { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; nvm "$@"; }
node() { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; node "$@"; }
npm()  { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; npm  "$@"; }
npx()  { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; npx  "$@"; }
```

--------------------------------

### Initialize Overstory in a Project

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Initializes Overstory within your project directory. This command sets up the necessary Overstory configuration.

```bash
cd your-project
ov init
```

--------------------------------

### Start Mail Injection Loop for Headless Agent

Source: https://github.com/jayminwest/overstory/blob/main/docs/headless-hooks-design.md

Initiates a loop to poll a mail store for unread messages and inject them into a headless agent's stdin. Returns a cleanup function to stop the polling.

```typescript
/**
 * Start a mail injection loop for a headless agent.
 *
 * Polls the mail store every `intervalMs` milliseconds. On unread mail,
 * formats a user turn and writes to the agent's stdin.
 *
 * Returns a cleanup function to stop the loop.
 */
export function startMailInjectionLoop(
  agentName: string,
  stdin: HeadlessProcess["stdin"],
  mailStorePath: string,
  intervalMs = 2000,
): () => void {
  const timer = setInterval(async () => {
    const store = createMailStore(mailStorePath);
    try {
      const messages = store.check(agentName);
      if (messages.length === 0) return;

      const text = messages
        .map((m) => `[MAIL] From: ${m.from} | Subject: ${m.subject}\n\n${m.body}`)
        .join("\n\n---\n\n");

      const turn = {
        type: "user",
        message: { role: "user", content: [{ type: "text", text }] },
      };
      await stdin.write(`${JSON.stringify(turn)}\n`);
    } finally {
      store.close();
    }
  }, intervalMs);

  return () => clearInterval(timer);
}
```

--------------------------------

### Overstory CLI: Upgrade Overstory

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Upgrades Overstory to the latest npm version. Use '--check' to compare versions without installing, or '--all' to upgrade all four ecosystem tools. JSON output is available.

```bash
ov upgrade
  --check                                Compare versions without installing
  --all                                  Upgrade all 4 ecosystem tools
  --json                                 JSON output
```

--------------------------------

### Running Tests with Bun

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Execute all tests using the 'bun test' command. For running a single test file, specify its path, e.g., 'bun test src/config.test.ts'.

```bash
bun test
bun test src/config.test.ts
```

--------------------------------

### Overstory CLI: Monitor Management

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Commands for managing the Tier 2 monitor agent. Use 'start' to spawn Claude Code at the root, 'stop' to kill the tmux session, and 'status' to view the monitor state.

```bash
ov monitor <sub>
  start                                  Start monitor (spawns Claude Code at root)
  stop                                   Stop monitor (kills tmux session)
  status                                 Show monitor state
```

--------------------------------

### deployConfig

Source: https://github.com/jayminwest/overstory/blob/main/docs/runtime-adapters.md

Deploys per-agent instructions and security guards to a worktree before spawning an agent.

```APIDOC
## deployConfig(worktreePath, overlay, hooks)

### Description
Deploys per-agent instructions and security guards to a worktree before spawn. When overlay is undefined, only guards are deployed.

### Parameters
#### Request Body
- **worktreePath** (string) - Required - Path to the worktree
- **overlay** (OverlayContent) - Optional - Content for the agent's instruction file
- **hooks** (HooksDef) - Required - Hook definitions including agent name, capability, and quality gates
```

--------------------------------

### Integration Test for Headless Claude Agent

Source: https://github.com/jayminwest/overstory/blob/main/docs/headless-hooks-design.md

This test verifies the behavior of a headless Claude agent receiving dispatch mail and prime context via stdin. It mocks the agent to validate the protocol without requiring a full AI setup.

```typescript
import { test } from "bun:test";
import { buildInitialHeadlessPrompt } from "../src/headless/prompt-builder";
import { startMailInjectionLoop } from "../src/headless/mail-injection";
import { deployConfig } from "../src/config/deploy-config";
import { mailClient } from "../src/mail/client";
import { createMockAgent } from "./mock-agent";
import { primeContext, dispatch, beacon } from "./test-data";

// Mock the mail client to prevent actual sending during tests
mailClient.send = async () => {};

test("headless Claude agent receives dispatch mail and prime context via stdin", async () => {
  const { agentStdin, agentProcess } = await createMockAgent();

  // 1. Deploy config, asserting hooks are skipped in headless mode
  deployConfig({ isHeadless: true });
  // Assert .claude/settings.local.json does NOT exist
  const settingsPath = ".claude/settings.local.json";
  const settingsExists = await Bun.file(settingsPath).exists();
  if (settingsExists) {
    throw new Error(".claude/settings.local.json should not exist in headless mode");
  }

  // 2. Build initial prompt and send to mock agent's stdin
  const initialPrompt = buildInitialHeadlessPrompt(primeContext, dispatch, beacon);
  agentStdin.write(initialPrompt + "\n");

  // 3. Start mail injection loop and send a test mail
  const injectionLoopPromise = startMailInjectionLoop();
  const testMail = "Subject: Test Mail\n\nThis is a test email.";
  await mailClient.send(testMail);

  // Wait for the injection loop to process the mail (or a short timeout)
  await new Promise((resolve) => setTimeout(resolve, 3000));

  // 4. Assert mock agent received all components
  const agentOutput = await agentProcess.stdout.text();

  if (!agentOutput.includes(initialPrompt)) {
    throw new Error("Mock agent did not receive initial prompt");
  }
  if (!agentOutput.includes(testMail)) {
    throw new Error("Mock agent did not receive test mail");
  }

  // Clean up the mock agent process
  agentProcess.kill();
});

```

--------------------------------

### Write Instructions to AGENTS.md

Source: https://github.com/jayminwest/overstory/blob/main/docs/runtime-abstraction.md

This TypeScript code demonstrates how Overstory's adapter would write overlay content to AGENTS.md when the runtime is Codex. This file serves as the primary instruction source for the agent.

```typescript
const instructionPath = join(worktreePath, "AGENTS.md");
await Bun.write(instructionPath, overlayContent);
```

--------------------------------

### Clone Repository

Source: https://github.com/jayminwest/overstory/blob/main/CONTRIBUTING.md

Clone your forked repository locally and navigate into the project directory.

```bash
git clone https://github.com/<your-username>/overstory.git
cd overstory
```

--------------------------------

### Overstory CLI: Doctor Health Checks

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Runs health checks on the Overstory setup. Use '--category' to specify a single category, '--fix' to auto-fix issues, and '--verbose' for more details. JSON output is available with '--json'.

```bash
ov doctor
  --category <name>                      Run one category only
  --fix                                  Auto-fix fixable issues
  --verbose                              Show passing checks too
  --json                                 JSON output
  Categories: dependencies, config, structure, databases,
              consistency, agents, merge, logs, version,
              ecosystem, providers, watchdog, serve
```

--------------------------------

### Measure Shell Startup Time

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Measure the initialization time of your shell to diagnose slow coordinator startup issues. Adjust `shellInitDelayMs` in `.overstory/config.yaml` based on these timings.

```bash
time zsh -i -c exit   # For zsh
```

```bash
time bash -i -c exit  # For bash
```

--------------------------------

### Manage Orchestration Runs

Source: https://context7.com/jayminwest/overstory/llms.txt

List, show, and complete orchestration runs.

```bash
# List orchestration runs
ov run list

# Show run details
ov run show run-2024-01-01T12-00-00

# Mark current run as completed
ov run complete
```

--------------------------------

### Test Helper: Create Git Repository

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Initializes a real Git repository in a temporary directory with an initial commit. This is a utility function for testing file and Git-related operations.

```typescript
createTempGitRepo()
```

--------------------------------

### Reduce Oh My Zsh Plugins

Source: https://github.com/jayminwest/overstory/blob/main/README.md

Improve shell startup performance by reducing the number of plugins loaded by Oh My Zsh. Edit your `~/.zshrc` file to keep only essential plugins.

```bash
# Before: plugins=(git zsh-autosuggestions zsh-syntax-highlighting node npm python ruby rbenv pyenv ...)
# After: keep only what you use regularly
plugins=(git)
```

--------------------------------

### Build Initial Headless Prompt

Source: https://github.com/jayminwest/overstory/blob/main/docs/headless-hooks-design.md

Constructs the initial prompt for a headless Claude agent by combining prime context, dispatch mail, and an activation phrase. The output is a JSON line formatted for the agent's stdin.

```typescript
/**
 * Build the initial stdin prompt for a headless Claude agent.
 *
 * Combines prime context (mulch expertise, session state) with pending
 * dispatch mail and the activation phrase.
 *
 * @param primeContext - Output of `ov prime --agent <name>` (may be empty)
 * @param dispatchMail - Pre-formatted dispatch mail body (may be empty)
 * @param beacon - Activation phrase (e.g. "Read your overlay and begin.")
 * @returns JSON line ready to write to the agent's stdin
 */
export function buildInitialHeadlessPrompt(
  primeContext: string,
  dispatchMail: string,
  beacon: string,
): string {
  const parts: string[] = [];
  if (primeContext) parts.push(primeContext);
  if (dispatchMail) parts.push(dispatchMail);
  if (beacon) parts.push(beacon);

  const text = parts.join("\n\n---\n\n");
  const message = {
    type: "user",
    message: { role: "user", content: [{ type: "text", text }] },
  };
  return `${JSON.stringify(message)}\n`;
}
```

--------------------------------

### Spawn Direct Builder Agent (Low-Budget Fallback)

Source: https://github.com/jayminwest/overstory/blob/main/agents/coordinator.md

Spawn a builder agent directly for small, concrete tasks. This bypasses the lead/spec cycle when a separate lead is unnecessary overhead, suitable for low-budget operations.

```bash
# Direct builder for a small, concrete task that does not need a separate lead/spec cycle
ov sling <task-id> --capability builder --name <builder-name> --depth 1
```

--------------------------------

### List All Prompts with Canopy

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Use this command to list all available prompts managed by Canopy.

```bash
cn list
```

--------------------------------

### Task Specification Management

Source: https://context7.com/jayminwest/overstory/llms.txt

Commands to create task specification files for agents, optionally including attribution.

```bash
# Write a spec file
ov spec write issue-123 --body "## Objective\nImplement the new API endpoint..."

# Write spec with attribution
ov spec write issue-123 --body "..." --agent coordinator
```

--------------------------------

### Create Task Group

Source: https://github.com/jayminwest/overstory/blob/main/agents/coordinator.md

Create a task group to track a batch of tasks. Provide a name for the batch and the IDs of the tasks to be included.

```bash
ov group create '<batch-name>' <task-id-1> <task-id-2> [<task-id-3>...]
```

--------------------------------

### Tracker CLI Commands

Source: https://github.com/jayminwest/overstory/blob/main/agents/lead.md

Manage tracker items using the tracker CLI. Available commands include create, show, ready, close, update, and sync.

```bash
{{TRACKER_CLI}} create
```

```bash
{{TRACKER_CLI}} show
```

```bash
{{TRACKER_CLI}} ready
```

```bash
{{TRACKER_CLI}} close
```

```bash
{{TRACKER_CLI}} update
```

```bash
{{TRACKER_CLI}} sync
```

--------------------------------

### Mulch - Structured Expertise Commands

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Commands for managing project expertise using Mulch, including priming prompts, recording insights, and searching across domains.

```bash
mulch prime [domain]                  # Output priming prompt
mulch status                          # Show domain statistics
mulch record <domain>                 # Record expertise
mulch search [query]                  # Search across domains
```

--------------------------------

### Quality Gate Checks

Source: https://github.com/jayminwest/overstory/blob/main/CLAUDE.md

Commands to run all quality gates: tests, linting, and type checking. These should be run before committing.

```bash
bun test                              # Tests pass
biome check .                         # Linting + formatting clean
tsc --noEmit                          # Type checking passes
```