gitbutler-multi-agent

Coordinate multiple AI agents working concurrently in the same workspace using GitButler's virtual branch model. Use for parallel development, sequential handoffs, and commit transfer patterns without checkout overhead.

⭐4stars🔀0forks📁View on GitHub🕐Updated Dec 31, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill enables seamless multi-agent coordination using GitButler's virtual branch model, allowing multiple AI agents to work concurrently in a single workspace without the overhead of branch switching or worktree management. It optimizes parallel development, facilitates smooth agent handoffs, and ensures immediate conflict detection by maintaining a shared working tree for all active agents.

Use Cases

  • Parallel Feature Development: Enable multiple AI agents to work on independent features (e.g., Auth and API) simultaneously within the same directory without merge conflicts.
  • Sequential Agent Handoffs: Facilitate a structured workflow where Agent A completes an initial implementation and Agent B takes over for refinement or testing without manual context transfer.
  • Cross-Agent Commit Transfer: Use the 'rub' power tool to instantly move specific commits or file changes between different agent-led branches to reorganize work post-hoc.
  • Real-time Conflict Detection: Identify overlapping code edits across multiple agent sessions early in the development cycle by utilizing GitButler's shared workspace architecture.
  • AI Lifecycle Management: Integrate with Claude Code and MCP servers to automate commit management and status broadcasting across complex multi-agent sessions.
namemulti-agent
version2.0.0
descriptionThis skill should be used when coordinating multiple agents, parallel development, agent handoffs, or when multi-agent, concurrent agents, or parallel agents are mentioned.

GitButler Multi-Agent Coordination

Multiple agents → virtual branches → parallel execution → zero coordination overhead.

  • Multiple agents working on different features simultaneously
  • Sequential agent handoffs (Agent A → Agent B)
  • Commit ownership transfer between agents
  • Parallel execution with early conflict detection
  • Post-hoc reorganization of multi-agent work

NOT for: single-agent workflows (use standard GitButler), projects needing PR automation (Graphite better)

Traditional Git Problem:

  • Agents must work in separate worktrees (directory coordination)
  • Constant branch switching (context loss, file churn)
  • Late conflict detection (only at merge time)

GitButler Solution:

  • Multiple branches stay applied simultaneously
  • Single shared workspace, zero checkout operations
  • Immediate conflict detection (shared working tree)
  • Each agent manipulates their own lane

Pattern 1: Parallel Feature Development

# Agent 1
but branch new agent-1-auth
echo "auth code" > auth.ts
but rub auth.ts agent-1-auth
but commit agent-1-auth -m "feat: add authentication"

# Agent 2 (simultaneously, same workspace!)
but branch new agent-2-api
echo "api code" > api.ts
but rub api.ts agent-2-api
but commit agent-2-api -m "feat: add API endpoints"

# Result: Two independent features, zero conflicts

Pattern 2: Sequential Handoff

# Agent A: Initial implementation
but branch new initial-impl
# ... code ...
but commit initial-impl -m "feat: initial implementation"

# Agent B: Takes ownership and refines
but rub <agent-a-commit> refinement-branch
# ... improve code ...
but commit refinement-branch -m "refactor: optimize implementation"

Pattern 3: Cross-Agent Commit Transfer

# Instant ownership transfer
but rub <commit-sha> agent-b-branch  # Agent A → Agent B
but rub <commit-sha> agent-a-branch  # Agent B → Agent A

Branch Naming Convention

<agent-name>-<task-type>-<brief-description>

Examples:
- claude-feat-user-auth
- droid-fix-api-timeout
- codex-refactor-database-layer

Makes ownership immediately visible in but status and but log.

AI Integration Methods

1. Agents Tab (Claude Code)

  • GUI-based launcher tied to branches
  • Each virtual branch = independent session
  • Automatic commit management per session
  • Parallel agent execution with branch isolation

2. Lifecycle Hooks

{
  "hooks": {
    "PreToolUse": [{"matcher": "Edit|MultiEdit|Write", "hooks": [{"type": "command", "command": "but claude pre-tool"}]}],
    "PostToolUse": [{"matcher": "Edit|MultiEdit|Write", "hooks": [{"type": "command", "command": "but claude post-tool"}]}],
    "Stop": [{"matcher": "", "hooks": [{"type": "command", "command": "but claude stop"}]}]
  }
}

3. MCP Server

but mcp  # Enables programmatic agent integration

Key Instruction for Agents:

"Never use the git commit command after a task is finished"

Let GitButler manage commits via hooks or MCP.

Coordination Protocols

Status Broadcasting:

# File-based coordination
but status > /tmp/agent-$(whoami)-status.txt

# Or use Linear/GitHub comments
# "[AGENT-A] Completed auth module, committed to claude-auth-feature"

Snapshot Cadence:

# Before risky operations
but snapshot --message "Before merging conflicting branches"

# If it breaks
but undo

Concurrent Safety:

  1. Snapshot before risky operations
  2. Broadcast status regularly to other agents
  3. Respect 🔒 locks — files assigned to other branches
  4. Use but --json for programmatic state inspection

The but rub Power Tool

Single command handles four critical multi-agent operations:

Operation Example Use Case
Assign but rub m6 claude-branch Organize files to branches post-hoc
Move but rub abc1234 other-branch Transfer work between agents
Squash but rub newer older Clean up history
Amend but rub file commit Fix existing commits

vs Other Workflows

Aspect Graphite Git Worktrees GitButler
Multi-agent concurrency Serial N directories Parallel ✓
Post-hoc organization Difficult Difficult but rub ✓
PR Submission gt submit ✓ Manual GUI only
Physical layout 1 directory N × repo 1 directory ✓
Context switching gt checkout cd None ✓
Conflict detection Late (merge) Late (merge) Early ✓
Disk usage 1 × repo N × repo 1 × repo ✓

ALWAYS:

  • Use unique branch names per agent: <agent>-<type>-<desc>
  • Assign files immediately after creating: but rub <id> <branch>
  • Snapshot before coordinated operations
  • Broadcast status to other agents when completing work
  • Check for 🔒 locked files before modifying

NEVER:

  • Use git commit — breaks GitButler state
  • Let files sit in "Unassigned Changes" — assign immediately
  • Modify files locked to other branches
  • Mix git and but commands during active agent sessions

Common Issues

Symptom Cause Solution
Agent commit "orphaned" Used git commit Find with git reflog, recover
Files in wrong branch Forgot assignment but rub <id> <correct-branch>
Conflicting edits Overlapping files Reassign hunks to different branches
Lost agent work Branch deleted but undo or restore from oplog

Recovery

# Find orphaned commits
git reflog

# Recover agent work
but oplog
but undo

# Extract from snapshot
git show <snapshot>:index/path/to/file.txt

Current Limitations

  • No PR submission CLI — use gh pr create after organizing
  • Overlapping file edits — adjacent lines can only go to one branch
  • No stack navigation CLI — no gt up/gt down equivalent

Recommendation: Use for exploratory multi-agent work. For production automation requiring PR submission, consider Graphite until CLI matures.