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

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 > /tmp/agent-$(whoami)-status.txt

Or use Linear/GitHub comments

"[AGENT-A] Completed auth module, committed to claude-auth-feature"

Concurrent Safety:

• Snapshot before risky operations

• Broadcast status regularly to other agents

• Respect 🔒 locks — files assigned to other branches

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

• 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

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>

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

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-virtual-branches — Core GitButler workflows

• gitbutler-stacks — Stacked branches

• outfitter:multi-agent-vcs — Tool-agnostic multi-agent policy (invoke with Skill tool)

External

• GitButler AI Docs — Official AI integration

• Agents Tab Blog — Claude Code integration details