Overstory Integration

Integrates overstory Claude Code agent swarm with nanobot orchestrator. Manages agent lifecycle, SQLite mail bridge, and git worktree coordination.

Security Scan

The skill's code, requirements, and instructions match its stated purpose (agent lifecycle, local SQLite mail bridge, and git worktree coordination); nothing requests unrelated secrets or remote installs, but it will modify local repos and create local DB files so review before running on important data.

Purpose & Capability

Name/description require managing overstory agents, a mail bridge, and worktrees. The package only asks for the overstory CLI, git, and tmux (declared in SKILL.md and reflected in the wrapper), which are proportionate to the described functionality.

Instruction Scope

SKILL.md and the scripts focus on spawning agents, inspecting logs, managing a local SQLite mail DB, and manipulating git worktrees. The code creates ~/.nanobot and .overstory/mail.db (or workspace/.overstory) and runs subprocesses (overstory, git). This is expected, but the skill will modify repository state (worktree remove) and spawn tmux sessions via the overstory CLI, so run with care in important repos or production hosts.

Install Mechanism

Instruction-only skill with bundled Python scripts; no external installer or remote downloads. No install-time network fetches or URL-based archive extraction are present in the provided material.

Credentials

No required secrets or unrelated environment variables. Optional env vars (OVERSTORY_BIN, OVERSTORY_WORKSPACE) are declared and used by the code.

Persistence & Privilege

Skill is not marked always:true and does not modify other skills or global agent configs. It operates on its own local DBs and workspace paths only.

Assessment

This skill appears to do what it claims: it will create and use local SQLite DB files (~/.nanobot/agent_lifecycle.db and workspace/.overstory/mail.db), run the overstory CLI (which spawns tmux sessions), and run git commands that can remove worktrees. Before installing or running: 1) Inspect the full, untruncated source files in the package (the provided mail_bridge snippet was truncated in the listing) to confirm there are no hidden behaviors. 2) Ensure the overstory CLI binary you point to is trusted; this wrapper executes it directly. 3) Back up any important repositories or run in an isolated workspace, since cleanup/remove worktree operations can modify or remove worktrees. 4) If you need to limit risk, run the scripts with non-privileged user accounts or in a container/VM. If you want higher assurance, provide the complete untruncated files so I can re-check for hidden/exfiltration code.

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