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 |