4.9 KiB

Raw Permalink Blame History

Multi-Agent AI Integration Reference

Detailed configuration and patterns for multi-agent workflows with GitButler.

Hook Configuration by Platform

Claude Code

File: .claude/hooks.json

{
  "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"
          }
        ]
      }
    ]
  }
}

Hook	Purpose
`but claude pre-tool`	Snapshot before changes
`but claude post-tool`	Auto-assign changes to agent's branch
`but claude stop`	Finalize commits, cleanup

Cursor

{
  "hooks": {
    "after-edit": "but cursor after-edit",
    "stop": "but cursor stop"
  }
}

MCP Server

Starting

but mcp

Available Tool

gitbutler_update_branches

{
  prompt: string  // Description of changes
}

Returns immediately; commits processed asynchronously.

Current Limitations

Single tool available
No branch creation
No stack operations
No push/PR operations

Multi-Agent Coordination Strategies

Strategy 1: Branch-Per-Agent

Each agent owns dedicated branch(es):

# Agent A owns auth domain
but branch new agent-a-auth
but mark agent-a-auth

# Agent B owns api domain
but branch new agent-b-api
but mark agent-b-api

# New changes auto-route to marked branch

Best for: Independent parallel development

Strategy 2: Shared Branch with Turn-Taking

Agents share branch, coordinate via file-based status:

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

# Other agents check before modifying

Best for: Sequential refinement of same feature

Strategy 3: Stack-Per-Agent

Agents own stack levels:

# Agent A: Foundation layer
but branch new foundation
but commit foundation -m "feat: foundation"

# Agent B: Build on foundation
but branch new feature --anchor foundation
but commit feature -m "feat: feature layer"

# Agent C: Tests on top
but branch new tests --anchor feature
but commit tests -m "test: comprehensive tests"

Best for: Layered architecture development

Strategy 4: Review Pairs

Author and reviewer agents work in parallel:

# Author implements
but branch new author-impl

# Reviewer creates sibling for fixes
but branch new reviewer-fixes

# Swap commits as needed
but rub <commit> <other-branch>

Best for: Code review cycles

Status Broadcasting

File-Based

# Broadcast status
but status > /tmp/agent-status-$(hostname)-$(date +%s).txt

# Other agents poll status files

Issue Tracker Comments

[AGENT-A] Completed auth module
- Branch: agent-a-auth
- Commits: abc1234
- Ready for review

JSON for Programmatic Inspection

# Machine-readable status
but status --json | jq '.stacks'
but show feature-branch --json | jq '.commits'

Agent Instructions Template

Add to agent system prompt:

## GitButler Rules

1. NEVER use `git commit` - use `but commit`
2. NEVER use `git add` - GitButler manages staging
3. NEVER use `git checkout` - all branches always applied
4. ALWAYS check file IDs with `but status` before `but rub`
5. ALWAYS snapshot before risky operations: `but oplog snapshot`
6. Return to workspace after git ops: `git checkout gitbutler/workspace`

## Your Branch
- Name: {agent-branch-name}
- Pattern: {file-pattern}

Assign your changes: `but rub <file-id> {agent-branch-name}`
Commit your work: `but commit {agent-branch-name} -m "your message"`

Troubleshooting Multi-Agent

Agents modifying same files

Symptom: Overlapping hunks in unassigned changes

Solution:

Assign non-overlapping hunks to respective branches
For overlapping lines: coordinate which agent owns them
Use but mark rules for clearer ownership

Lost agent work

Recovery:

# Check oplog
but oplog

# Undo if recent
but undo

# Or restore from snapshot
but oplog restore <snapshot-id>

Agent committed with git

Symptom: Orphaned commit not in GitButler