This project provides a project-agnostic swarm system designed to orchestrate multiple Claude Code agents, transforming a single session into a coordinated multi-agent team. It addresses the complexity of advanced AI-driven development workflows by enabling agents to collaborate on tasks, decompose objectives, and merge their work, offering a powerful tool for users seeking to scale their AI development capabilities.

How It Works

Overstory employs a two-layer architecture featuring a persistent coordinator agent that manages task decomposition and dispatch. Worker agents are spawned in isolated git worktrees using tmux, communicating via a custom SQLite mail system with a typed protocol and broadcast messaging. A mechanical watchdog daemon monitors agent health. This approach leverages git worktrees for isolation, a structured SQLite mail system for reliable communication, and tiered health monitoring to manage complex agent swarms robustly.

Quick Start & Requirements

• Primary install: Clone the repository, install dependencies with bun install, and link the CLI globally using bun link.
• Prerequisites: Bun (v1.0+), Claude Code, git, and tmux are required.
• Setup: Initialize Overstory in a project directory with overstory init and install hooks via overstory hooks install.
• Running: Start the coordinator with overstory coordinator start or spawn individual worker agents using overstory sling --capability <type>.
• Documentation: Refer to STEELMAN.md for risk analysis and the Agentic Engineering Book (web version) for deeper insights.

Highlighted Details

• Custom SQLite mail system with typed protocols and broadcast messaging for structured agent coordination.
• FIFO merge queue with a 4-tier conflict resolution strategy.
• Tiered health monitoring includes a mechanical daemon, AI-assisted failure triage, and a Tier 2 monitor agent.
• PreToolUse hooks mechanically enforce file modification restrictions and prevent dangerous git operations for agents.
• Token instrumentation extracts session metrics from Claude Code transcript JSONL files.
• A live TUI dashboard (overstory dashboard) provides real-time monitoring of the agent fleet.

Maintenance & Community

No specific details regarding notable contributors, sponsorships, or community channels (e.g., Discord, Slack) are provided in the README.

Licensing & Compatibility

The project is released under the MIT license, which is generally permissive for commercial use and integration into closed-source projects.

Limitations & Caveats

Agent swarms are explicitly warned against as a universal solution. Users must understand the inherent risks of multi-agent orchestration, including compounding error rates, cost amplification, debugging complexity, and merge conflicts, which are presented as the "normal case." A full risk analysis is available in STEELMAN.md.