opencode-gitbutler

Stop managing git branches manually and let your AI agents do the heavy lifting with GitButler.

Why This Plugin?

AI agents generate code at a pace that manual version control can't match. Without automation, you end up with massive commits, messy branch organization, and generic messages that make code review a nightmare.

This plugin bridges the gap by bringing GitButler's virtual branch power directly into your OpenCode agent sessions.

What This Plugin Does Differently

• Only tool that combines automatic branch creation, LLM commits, file assignment, and context injection.
• Zero-config setup. Just add it to your plugins and go.
• Works with GitButler virtual branches to avoid worktree overhead.
• Impersonates Cursor for full GitButler CLI compatibility.
• Session-first routing: every edit/write is assigned via but cursor after-edit.
• Unique multi-agent session mapping so subagents stay on the parent branch.
• Hunk-level rub guard in post-stop recovery to avoid unsafe auto-moves.

Installation

1. Add plugin to OpenCode config

Add to your opencode.json (global or project-level):

{
  "plugin": [
    "opencode-gitbutler@latest"
  ]
}

OpenCode will install the plugin automatically on next launch.

2. Install GitButler CLI

brew install gitbutler

See GitButler installation docs for other methods.

3. Install the GitButler skill (recommended)

The plugin includes a skill that teaches your agent GitButler commands, safety rules, and workflows. Install it as a project-level skill so the agent can load it on demand:

npx skills add https://github.com/gaboe/opencode-gitbutler --skill but --agent opencode --yes

Why? The plugin handles automation (auto-branch, auto-commit), but the agent also needs to know how to use but commands directly. Without the skill, the agent falls back to raw git commands which break the GitButler workspace.

4. Restart OpenCode

The plugin automatically:

• Routes every edit/write through GitButler's after-edit
• Creates and renames branches based on your prompts
• Rewords commit messages using Claude Haiku (with deterministic fallback)
• Injects workspace state notifications into agent context
• Checks for updates on session creation

How Branch Assignment Works

This plugin uses a session-first flow. In practice:

1. On every edit/write, the plugin resolves your root session (parent session for subagents).
2. It derives a deterministic conversation_id from that root session (or from branch_target, when configured).
3. It always calls but cursor after-edit with that conversation_id and file path.
4. On idle/stop, it calls but cursor stop for that same conversation_id.
5. In post-stop processing, it may:
   • sweep edited files and but rub unassigned changes when attribution is safe,
   • reword commit message,
   • rename default ge-branch-* names,
   • sync OpenCode session title,
   • clean empty default branches.

This avoids cross-session branch pollution and keeps subagent edits attached to the parent session branch.

Configuration

Create .opencode/gitbutler.json in your workspace root to override defaults:

{
  // Enable debug logging to .opencode/plugin/debug.log
  "log_enabled": true,

  // LLM provider and model for commit message generation
  "commit_message_provider": "anthropic",
  "commit_message_model": "claude-haiku-4-5",

  // Timeout for LLM requests (milliseconds)
  "llm_timeout_ms": 15000,

  // Maximum diff size to send to LLM (characters)
  "max_diff_chars": 4000,

  // Maximum length of auto-generated branch slugs
  "branch_slug_max_length": 50,

  // Enable automatic version update checks
  "auto_update": true,

  // Regex pattern for default branch detection
  "default_branch_pattern": "^ge-branch-\\d+$",

  // Milliseconds before file lock is considered stale
  "stale_lock_ms": 300000,

  // Max age of pending notifications before expiry
  "notification_max_age_ms": 300000,

  // Enable branch inference heuristics in post-stop sweep
  "inference_enabled": true,

  // Optional: force all sessions onto one branch seed
  "branch_target": "",

  // Reserved (currently no-op)
  "edit_debounce_ms": 200,
  "gc_on_session_start": false
}

Configuration Reference

