claude-octopus 1.0.5 → 1.1.2

package/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm test

package/.github/workflows/sdk-watch.yml

@@ -0,0 +1,86 @@
+name: SDK watch — auto-bump Agent SDK
+
+on:
+  schedule:
+    # Every 6 hours
+    - cron: "0 */6 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  check-and-bump:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      # ── Detect new SDK version ─────────────────────────────────
+      - name: Check for SDK update
+        id: check
+        run: |
+          CURRENT=$(node -e "console.log(require('./node_modules/@anthropic-ai/claude-agent-sdk/package.json').version)")
+          LATEST=$(npm view @anthropic-ai/claude-agent-sdk version)
+          echo "current=$CURRENT" >> "$GITHUB_OUTPUT"
+          echo "latest=$LATEST"   >> "$GITHUB_OUTPUT"
+          if [ "$CURRENT" = "$LATEST" ]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # ── Bump SDK ───────────────────────────────────────────────
+      - name: Update SDK dependency
+        if: steps.check.outputs.skip == 'false'
+        run: pnpm add @anthropic-ai/claude-agent-sdk@latest
+
+      # ── Build + test ───────────────────────────────────────────
+      - name: Build
+        if: steps.check.outputs.skip == 'false'
+        run: pnpm build
+
+      - name: Test
+        if: steps.check.outputs.skip == 'false'
+        run: pnpm test
+
+      # ── Bump octopus patch version ─────────────────────────────
+      - name: Bump patch version
+        if: steps.check.outputs.skip == 'false'
+        id: version
+        run: |
+          NEW_VERSION=$(node -e "
+            const pkg = require('./package.json');
+            const [maj, min, pat] = pkg.version.split('.').map(Number);
+            console.log(maj + '.' + min + '.' + (pat + 1));
+          ")
+          pnpm pkg set version="$NEW_VERSION"
+          echo "version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+
+      # ── Commit + push ──────────────────────────────────────────
+      - name: Commit and push
+        if: steps.check.outputs.skip == 'false'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add package.json pnpm-lock.yaml
+          git commit -m "chore: bump agent-sdk ${{ steps.check.outputs.current }} -> ${{ steps.check.outputs.latest }}, release v${{ steps.version.outputs.version }}"
+          git push
+
+      # ── Publish to npm ─────────────────────────────────────────
+      - name: Publish
+        if: steps.check.outputs.skip == 'false'
+        run: pnpm publish --no-git-checks --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -30,14 +30,22 @@ Or skip the install entirely — use `npx` directly in your `.mcp.json` (see Qui
 
 ## Quick Start
 
-Add to your `.mcp.json`:
+The fastest way to get started:
+
+```bash
+npx claude-octopus init
+```
+
+This interactive wizard lets you pick a template, detects your MCP client, and writes the config for you.
+
+Or add to your `.mcp.json` manually:
 
 ```json
 {
   "mcpServers": {
     "claude": {
       "command": "npx",
-      "args": ["claude-octopus"],
+      "args": ["claude-octopus@latest"],
       "env": {
         "CLAUDE_PERMISSION_MODE": "bypassPermissions"
       }
@@ -46,7 +54,17 @@ Add to your `.mcp.json`:
 }
 ```
 
-This gives you two tools: `claude_code` and `claude_code_reply`. That's it — you have Claude Code as a tool.
+This gives you five tools:
+
+| Tool | Purpose |
+|------|---------|
+| `claude_code` | Send a task, get a result |
+| `claude_code_reply` | Continue a conversation |
+| `claude_code_timeline` | Query the workflow timeline |
+| `claude_code_transcript` | Read full session transcripts |
+| `claude_code_report` | Generate HTML reports |
+
+That's it — you have Claude Code as a tool, with full workflow observability built in.
 
 ## Multiple Agents
 
@@ -57,7 +75,7 @@ The real power is running several instances with different configurations:
   "mcpServers": {
     "code-reviewer": {
       "command": "npx",
-      "args": ["claude-octopus"],
+      "args": ["claude-octopus@latest"],
       "env": {
         "CLAUDE_TOOL_NAME": "code_reviewer",
         "CLAUDE_SERVER_NAME": "code-reviewer",
@@ -70,7 +88,7 @@ The real power is running several instances with different configurations:
     },
     "test-writer": {
       "command": "npx",
-      "args": ["claude-octopus"],
+      "args": ["claude-octopus@latest"],
       "env": {
         "CLAUDE_TOOL_NAME": "test_writer",
         "CLAUDE_SERVER_NAME": "test-writer",
@@ -81,7 +99,7 @@ The real power is running several instances with different configurations:
     },
     "quick-qa": {
       "command": "npx",
-      "args": ["claude-octopus"],
+      "args": ["claude-octopus@latest"],
       "env": {
         "CLAUDE_TOOL_NAME": "quick_qa",
         "CLAUDE_SERVER_NAME": "quick-qa",
@@ -95,7 +113,32 @@ The real power is running several instances with different configurations:
 }
 ```
 
-Your MCP client now sees three distinct tools — `code_reviewer`, `test_writer`, `quick_qa` — each purpose-built.
+Your MCP client now sees distinct tools for each agent — `code_reviewer`, `test_writer`, `quick_qa` — each purpose-built.
+
+## Multi-Agent Orchestration
+
+Agents can coordinate through a **coordinator pattern**: one agent has the others as inner MCP tools via `CLAUDE_MCP_SERVERS`, and its system prompt drives the pipeline.
+
+```json
+{
+  "mcpServers": {
+    "publishing-house": {
+      "command": "npx",
+      "args": ["claude-octopus@latest"],
+      "env": {
+        "CLAUDE_TOOL_NAME": "publishing_house",
+        "CLAUDE_SERVER_NAME": "publishing-house",
+        "CLAUDE_MODEL": "opus",
+        "CLAUDE_PERMISSION_MODE": "bypassPermissions",
+        "CLAUDE_APPEND_PROMPT": "You are a publishing house coordinator. Dispatch tasks to your specialist agents and drive the pipeline to completion.",
+        "CLAUDE_MCP_SERVERS": "{\"researcher\":{\"command\":\"npx\",\"args\":[\"claude-octopus@latest\"],\"env\":{\"CLAUDE_TOOL_NAME\":\"researcher\",\"CLAUDE_SERVER_NAME\":\"researcher\",\"CLAUDE_MODEL\":\"sonnet\",\"CLAUDE_PERMISSION_MODE\":\"bypassPermissions\"}},\"architect\":{\"command\":\"npx\",\"args\":[\"claude-octopus@latest\"],\"env\":{\"CLAUDE_TOOL_NAME\":\"architect\",\"CLAUDE_SERVER_NAME\":\"architect\",\"CLAUDE_MODEL\":\"opus\",\"CLAUDE_PERMISSION_MODE\":\"bypassPermissions\"}}}"
+      }
+    }
+  }
+}
+```
+
+The coordinator agent autonomously calls `researcher`, `architect`, etc. as MCP tools — fully autonomous, no human in the loop until it finishes. Every invocation is tracked in the shared timeline.
 
 ## Agent Factory
 
@@ -106,7 +149,7 @@ Don't want to write configs by hand? Add a factory instance:
   "mcpServers": {
     "agent-factory": {
       "command": "npx",
-      "args": ["claude-octopus"],
+      "args": ["claude-octopus@latest"],
       "env": {
         "CLAUDE_FACTORY_ONLY": "true",
         "CLAUDE_SERVER_NAME": "agent-factory"
@@ -120,31 +163,209 @@ This exposes a single `create_claude_code_mcp` tool — an interactive wizard. T
 
 In factory-only mode, no query tools are registered — just the wizard. This keeps routing clean: the factory creates agents, the agents do work.
 
+## Init Wizard
+
+Don't want to edit JSON by hand? The init wizard gets you from zero to working in 30 seconds:
+
+```bash
+npx claude-octopus init
+```
+
+```
+  Claude Octopus — init wizard
+
+  One brain, many arms. Let's set up your agents.
+
+Pick a template (or build your own):
+
+  1. Code Review Team — Reviewer + test writer + security auditor
+  2. Publishing House — Researcher + architect + editor + proofreader
+  3. Tiered Models — Haiku for quick Q&A, Sonnet for coding, Opus for hard problems
+  4. Solo Agent — Single Claude Code agent with sensible defaults
+  5. Agent Factory — Interactive wizard that generates agent configs on demand
+  6. Custom — describe your own agent(s)
+
+Choice [1-6]:
+```
+
+It auto-detects installed MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf), merges with existing config, and warns before overwriting.
+
+### Skip the menu
+
+```bash
+npx claude-octopus init --template code-review-team
+npx claude-octopus init --template tiered-models
+npx claude-octopus init --template publishing-house
+```
+
+## Templates
+
+Five built-in templates, battle-tested and ready to use:
+
+| Template | Agents | Purpose |
+|----------|--------|---------|
+| `code-review-team` | code-reviewer (opus), test-writer (sonnet), security-auditor (opus) | Thorough code review pipeline |
+| `publishing-house` | researcher (sonnet), architect (opus), editor (sonnet), proofreader (haiku) | Multi-stage content/code pipeline |
+| `tiered-models` | quick-qa (haiku), coder (sonnet), deep-thinker (opus) | Right model for the job |
+| `solo-agent` | claude (default) | Single agent, quick setup |
+| `factory` | agent-factory | Generates configs on demand |
+
+Each agent comes pre-tuned with appropriate model, tools, effort level, and system prompt.
+
+## Dashboard
+
+Monitor your agents in real time:
+
+```bash
+npx claude-octopus dashboard
+```
+
+Opens a local web dashboard at `http://localhost:3456` with:
+
+- **Live stats** — total runs, invocations, cost, turns, errors
+- **Recent activity** — agent cards for the latest run
+- **Run table** — all runs with cost, duration, and status
+- **Auto-refresh** — SSE connection pushes updates as agents run
+
+```bash
+# Custom port
+npx claude-octopus dashboard --port 8080
+```
+
+The dashboard reads the same timeline index used by the `_timeline` and `_report` tools. No additional configuration needed.
+
 ## Tools
 
 Each non-factory instance exposes:
 
-| Tool           | Purpose                                                 |
-| -------------- | ------------------------------------------------------- |
-| `<name>`       | Send a task to the agent, get a response + `session_id` |
-| `<name>_reply` | Continue a previous conversation by `session_id`        |
+| Tool | Purpose |
+|------|---------|
+| `<name>` | Send a task to the agent, get a response + `session_id` + `run_id` |
+| `<name>_reply` | Continue a previous conversation by `session_id` |
+| `<name>_timeline` | Query the cross-agent workflow timeline |
+| `<name>_transcript` | Retrieve full session transcript from Claude Code's storage |
+| `<name>_report` | Generate a self-contained HTML report for a run or all runs |
+
+### Query and reply parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `prompt` | The task or question (required) |
+| `run_id` | Workflow run ID — groups related agent calls into one timeline. Auto-generated if omitted; returned in every response for propagation. |
+| `cwd` | Working directory override |
+| `model` | Model override (`sonnet`, `opus`, `haiku`, or full ID) |
+| `tools` | Restrict available tools (intersects with server restriction) |
+| `disallowedTools` | Block additional tools (unions with server blacklist) |
+| `additionalDirs` | Extra directories the agent can access |
+| `plugins` | Additional plugin paths to load |
+| `effort` | Thinking effort (`low`, `medium`, `high`, `max`) |
+| `permissionMode` | Permission mode (can only tighten, never loosen) |
+| `maxTurns` | Max conversation turns |
+| `maxBudgetUsd` | Max spend in USD |
+| `systemPrompt` | Additional prompt (appended to server default) |
+
+## Timeline
+
+Every agent invocation is recorded in a lightweight JSONL index at `~/.claude-octopus/timelines/timeline.jsonl`. This solves the multi-agent correlation problem: when several agents participate in a workflow, the timeline tracks which sessions belong to the same run, in what order they executed, and what role each played.
+
+Full session transcripts stay in Claude Code's own storage (`~/.claude/projects/`). The timeline is just the table of contents — ~200 bytes per entry — that cross-references via `session_id`.
+
+```mermaid
+graph TB
+    subgraph "Timeline Index (~200 bytes/entry)"
+        TL["~/.claude-octopus/timelines/timeline.jsonl"]
+    end
+
+    subgraph "Claude Code Session Storage (full transcripts)"
+        S1["~/.claude/projects/.../ses-aaa.jsonl"]
+        S2["~/.claude/projects/.../ses-bbb.jsonl"]
+        S3["~/.claude/projects/.../ses-ccc.jsonl"]
+    end
+
+    TL -->|"session_id cross-ref"| S1
+    TL -->|"session_id cross-ref"| S2
+    TL -->|"session_id cross-ref"| S3
+```
 
-Per-invocation parameters (override server defaults):
+### How it works
 
-| Parameter         | Description                                     |
-| ----------------- | ----------------------------------------------- |
-| `prompt`          | The task or question (required)                 |
-| `cwd`             | Working directory override                      |
-| `model`           | Model override                                  |
-| `tools`           | Restrict available tools (intersects with server restriction) |
-| `disallowedTools` | Block additional tools (unions with server blacklist) |
-| `additionalDirs`  | Extra directories the agent can access           |
-| `plugins`         | Additional plugin paths to load                  |
-| `effort`          | Thinking effort (`low`, `medium`, `high`, `max`) |
-| `permissionMode`  | Permission mode (can only tighten, never loosen) |
-| `maxTurns`        | Max conversation turns                          |
-| `maxBudgetUsd`    | Max spend in USD                                |
-| `systemPrompt`    | Additional prompt (appended to server default)  |
+1. Every `<name>` and `<name>_reply` call appends one line to the timeline
+2. If you pass `run_id`, all agents sharing the same `run_id` are grouped into one run
+3. If you omit `run_id`, one is auto-generated and returned in the response — pass it to subsequent agents to keep them grouped
+
+### Querying the timeline
+
+```
+# List all runs
+<name>_timeline({})
+
+# Show one run's agent sequence
+<name>_timeline({ run_id: "abc-123" })
+
+# Look up a specific session
+<name>_timeline({ session_id: "ses-xyz" })
+
+# Retrieve full transcript (separate tool)
+<name>_transcript({ session_id: "ses-xyz" })
+```
+
+### Multi-agent workflow example
+
+```
+Host:  researcher({ prompt: "Research X", run_id: "pub-001" })
+       → { run_id: "pub-001", session_id: "ses-aaa", result: "..." }
+
+Host:  architect({ prompt: "Structure based on...", run_id: "pub-001" })
+       → { run_id: "pub-001", session_id: "ses-bbb", result: "..." }
+
+Host:  verifier({ prompt: "Check this plan", run_id: "pub-001" })
+       → { run_id: "pub-001", session_id: "ses-ccc", result: "..." }
+
+Later: researcher_timeline({ run_id: "pub-001" })
+       → [
+           { agent: "researcher", session_id: "ses-aaa", cost: 0.05, turns: 4 },
+           { agent: "architect",  session_id: "ses-bbb", cost: 0.08, turns: 6 },
+           { agent: "verifier",   session_id: "ses-ccc", cost: 0.03, turns: 3 },
+         ]
+
+Later: researcher_transcript({ session_id: "ses-aaa" })
+       → full conversation transcript from Claude Code's storage
+```
+
+## HTML Reports
+
+Generate self-contained HTML reports with agent sequence visualization, cost breakdown, and collapsible transcripts. Dark theme, no external dependencies — one file, open in any browser.
+
+### Via MCP tool
+
+```
+<name>_report({})                        # index of all runs
+<name>_report({ run_id: "pub-001" })     # detailed report for one run
+```
+
+### Via CLI
+
+```bash
+# Index of all runs
+npx claude-octopus report --out index.html
+
+# Detailed report for one run
+npx claude-octopus report pub-001 --out report.html
+open report.html
+
+# Without transcripts (faster, smaller file)
+npx claude-octopus report pub-001 --no-transcripts --out report.html
+
+# To stdout (pipe-friendly)
+npx claude-octopus report pub-001 > report.html
+```
+
+### What's in the report
+
+- **Run summary** — agent count, total cost, duration, total turns
+- **Timeline bar** — numbered dots for each agent (green = success, red = error)
+- **Agent cards** — timing, cost, turns, session ID, prompt excerpt
+- **Collapsible transcripts** — full tool calls, reasoning, and results per agent
 
 ## Configuration
 
@@ -152,50 +373,56 @@ All configuration is via environment variables in `.mcp.json`. Every env var is
 
 ### Identity
 
-| Env Var               | Description                                    | Default          |
-| --------------------- | ---------------------------------------------- | ---------------- |
-| `CLAUDE_TOOL_NAME`    | Tool name prefix (`<name>` and `<name>_reply`) | `claude_code`    |
-| `CLAUDE_DESCRIPTION`  | Tool description shown to the host AI          | generic          |
-| `CLAUDE_SERVER_NAME`  | MCP server name in protocol handshake          | `claude-octopus` |
-| `CLAUDE_FACTORY_ONLY` | Only expose the factory wizard tool            | `false`          |
+| Env Var | Description | Default |
+|---------|-------------|---------|
+| `CLAUDE_TOOL_NAME` | Tool name prefix (generates `<name>`, `<name>_reply`, `<name>_timeline`, `<name>_transcript`, `<name>_report`) | `claude_code` |
+| `CLAUDE_DESCRIPTION` | Tool description shown to the host AI | generic |
+| `CLAUDE_SERVER_NAME` | MCP server name in protocol handshake | `claude-octopus` |
+| `CLAUDE_FACTORY_ONLY` | Only expose the factory wizard tool | `false` |
 
 ### Agent
 
-| Env Var                   | Description                                           | Default         |
-| ------------------------- | ----------------------------------------------------- | --------------- |
-| `CLAUDE_MODEL`            | Model (`sonnet`, `opus`, `haiku`, or full ID)         | SDK default     |
-| `CLAUDE_CWD`              | Working directory                                     | `process.cwd()` |
-| `CLAUDE_PERMISSION_MODE`  | `default`, `acceptEdits`, `bypassPermissions`, `plan` | `default`       |
-| `CLAUDE_ALLOWED_TOOLS`    | Comma-separated tool restriction (available tools)    | all             |
-| `CLAUDE_DISALLOWED_TOOLS` | Comma-separated tool blacklist                        | none            |
-| `CLAUDE_MAX_TURNS`        | Max conversation turns                                | unlimited       |
-| `CLAUDE_MAX_BUDGET_USD`   | Max spend per invocation                              | unlimited       |
-| `CLAUDE_EFFORT`           | `low`, `medium`, `high`, `max`                        | SDK default     |
+| Env Var | Description | Default |
+|---------|-------------|---------|
+| `CLAUDE_MODEL` | Model (`sonnet`, `opus`, `haiku`, or full ID) | SDK default |
+| `CLAUDE_CWD` | Working directory | `process.cwd()` |
+| `CLAUDE_PERMISSION_MODE` | `default`, `acceptEdits`, `bypassPermissions`, `plan` | `default` |
+| `CLAUDE_ALLOWED_TOOLS` | Comma-separated tool restriction (available tools) | all |
+| `CLAUDE_DISALLOWED_TOOLS` | Comma-separated tool blacklist | none |
+| `CLAUDE_MAX_TURNS` | Max conversation turns | unlimited |
+| `CLAUDE_MAX_BUDGET_USD` | Max spend per invocation | unlimited |
+| `CLAUDE_EFFORT` | `low`, `medium`, `high`, `max` | SDK default |
 
 ### Prompts
 
-| Env Var                | Description                                            |
-| ---------------------- | ------------------------------------------------------ |
-| `CLAUDE_SYSTEM_PROMPT` | Replaces the default Claude Code system prompt         |
+| Env Var | Description |
+|---------|-------------|
+| `CLAUDE_SYSTEM_PROMPT` | Replaces the default Claude Code system prompt |
 | `CLAUDE_APPEND_PROMPT` | Appended to the default prompt (usually what you want) |
 
 ### Advanced
 
-| Env Var                  | Description                                              |
-| ------------------------ | -------------------------------------------------------- |
-| `CLAUDE_ADDITIONAL_DIRS` | Extra directories to grant access (comma-separated)      |
-| `CLAUDE_PLUGINS`         | Local plugin paths (comma-separated)                     |
-| `CLAUDE_MCP_SERVERS`     | MCP servers for the inner agent (JSON)                   |
+| Env Var | Description |
+|---------|-------------|
+| `CLAUDE_ADDITIONAL_DIRS` | Extra directories to grant access (comma-separated) |
+| `CLAUDE_PLUGINS` | Local plugin paths (comma-separated) |
+| `CLAUDE_MCP_SERVERS` | MCP servers for the inner agent (JSON) |
 | `CLAUDE_PERSIST_SESSION` | `true`/`false` — enable session resume (default: `true`) |
-| `CLAUDE_SETTING_SOURCES` | Settings to load: `user`, `project`, `local`             |
-| `CLAUDE_SETTINGS`        | Path to settings JSON or inline JSON                     |
-| `CLAUDE_BETAS`           | Beta features (comma-separated)                          |
+| `CLAUDE_SETTING_SOURCES` | Settings to load: `user`, `project`, `local` |
+| `CLAUDE_SETTINGS` | Path to settings JSON or inline JSON |
+| `CLAUDE_BETAS` | Beta features (comma-separated) |
+
+### Timeline
+
+| Env Var | Description | Default |
+|---------|-------------|---------|
+| `CLAUDE_TIMELINE_DIR` | Directory for the cross-agent timeline index | `~/.claude-octopus/timelines` |
 
 ### Authentication
 
-| Env Var                   | Description                            | Default               |
-| ------------------------- | -------------------------------------- | --------------------- |
-| `ANTHROPIC_API_KEY`       | Anthropic API key for this agent       | inherited from parent |
+| Env Var | Description | Default |
+|---------|-------------|---------|
+| `ANTHROPIC_API_KEY` | Anthropic API key for this agent | inherited from parent |
 | `CLAUDE_CODE_OAUTH_TOKEN` | Claude Code OAuth token for this agent | inherited from parent |
 
 Leave both unset to inherit auth from the parent process. Set one per agent to use a different account or billing source.
@@ -204,50 +431,56 @@ Lists accept JSON arrays when values contain commas: `["path,with,comma", "/norm
 
 ## Security
 
-- **Permission mode defaults to ****`default`** — tool executions prompt for approval unless you explicitly set `bypassPermissions`.
+- **Permission mode defaults to `default`** — tool executions prompt for approval unless you explicitly set `bypassPermissions`.
 - **`cwd` overrides preserve agent knowledge** — when the host overrides `cwd`, the agent's configured base directory is automatically added to `additionalDirectories` so it retains access to its own context.
 - **Tool restrictions narrow, never widen** — per-invocation `tools` intersects with the server restriction (can only remove tools, not add). `disallowedTools` unions (can only block more).
-- **`_reply`**** tool respects persistence** — not registered when `CLAUDE_PERSIST_SESSION=false`.
+- **`_reply` and `_transcript` tools respect persistence** — not registered when `CLAUDE_PERSIST_SESSION=false`.
+- **Timeline writes are best-effort** — a failed timeline append never blocks or fails the primary query.
 
 ## Architecture
 
-```
-┌─────────────────────────────────┐
-│  MCP Client                     │
-│  (Claude Desktop, Cursor, etc.) │
-│                                 │
-│  Sees: code_reviewer,           │
-│        test_writer, quick_qa    │
-└──────────┬──────────────────────┘
-           │ JSON-RPC / stdio
-┌──────────▼──────────────────────┐
-│  Claude Octopus (per instance)  │
-│                                 │
-│  Env: CLAUDE_MODEL=opus         │
-│       CLAUDE_ALLOWED_TOOLS=...  │
-│       CLAUDE_APPEND_PROMPT=...  │
-│                                 │
-│  Calls: Agent SDK query()       │
-└──────────┬──────────────────────┘
-           │ in-process
-┌──────────▼──────────────────────┐
-│  Claude Agent SDK               │
-│  Runs autonomously: reads files,│
-│  writes code, runs commands     │
-│  Returns result + session_id    │
-└─────────────────────────────────┘
+```mermaid
+graph TB
+    subgraph "MCP Client (Claude Desktop, Cursor, etc.)"
+        C["Sees: code_reviewer, test_writer, quick_qa"]
+    end
+
+    C -->|"JSON-RPC / stdio"| O1
+    C -->|"JSON-RPC / stdio"| O2
+    C -->|"JSON-RPC / stdio"| O3
+
+    subgraph "Claude Octopus Instances"
+        O1["code-reviewer<br/>model=opus, tools=Read,Grep,Glob"]
+        O2["test-writer<br/>model=sonnet"]
+        O3["quick-qa<br/>model=haiku, budget=$0.02"]
+    end
+
+    O1 -->|"Agent SDK query()"| SDK["Claude Agent SDK"]
+    O2 -->|"Agent SDK query()"| SDK
+    O3 -->|"Agent SDK query()"| SDK
+
+    O1 -->|"append"| TL["Timeline Index<br/>~/.claude-octopus/timelines/"]
+    O2 -->|"append"| TL
+    O3 -->|"append"| TL
+
+    SDK -->|"persist"| SS["Session Storage<br/>~/.claude/projects/"]
+    TL -.->|"cross-ref"| SS
 ```
 
 ## How It Compares
 
-| Feature             | ``         | [claude-code-mcp](https://github.com/steipete/claude-code-mcp) | **Claude Octopus** |
-| ------------------- | ------------ | -------------------------------------------------------------- | ------------------ |
-| Approach            | Built-in     | CLI wrapping                                                   | Agent SDK          |
-| Exposes             | 16 raw tools | 1 prompt tool                                                  | 1 prompt + reply   |
-| Multi-instance      | No           | No                                                             | Yes                |
-| Per-instance config | No           | No                                                             | Yes (18 env vars)  |
-| Factory wizard      | No           | No                                                             | Yes                |
-| Session continuity  | No           | No                                                             | Yes                |
+| Feature | Built-in `claude` | [claude-code-mcp](https://github.com/steipete/claude-code-mcp) | **Claude Octopus** |
+|---------|-------------------|----------------------------------------------------------------|--------------------|
+| Approach | Built-in | CLI wrapping | Agent SDK |
+| Tools per instance | 16 raw tools | 1 prompt tool | 5 (prompt, reply, timeline, transcript, report) |
+| Multi-instance | No | No | Yes |
+| Per-instance config | No | No | Yes (20 env vars) |
+| Init wizard | No | No | Yes (`init` + 5 templates) |
+| Factory wizard | No | No | Yes |
+| Session continuity | No | No | Yes |
+| Cross-agent timeline | No | No | Yes |
+| Web dashboard | No | No | Yes (live, SSE) |
+| HTML reports | No | No | Yes |
 
 ## Development
 

package/dist/cli-prompts.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CLI prompt helpers and MCP client detection — extracted from init.ts.
+ */
+import { createInterface } from "node:readline/promises";
+import type { AgentConfig } from "./templates.js";
+export interface McpClient {
+    name: string;
+    configPath: string;
+}
+export interface McpConfig {
+    mcpServers?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export declare function detectMcpClients(): Promise<McpClient[]>;
+export declare function readMcpConfig(path: string): Promise<McpConfig>;
+export declare function writeMcpConfig(path: string, config: McpConfig): Promise<void>;
+export declare function choose(rl: ReturnType<typeof createInterface>, prompt: string, options: {
+    label: string;
+    value: string;
+}[]): Promise<string>;
+export declare function confirm(rl: ReturnType<typeof createInterface>, prompt: string): Promise<boolean>;
+export declare function buildCustomAgent(rl: ReturnType<typeof createInterface>): Promise<AgentConfig>;