io.github.vorluno/batuta-mcp

Official

by vorluno · TypeScript

Split a task into plans with disjoint file boundaries; scaffold a git worktree per plan.

Decompose tasks into plans and scaffold isolated git worktrees per plan.

Topics

ai-agentsbunclaudeclaude-codedeveloper-toolsgit-worktreemcpmcp-servermodel-context-protocolmulti-agentparalleltypescript

README.md4 KBView on GitHub

batuta-mcp

Split a task into plans with disjoint file boundaries, then scaffold a git worktree per plan — so parallel agents never step on each other.

A stateless MCP server that turns a brain dump into conflict-free parallel work.

</div>

Why

Running several coding agents in parallel is fast — until two of them edit the same file and silently clobber each other's work. The fix isn't live coordination; it's separation: give each agent a set of files that don't overlap, and the conflict can't happen by design.

batuta-mcp is the brain that does that split. You hand it a brain dump; it returns plans with disjoint file boundaries, and scaffolds an isolated git worktree for each one.

How it works

It's a stateless MCP server (stdio). No database, no daemon, no web UI — just three tools that compose:

Decompose a brain dump into 2–5 plans whose fileBoundaries don't overlap (auto-corrects once if they do).
Check that the boundaries are truly disjoint.
Scaffold a git worktree per plan, returning a ready-to-paste prompt for each — open them in separate terminals/tabs and let one agent work each, conflict-free.

The "muscle" (running the agents, the terminals) stays in your editor; batuta-mcp is just the planning brain.

Features

🧠 Disjoint decomposition — plans are generated so no file appears in two plans.
♻️ Auto-correction — if the model returns overlapping boundaries, it retries once to separate them.
🌳 Worktree scaffolding — one isolated git worktree per plan, with a ready-to-paste prompt.
🔒 Safe by design — pre-flight checks (valid git repo, no overlaps, no path traversal) before touching disk; dryRun previews without writing.
🪶 Stateless — nothing persisted; uses your logged-in claude CLI (no API key needed).

Requirements

Bun 1.3+
git 2.x (for scaffold_worktrees)
The claude CLI, logged in (for decompose_into_plans)
Claude Code or any MCP client

Installation

bash

git clone https://github.com/vorluno/batuta-mcp.git
cd batuta-mcp
bun install

claude mcp add batuta -- bun run /absolute/path/to/batuta-mcp/src/index.ts

Configuration

Any MCP client works. The mcpServers entry:

json

{
  "mcpServers": {
    "batuta": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/batuta-mcp/src/index.ts"]
    }
  }
}

For Claude Code, claude mcp add (above) writes this for you. For Warp or Cursor, paste the snippet into their MCP settings.

Tools

Tool	Description
`decompose_into_plans`	`{ brainDump, projectHint?, repoPath? }` → `{ plans, overlapsResolved, attempts }`. Splits the work into plans with disjoint boundaries (auto-corrects overlaps once).
`check_boundary_overlaps`	`{ plans }` → `{ overlaps, ok }`. Pure check: do any plans share files?
`scaffold_worktrees`	`{ repoPath, plans, dryRun? }` → `{ results }`. Pre-flight, then `git worktree add` per plan + a ready-to-paste prompt.

Typical flow

decompose_into_plans → plans with disjoint boundaries.
check_boundary_overlaps → confirm ok: true (or adjust).
scaffold_worktrees → creates the worktrees; open each in its own terminal/tab and paste its suggestedPrompt.

Development

bash

bun test          # full suite
bunx tsc --noEmit # type-check

Built test-first across 10 TDD tasks with per-task and whole-branch review.

License

Built by Vorluno — a software studio from Panamá 🇵🇦

Part of the mcp-s family of MCP servers. Looking for live coordination between sessions instead of separation? See agora.

</div>

Install

claude_desktop_config.json

{
  "mcpServers": {
    "batuta-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@vorluno/batuta-mcp@0.1.0"
      ]
    }
  }
}