gitbutler-multiagent

name	gitbutler-multiagent
description	This skill should be used when coordinating multiple AI agents working concurrently, handling agent handoffs, transferring commits between agents, or when "multi-agent", "concurrent agents", "parallel agents", "agent collaboration", or "parallel execution" are mentioned with GitButler. Provides virtual branch patterns for parallel execution without coordination overhead.
metadata	{"version":"1.0.0","author":"Matt Galligan <[e-mail]>","category":"version-control","related-skills":["gitbutler-guide"]}

GitButler Multi-Agent Coordination

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

<when_to_use>

• 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)

</when_to_use>

Core Advantage

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

Workflow Patterns

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

Pattern 4: Agent Code Review Cycle

Reviewer agent commits fixes separately, then swap/merge:

# Author agent implements
but branch new author-impl
but commit author-impl -m "feat: implement feature"

# Reviewer agent creates sibling branch for fixes
but branch new reviewer-fixes
# ... reviewer makes fixes ...
but commit reviewer-fixes -m "fix: address review feedback"

# Adopt reviewer fixes into author branch
but rub <reviewer-commit> author-impl

# Clean audit trail, final branch has both

Pattern 5: Agent Swarm (Many Agents, One Branch)

Multiple agents contribute to a single feature:

but branch new shared-feature

# Agent A assigns their work
but rub <a-file-id> shared-feature

# Agent B assigns their work
but rub <b-file-id> shared-feature

# Agent C assigns their work
but rub <c-file-id> shared-feature

# Single commit with all contributions
but commit shared-feature -m "feat: collaborative implementation"

Use with Workspace Rules (but mark) for auto-assignment to branches.

Pattern 6: Pre-Created Stack (Multi-Agent)

Orchestrator pre-creates the stack structure, then agents target specific branches:

# Orchestrator: set up stack structure
but branch new db-migration
but branch new api-endpoints --anchor db-migration
but branch new frontend-views --anchor api-endpoints

# Agent A: targets db-migration (use -p, NOT but stage)
but commit db-migration -m "feat: add user tables" -p m6,p9

# Agent B: targets api-endpoints
but commit api-endpoints -m "feat: add REST endpoints" -p q3,r7

# Agent C: targets frontend-views
but commit frontend-views -m "feat: add user views" -p s1,t4

# All agents work in parallel, same workspace, no checkout

Critical: Use but commit <branch> -p <id> to target specific branches in the stack. Do NOT use but stage — staging is per-stack, not per-branch. but stage silently routes to the stack head when targeting empty branches. See gitbutlerapp/gitbutler#12293.

Once each branch has at least one commit, but stage and but absorb work correctly for subsequent changes.

Pattern 7: Exploratory Development

Compare multiple approaches in parallel:

# Parent branch with shared setup
but branch new perf-parent
but commit perf-parent -m "chore: benchmark setup"

# Strategy A
but branch new perf-strategy-a --anchor perf-parent
but commit perf-strategy-a -m "perf: try caching approach"

# Strategy B
but branch new perf-strategy-b --anchor perf-parent
but commit perf-strategy-b -m "perf: try batching approach"

# Run benchmarks on each, keep winner
but rub <winning-commit> perf-parent

Pattern 8: Emergency Hotfix (Feature Work Continues)

Ship a fix without disturbing ongoing multi-agent work:

# Create isolated hotfix branch
but branch new hotfix-urgent
but rub <file-id> hotfix-urgent
but commit hotfix-urgent -m "fix: prod outage"

# Push and create PR
but push hotfix-urgent
but pr new hotfix-urgent

# Other agents continue unaffected in their lanes

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 --json.

AI Integration Methods

1. Agents Tab (GUI)

• Branch-agent binding in GitButler GUI
• Each virtual branch = independent agent session
• Automatic commit management per session
• Parallel execution with branch isolation
• Access: but gui then navigate to Agents Tab

2. Lifecycle Hooks (CLI)

Platform	Commands
Claude Code	but claude pre-tool, but claude post-tool, but claude stop
Cursor	but cursor after-edit, but cursor stop

Example Claude Code hooks config (.claude/hooks.json):

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

3. MCP Server

but mcp  # Start MCP server for programmatic access

Exposes gitbutler_update_branches tool for async commit processing.

4. Workspace Rules (Auto-Assignment)

but mark agent-auth-branch
but mark agent-api-branch

New changes auto-route to the marked branch.

Key Instruction for All Agents:

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

For detailed hook configs and MCP schemas, see references/ai-integration.md.

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

Coordination Protocols

Status Broadcasting:

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

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

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

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	but push + but pr new ✓
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 ✓

Decision Framework: When to Use What

Use GitButler when:

• Multiple agents work in same repo simultaneously
• Exploratory development (organize code after writing)
• Frequent reorganization of commits between branches
• Visual organization preferred (GUI + CLI)
• Early conflict detection matters

Use Graphite when:

• Fully automated CLI workflows (scripted end-to-end)
• Terminal-first teams
• Established stacked PR practices
• Need gt up/gt down stack navigation

Use Git Worktrees when:

• Complete branch isolation required
• Different dependencies per branch
• CI/CD needs separate checkouts

Don't mix in same repo - Choose one model per repository.

ALWAYS:

• Use unique branch names per agent: <agent>-<type>-<desc>
• Use but commit <branch> -p <id> when targeting branches in a stack — especially empty ones
• 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 but stage to target empty branches in a stack — staging is per-stack and silently routes to stack head; use -p flag on commit instead
• 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

Troubleshooting

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>
but stage routes to stack head	Staging is per-stack; empty branches share staging area	Use but commit <branch> -p <id> instead (#12293)
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 --json
but undo

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

Limitations

• Overlapping file edits — adjacent lines can only go to one branch
• No stack navigation CLI — no gt up/gt down equivalent (all branches always applied)
• MCP server limited — only gitbutler_update_branches tool currently exposed

Reference Files

• references/ai-integration.md — Detailed hook configs, MCP schemas, troubleshooting

Related Skills

• gitbutler-guide — Complete GitButler lifecycle guide

External

• GitButler AI Docs — Official AI integration
• Agents Tab Blog — Claude Code integration details