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

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