overstory Integration

Description

Integrates overstory's Claude Code agent swarm system with the nanobot orchestrator. Provides agent lifecycle management, an inter-agent SQLite mail bridge, and git worktree coordination for parallel agent workstreams.

Architecture

┌──────────────┐       ┌───────────────────┐
│   nanobot     │──────▶│ overstory_wrapper │──▶ overstory CLI (tmux sessions)
│  orchestrator │       └───────────────────┘
│               │       ┌───────────────────┐
│               │──────▶│ agent_lifecycle    │──▶ SQLite (agent_lifecycle.db)
│               │       └───────────────────┘
│               │       ┌───────────────────┐
│               │──────▶│   mail_bridge     │──▶ SQLite (.overstory/mail.db)
└──────────────┘       └───────────────────┘

• overstory_wrapper.py — Thin wrapper around the overstory CLI. Spawns agents via tmux, manages worktrees, installs hooks.
• agent_lifecycle.py — Tracks agent state (spawned → running → completed/failed/terminated) in a local SQLite database. Provides async monitoring and cleanup.
• mail_bridge.py — Thread-safe message bridge using overstory's native SQLite mail format. Supports direct messages, broadcasts, and threaded conversations.

Requirements

• Python 3.9+
• overstory CLI installed and on PATH (or set OVERSTORY_BIN)
• git (for worktree management)
• tmux (overstory uses tmux for agent sessions)
• No external Python dependencies (stdlib only)

Environment Variables

| Variable | Default | Description | |---|---|---| | OVERSTORY_BIN | overstory | Path to overstory binary | | OVERSTORY_WORKSPACE | current directory | Workspace root for overstory operations |

Commands

Initialize workspace

python3 scripts/overstory_wrapper.py init --workspace /path/to/project

Spawn an agent

python3 scripts/overstory_wrapper.py sling \
  --task-id TASK-42 \
  --capability code \
  --name builder-alice \
  --description "Implement auth module" \
  --worktree

Check status

python3 scripts/overstory_wrapper.py status
python3 scripts/overstory_wrapper.py status --agent builder-alice --verbose

Inspect agent transcript

python3 scripts/overstory_wrapper.py inspect --agent builder-alice --lines 100

Kill an agent

python3 scripts/overstory_wrapper.py kill --agent builder-alice

Worktree management

python3 scripts/overstory_wrapper.py list-worktrees
python3 scripts/overstory_wrapper.py cleanup-worktree --agent builder-alice

Agent lifecycle

python3 scripts/agent_lifecycle.py spawn --task "Fix login bug" --capability code --name bug-fixer
python3 scripts/agent_lifecycle.py list-active --json
python3 scripts/agent_lifecycle.py wait --agent bug-fixer --timeout 1800
python3 scripts/agent_lifecycle.py cleanup --max-age 24

Mail bridge

python3 scripts/mail_bridge.py send --from orchestrator --to builder-alice --subject "Priority change" --body "Switch to auth module"
python3 scripts/mail_bridge.py read --agent builder-alice --unread
python3 scripts/mail_bridge.py broadcast --from orchestrator --channel @all --message "Stand down"
python3 scripts/mail_bridge.py create-thread --agents orchestrator,builder-alice --subject "Auth design"
python3 scripts/mail_bridge.py reply --thread THREAD-ID --from builder-alice --body "Done with phase 1"

Usage as Python Module

from overstory_wrapper import OverstoryWrapper
from agent_lifecycle import AgentLifecycle
from mail_bridge import MailBridge

wrapper = OverstoryWrapper("/path/to/workspace")
wrapper.init()

lifecycle = AgentLifecycle()
agent = lifecycle.spawn_agent(task="Build API", capability="code", name="api-builder")

bridge = MailBridge("/path/to/workspace")
bridge.send("orchestrator", "api-builder", "Context", "Here are the specs...")

Database Schemas

agent_lifecycle.db (~/.nanobot/agent_lifecycle.db)

| Column | Type | Description | |---|---|---| | id | INTEGER PRIMARY KEY | Auto-increment | | agent_name | TEXT UNIQUE | Agent identifier | | capability | TEXT | Agent capability (code, research, etc.) | | status | TEXT | spawned/running/completed/failed/terminated | | task | TEXT | Task description | | result | TEXT | Final output (nullable) | | start_time | REAL | Unix timestamp | | end_time | REAL | Unix timestamp (nullable) | | timeout | INTEGER | Max runtime in seconds |

mail.db (.overstory/mail.db)

| Column | Type | Description | |---|---|---| | id | INTEGER PRIMARY KEY | Auto-increment | | thread_id | TEXT | Thread identifier (nullable) | | from_agent | TEXT | Sender agent name | | to_agent | TEXT | Recipient agent name | | subject | TEXT | Message subject | | body | TEXT | Message body | | priority | TEXT | normal/high/urgent | | read | INTEGER | 0=unread, 1=read | | created_at | REAL | Unix timestamp |