Overstory: Multi-Agent AI Coding with Git Worktrees and SQLite Coordination

Hook

Most AI coding tools give you one assistant. Overstory gives you a team—but like any team, they can work in parallel brilliantly or compound each other's mistakes exponentially.

Context

AI coding assistants have evolved from autocomplete suggestions to full-featured agents that can implement features, write tests, and refactor code. Tools like Cursor, Aider, and Claude Code have made single-agent workflows remarkably effective. But a single agent is fundamentally bottlenecked: it works serially, tackling one file or feature at a time.

The promise of multi-agent orchestration is parallelism—imagine one agent writing tests while another updates documentation and a third refactors legacy code. The challenge is coordination. Multiple agents modifying the same codebase create merge conflicts, duplicate work, and compounding errors. Traditional agent frameworks like AutoGPT use message queues or API calls for coordination, but these approaches lack the transactional guarantees and merge semantics that code requires. Overstory takes a different approach: it treats git itself as the coordination primitive, using worktrees for isolation and SQLite as a persistent message bus between agents.

Technical Insight

Overstory's architecture centers on three core decisions: git worktrees as process boundaries, SQLite-based message passing, and pluggable runtime adapters. Each choice addresses a specific coordination problem.

Git worktrees provide filesystem-level isolation. When Overstory spawns an agent, it creates a dedicated worktree (essentially a separate working directory pointing to a unique branch). Each agent modifies code independently without interfering with others. The framework coordinates through a parent orchestrator that assigns tasks, monitors progress, and eventually merges results. This isn't just convenient—it's a fundamental architectural constraint that prevents agents from clobbering each other's work mid-execution.

The message-passing system uses SQLite rather than traditional queues or RPC. Each agent reads and writes to a shared SQLite database that acts like an asynchronous mailbox. This persistence matters: if an agent crashes or times out, its partial work and message history remain queryable. The orchestrator can inspect what failed, replay messages, or reassign tasks. Here's a simplified view of how runtime adapters integrate:

export interface AgentRuntime {
  name: string;
  spawn(config: AgentConfig): Promise<AgentProcess>;
  sendMessage(process: AgentProcess, msg: Message): Promise<void>;
  receiveMessages(process: AgentProcess): AsyncIterator<Message>;
  terminate(process: AgentProcess): Promise<void>;
}

// Example: Aider runtime adapter
class AiderRuntime implements AgentRuntime {
  async spawn(config: AgentConfig): Promise<AgentProcess> {
    const worktree = await createWorktree(config.branch);
    const proc = spawnAider({
      cwd: worktree.path,
      model: config.model,
      editFormat: 'diff'
    });
    return { pid: proc.pid, worktree, stdin: proc.stdin };
  }
  
  async sendMessage(process: AgentProcess, msg: Message): Promise<void> {
    // Aider reads from stdin, expects natural language prompts
    process.stdin.write(`${msg.content}\n`);
    await recordMessageInDB(msg, process.pid);
  }
}

The pluggable runtime abstraction means Overstory supports 11+ different AI coding tools—Claude Code, Aider, Goose, Copilot Workspace, OpenHands, and more—through a standardized interface. Each adapter translates Overstory's coordination messages into the tool's native input format (stdin commands, API calls, file-based prompts).

Conflict resolution happens in tiers. First, git's automatic merge handles non-overlapping changes. When conflicts arise, Overstory can invoke a designated 'referee' agent to resolve them—essentially prompting an LLM with the conflict markers and asking for a resolution. If that fails, the system falls back to manual intervention. This is where the tmux integration becomes critical: Overstory can optionally attach each agent to a tmux pane, allowing developers to monitor agent sessions in real-time and take manual control when automation hits a wall.

The web UI provides a control plane for headless operation. You see agent statuses, message logs, git graph visualizations showing branch/merge activity, and cost tracking per agent. It's designed for oversight, not micromanagement—you launch a multi-agent job, monitor progress through the dashboard, and intervene only when the system surfaces a conflict or timeout.

What makes this architecture compelling is the explicit embrace of git semantics. Rather than trying to abstract away version control or build a custom coordination layer, Overstory leans into git's strengths: branching is cheap, merges are well-understood, and the entire coordination history is versioned. When things go wrong—and the README frankly admits they will—you have git's full tooling to debug, revert, or cherry-pick changes.

Gotcha

Overstory's documentation is refreshingly honest about failure modes, and that honesty reveals real limitations. Multi-agent orchestration doesn't just multiply productivity—it multiplies costs and error rates exponentially. If one agent misunderstands a requirement and implements the wrong feature, other agents might build on that faulty assumption. You're not just paying for multiple API calls; you're paying for compounding mistakes that single-agent workflows would catch earlier.

Merge conflicts aren't edge cases here—they're the expected outcome when multiple agents modify overlapping code. The tiered resolution helps, but invoking an LLM to resolve conflicts adds latency and more API cost. In practice, this means Overstory works best for truly parallelizable work: separate features, independent modules, or broad refactoring where conflicts are unlikely. For tightly coupled changes or small codebases where agents would naturally collide, the coordination overhead exceeds the parallelism benefit.

The project also runs on Bun, not Node.js, which narrows deployment options. You'll need Bun installed, and any deployment pipelines or CI integrations need to accommodate that. The maintainer follows a part-time schedule with 2-week PR review batches and an aggressive 30-day PR closure policy. This isn't necessarily bad—it sets clear expectations—but teams expecting rapid upstream fixes or frequent releases should plan accordingly. Overstory is a power tool for teams who understand git internals and multi-agent tradeoffs, not a plug-and-play productivity boost.

Verdict

Use if: You have genuinely parallelizable work—multi-repo migrations, large-scale test generation, exploratory refactoring across independent modules, or documentation sweeps—where human coordination costs exceed agent coordination costs. Your team is comfortable with git worktrees, merge conflict resolution, and monitoring LLM costs across multiple agents. You value the flexibility to swap between different AI coding tools (Aider for one task, Claude Code for another) through a unified orchestration layer. Skip if: You're working on tightly coupled features where agents would constantly conflict, you have budget constraints that make multi-agent API costs prohibitive, or your team lacks experience debugging complex git merge scenarios. For single-threaded tasks or small codebases, stick with standalone tools like Aider or Cursor—Overstory's coordination overhead won't pay off.