Overstory Integration
WarnAudited by ClawScan on May 10, 2026.
Overview
The skill mostly matches its stated Overstory orchestration purpose, but it can launch/persist agents and force-remove git worktrees without strong containment safeguards.
Install only if you intentionally want an agent-swarm/worktree orchestration layer for a trusted workspace. Before using cleanup or hooks commands, review what will be removed or installed, keep backups of git worktrees, and make sure spawned Overstory/tmux agents are actually stopped when a task is finished.
Findings (6)
Artifact-based informational review of SKILL.md, metadata, install specs, static scan signals, and capability signals. ClawScan does not execute the skill or run runtime probes.
A mistaken or manipulated cleanup request could remove the wrong git worktree or discard local changes.
The cleanup target is derived from a caller-supplied agent_name without path validation, then removed with --force. Absolute paths or ../ segments could escape the intended .overstory/worktrees scope, and --force can discard worktree changes.
wt_path = self.workspace / ".overstory" / "worktrees" / agent_name ... ["git", "worktree", "remove", "--force", str(wt_path)]
Validate agent names as simple identifiers, resolve the path and confirm it remains under .overstory/worktrees, avoid --force by default, and require explicit user approval before deletion.
An agent may appear stopped in the lifecycle database while its underlying session continues to run.
The lifecycle manager can record an agent as terminated without stopping the actual tmux/Overstory process, so state tracking may not contain running agents.
def terminate_agent(self, agent_name: str, graceful: bool = True) -> Dict[str, Any]:
"""Mark agent as terminated. Caller handles actual process kill."""Tie lifecycle termination and timeout handling to the actual Overstory/tmux kill operation, and show users active sessions before and after termination.
Future git commands in the workspace may run hook code installed by the external Overstory CLI.
Git hooks are persistent code-execution mechanisms that can run during later git operations. This appears purpose-aligned, but the artifacts do not show what hooks are installed or how to review/remove them.
def hooks_install(self) -> Dict[str, Any]:
"""Install overstory git hooks."""
return self._cmd("hooks", "install")Only run hooks-install in trusted repositories, review installed hook contents, and provide an uninstall or rollback path.
Any local caller with access to the workspace mail database could impersonate another agent or inject instructions into agent conversations.
The mail bridge accepts arbitrary sender names from the caller and writes them to the shared SQLite mail database without authentication or sender verification.
p_send.add_argument("--from", dest="from_agent", required=True) ... bridge.send(args.from_agent, args.to_agent, args.subject, args.body, args.priority)Treat the mail database as trusted-local only, restrict file permissions, and consider sender validation or signed messages if agents will act on mail contents.
Sensitive task details or agent messages may remain on disk after use and could influence later agent activity.
The skill stores tasks, results, and inter-agent message bodies in persistent local SQLite databases. This is disclosed and purpose-aligned, but those records may contain sensitive project context or instructions reused by agents.
agent_lifecycle.db (~/.nanobot/agent_lifecycle.db) ... task ... result ... mail.db (.overstory/mail.db) ... body
Avoid placing secrets in tasks or messages, protect the database files, and use cleanup/retention policies for old records.
Users must ensure the local overstory/git/tmux tools are the intended trusted versions before using the skill.
The registry metadata does not declare required binaries, while SKILL.md says the skill needs Python, overstory, git, and tmux. The dependency on an externally installed Overstory CLI is disclosed but not install-verified here.
Required binaries (all must exist): none ... No install spec — this is an instruction-only skill.
Declare required binaries in metadata where possible and document trusted installation sources and version expectations for Overstory.