Key	Type	Default	Description
log_enabled	boolean	true	Write debug logs to .opencode/plugin/debug.log
commit_message_provider	string	"anthropic"	LLM provider ID
commit_message_model	string	"claude-haiku-4-5"	Model ID for commit generation
llm_timeout_ms	number	15000	Request timeout in milliseconds
max_diff_chars	number	4000	Max diff size sent to LLM
branch_slug_max_length	number	50	Max auto-generated branch name length
auto_update	boolean	true	Check npm for newer versions
default_branch_pattern	string	"^ge-branch-\\d+$"	Regex for default branch detection
stale_lock_ms	number	300000	Lock age threshold before stale cleanup
notification_max_age_ms	number	300000	Expiry window for queued state notifications
inference_enabled	boolean	true	Enable branch inference in post-stop sweep
branch_target	string	unset	Force all sessions to one branch seed (disables per-session isolation)
edit_debounce_ms	number	200	Reserved, currently no-op
gc_on_session_start	boolean	false	Reserved, currently no-op

All fields are optional. Missing fields use defaults.

Feature Parity vs Native Integrations

How this plugin compares to GitButler's built-in Cursor and Claude Code integrations:

Feature	Cursor	Claude Code	This Plugin	Status
Post-edit hook	after-edit	PostToolUse	tool.execute.after	Equal
Stop/idle hook	stop	Stop	session.idle	Equal
Branch creation	get_or_create_session	get_or_create_session	via conversation_id	Equal
Auto-assign to existing branch	Internal	Internal	Session-first after-edit + safe post-stop but rub sweep	Better
Branch auto-rename (LLM)	From Cursor DB	From transcript	but reword + user prompt	Equal
Auto-commit on stop	handle_changes()	handle_changes()	via but cursor stop	Equal
Commit message (LLM)	OpenAI gpt-4-mini	OpenAI gpt-4-mini	Claude Haiku via OpenCode SDK	Equal
Multi-agent session mapping	—	—	resolveSessionRoot()	Unique
File locking (concurrent)	—	60s wait + retry	60s poll + stale cleanup	Equal
Agent state notifications	—	—	chat.messages.transform	Unique
Hunk-level rub guard	—	—	Skip multi-stack files	Better

Score: 7 Equal, 4 Better/Unique

For the full architecture breakdown, gap analysis, and known issues, see docs/gitbutler-integration.md.

Known Operational Limits

• The plugin only performs GitButler actions in workspace mode (gitbutler/workspace branch).
• If branch_target is set, all sessions intentionally share one branch seed.
• edit_debounce_ms and gc_on_session_start are reserved config fields and are currently no-op.
• GitButler CLI still has upstream edge cases around unapply/pull after squash-merge with deleted remote branches (see linked issues in docs/gitbutler-integration.md).

Troubleshooting

GitButler CLI not found

Error: ⚠ GitButler CLI not found. Install with: brew install gitbutler

Solution: Install GitButler via Homebrew:

brew install gitbutler

The plugin will work without it, but workspace commands will fail at runtime.

Config file not found

If .opencode/gitbutler.json is missing, the plugin uses all defaults. No error is raised.

Debug logging

Enable log_enabled: true in config to write detailed logs to .opencode/plugin/debug.log. Useful for diagnosing branch creation, commit message generation, and state injection issues.

Wrong branch assignment

If changes still appear on an unexpected branch:

1. Ensure branch_target is not set in .opencode/gitbutler.json.
2. Check .opencode/plugin/session-map.json and confirm subagent sessions resolve to the expected parent.
3. Inspect .opencode/plugin/debug.log for after-edit, session-stop, and branch-collision events.
4. Run but status --json -f and verify where the file is currently assigned.

LLM timeout

If commit message generation times out, increase llm_timeout_ms in config:

{
  "llm_timeout_ms": 30000
}

Large diffs

If diffs are truncated, increase max_diff_chars:

{
  "max_diff_chars": 8000
}

Workspace Guide

See SKILL.md bundled with this package for detailed GitButler workspace commands, multi-agent safety rules, and known issues.

License

MIT