5.0 KiB

Raw Blame History

AI Integration Reference

GitButler provides hooks, MCP server, and GUI features for AI agent integration.

Lifecycle Hooks

GitButler CLI commands that can be called from AI agent lifecycle hooks.

Claude Code Hooks

Add to .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 commands:

Command	Trigger	Purpose
`but claude pre-tool`	Before Edit/Write	Prepare workspace, snapshot
`but claude post-tool`	After Edit/Write	Auto-assign changes
`but claude stop`	Session ends	Finalize commits, cleanup

Cursor Hooks

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

Hook commands:

Command	Purpose
`but cursor after-edit`	Auto-assign/commit after Cursor edits
`but cursor stop`	Finalize when task completes

MCP Server

Start GitButler's MCP server for programmatic agent access:

but mcp

Available Tool

gitbutler_update_branches

Updates commits based on prompt and changes. Designed for async processing:

Agent calls after making code changes
GitButler records changes + prompt immediately (returns fast)
Processing happens asynchronously to create commits

Input schema:

{
  prompt: string  // Description of changes made
}

Current limitations:

No branch creation via MCP
No stack management
No push/submit operations
No branch navigation
No restack commands

Future roadmap (from GitButler docs):

Auto-absorbing changes into existing commits
Creating new branches based on prompt theme
Creating stacked branches
More sophisticated commit organization

Agents Tab (GUI)

GitButler GUI provides an Agents Tab for Claude Code integration:

Branch-Agent Binding: Each virtual branch can be tied to an agent session
Parallel Execution: Multiple agents run simultaneously, isolated by branch
Automatic Commit Management: Agent work auto-committed to their branch
Session Persistence: Agent context preserved across restarts

Setup

Open GitButler GUI for repo: but gui
Navigate to Agents Tab
Create agent sessions tied to virtual branches
Configure which branches each agent can modify

Agent Workflow Patterns

Pattern 1: Hook-Based Auto-Commit

Let GitButler handle commits automatically:

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

PostToolUse hook creates commits automatically.

Pattern 2: Explicit Agent Commits

Agent controls commit timing:

# Agent creates branch
but branch new agent-feature

# Agent makes changes...

# Agent assigns and commits explicitly
but rub <file-id> agent-feature
but commit agent-feature -m "feat: implementation"

Pattern 3: Multi-Agent with Marks

Set up auto-assignment for agent branches:

# Agent A's branch receives new changes
but mark agent-a-auth

# Agent B's branch receives new changes
but mark agent-b-api

Key Agent Instructions

When configuring agents to work with GitButler:

Never use git commit - Breaks GitButler state
Never use git add - GitButler manages index
Never use git checkout - All branches always applied
Always return to workspace after any git operations: git checkout gitbutler/workspace
Use but status to find file IDs before using but rub

Troubleshooting

Agent commit "orphaned"

Cause: Agent used git commit instead of but commit.

Solution:

git reflog  # Find orphaned commit
but branch new recovered-work
# Manually apply changes or cherry-pick

MCP server not responding

Cause: Feature may be behind experimental flag.