opencode-gitbutler 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 gaboe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# opencode-gitbutler
+
+OpenCode plugin for seamless GitButler integration. Automatically manages branches, generates commit messages via LLM, and provides real-time workspace state notifications.
+
+## Installation
+
+```bash
+bun add opencode-gitbutler
+```
+
+## Prerequisites
+
+- **GitButler CLI** (`but`) — [Install via Homebrew](https://docs.gitbutler.com/installation)
+- **OpenCode** — v1.1.0 or later
+- **Bun** — v1.0.0 or later (plugin runtime)
+
+The postinstall script checks for the GitButler CLI and warns if missing (install never fails).
+
+## Quick Start
+
+Add to your OpenCode config (`.opencode/config.json`):
+
+```json
+{
+  "plugins": ["opencode-gitbutler"]
+}
+```
+
+The plugin automatically:
+- Creates and renames branches based on your prompts
+- Generates commit messages using Claude Haiku
+- Injects workspace state into agent context via `SKILL.md`
+- Checks for updates on session creation
+
+## Configuration
+
+Create `.opencode/gitbutler.json` in your workspace root to override defaults:
+
+```json
+{
+  // 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+$"
+}
+```
+
+### 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 |
+
+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 | — | — | `but rub` via `findFileBranch()` | **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`](docs/gitbutler-integration.md).
+
+## Troubleshooting
+
+### GitButler CLI not found
+
+**Error:** `⚠ GitButler CLI not found. Install with: brew install gitbutler`
+
+**Solution:** Install GitButler via Homebrew:
+```bash
+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.
+
+### LLM timeout
+
+If commit message generation times out, increase `llm_timeout_ms` in config:
+```json
+{
+  "llm_timeout_ms": 30000
+}
+```
+
+### Large diffs
+
+If diffs are truncated, increase `max_diff_chars`:
+```json
+{
+  "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

package/command/b-branch-commit.md

@@ -0,0 +1,105 @@
+---
+description: Create GitButler branch from changes and commit
+---
+
+# Create GitButler Branch and Commit
+
+Analyze modified files, create/reuse a `but` branch with a meaningful name, format code, and commit changes.
+
+## Delegation
+
+Delegate change analysis and commit-message drafting; keep formatting and `but commit --changes` execution in the main agent.
+Flow: Subagent (analyze/summarize) -> Main agent (decide/execute).
+
+## Additional Instructions
+
+$ARGUMENTS
+
+## Instructions
+
+### Step 1: Sync and check state
+
+```bash
+but pull
+but status --json -f
+```
+
+Review the output:
+- Identify **unassigned changes** (in `zz` or uncommitted)
+- Identify which files YOU modified (if unsure, list them and ask)
+- Check if an existing branch already matches this work
+
+### Step 2: Decide branch strategy
+
+**If changes are already on a named branch** (not `zz`):
+- Reuse that branch, skip to Step 4
+
+**If changes are unassigned** (in `zz`):
+- Analyze the modified files to understand the scope
+- Classify: `feat/`, `fix/`, `chore/`, `refactor/`, `docs/`
+- Generate descriptive branch name (e.g., `feat/add-user-settings`)
+
+**If an existing branch matches the work:**
+- ASK user whether to reuse it or create new
+
+### Step 3: Create branch and assign changes (if needed)
+
+```bash
+but branch new <branch-name>
+but status --json -f
+but stage <file-id> <branch-name>
+```
+
+Repeat staging for each unassigned file that belongs to this work.
+
+### Step 4: Format code
+
+```bash
+bun run format
+```
+
+### Step 5: Get change IDs and commit
+
+```bash
+but status --json -f
+```
+
+Collect the file/hunk IDs that belong to this branch, then commit:
+
+```bash
+but commit <branch> -m "<type>(<scope>): <description>" --changes <id>,<id>
+```
+
+**Commit message rules:**
+- Use conventional commits: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`, `test:`
+- Include scope when clear (e.g., `feat(auth):`, `fix(ui):`)
+- Short description (max 72 chars)
+- Describe WHAT and WHY, not HOW
+
+If the pre-commit hook fails on YOUR changes, fix the code and retry.
+If the hook fails on pre-existing errors, run `bun run format` and use `--no-hooks`.
+
+### Step 6: Verify
+
+```bash
+but status --json -f
+```
+
+Confirm:
+- Branch exists with correct name
+- Changes are committed
+- No unrelated files were committed
+
+Report: "Branch `<branch-name>` created. Committed: `<commit-message>`"
+
+## Constraints
+
+- **NEVER commit without `--changes`** — this prevents committing other agents' work
+- **NEVER discard changes** in `zz` that you didn't create
+- **NEVER move files** that don't belong to current work
+- **ALWAYS run `bun run format`** before committing
+- If unsure which files belong, **ASK the user**
+
+## State
+
+!`but status --json -f 2>/dev/null || echo "GitButler not active"`

package/command/b-branch-gc.md

@@ -0,0 +1,58 @@
+---
+description: Clean up empty or orphaned GitButler branches
+---
+
+# GitButler Branch Garbage Collection
+
+Identify and remove empty or orphaned `ge-branch-*` branches that have accumulated from past sessions.
+
+## Additional Instructions
+
+$ARGUMENTS
+
+## Instructions
+
+### Step 1: Survey current branches
+
+```bash
+but status --json -f
+```
+
+Review the output and categorize branches:
+
+- **Empty branches**: `ge-branch-*` with 0 commits and 0 assigned changes — safe to remove
+- **Orphaned branches**: `ge-branch-*` with commits but no recent activity — list for user review
+- **Active branches**: branches with assigned changes or recent commits — DO NOT touch
+- **User-named branches**: branches NOT matching `ge-branch-*` — DO NOT touch
+
+### Step 2: Report findings
+
+Present a summary table:
+
+| Branch | Commits | Changes | Status | Action |
+|--------|---------|---------|--------|--------|
+
+### Step 3: Clean up empty branches
+
+For each empty `ge-branch-*` branch (0 commits, 0 changes):
+
+```bash
+but unapply <branch-cli-id>
+```
+
+Report each cleanup result.
+
+### Step 4: Handle orphaned branches
+
+For orphaned `ge-branch-*` branches (has commits but appears stale):
+
+- List them with their last commit message
+- Ask the user which ones to remove
+- Only remove explicitly approved branches
+
+### Safety Rules
+
+- NEVER remove branches that are NOT `ge-branch-*` pattern
+- NEVER remove branches with assigned changes
+- NEVER remove branches without user confirmation (except empty ones)
+- If `but unapply` fails, log the error and continue with the next branch

package/command/b-branch-pr.md

@@ -0,0 +1,221 @@
+---
+description: Create GitButler branch, commit, push, open PR, and monitor CI with auto-fix
+---
+
+# Create GitButler Branch, PR, and Monitor CI
+
+Full workflow: analyze changes → create/reuse branch → commit → push → create PR → monitor CI → auto-fix failures and review comments.
+
+## Delegation
+
+Delegate PR-state and CI-failure analysis; keep branch writes, pushes, and PR updates in the main agent.
+Flow: Subagent (analyze/summarize) -> Main agent (decide/execute).
+
+## Additional Instructions
+
+$ARGUMENTS
+
+## Instructions
+
+### Step 1: Sync and check state
+
+```bash
+but pull
+but status --json -f
+```
+
+Review the output:
+- Identify **unassigned changes** (in `zz` or uncommitted)
+- Identify which files YOU modified (if unsure, list them and ask)
+- Check if an existing branch already matches this work
+
+### Step 2: Decide branch strategy
+
+**If changes are already on a named branch** (not `zz`):
+- Reuse that branch, skip to Step 4
+- Check if branch already has a PR (Step 6 will handle this)
+
+**If changes are unassigned** (in `zz`):
+- Analyze the modified files to understand the scope
+- Classify: `feat/`, `fix/`, `chore/`, `refactor/`, `docs/`
+- Generate descriptive branch name (e.g., `feat/add-user-settings`)
+
+**If an existing branch matches the work:**
+- ASK user whether to reuse it or create new
+
+### Step 3: Create branch and assign changes (if needed)
+
+```bash
+but branch new <branch-name>
+but status --json -f
+but stage <file-id> <branch-name>
+```
+
+Repeat staging for each unassigned file that belongs to this work.
+
+### Step 4: Format and validate
+
+```bash
+bun run format
+bun run check
+```
+
+Fix any issues found by `bun run check` before proceeding. Re-run until clean.
+
+### Step 5: Commit
+
+```bash
+but status --json -f
+```
+
+Collect the file/hunk IDs that belong to this branch, then commit:
+
+```bash
+but commit <branch> -m "<type>(<scope>): <description>" --changes <id>,<id>
+```
+
+**Commit message rules:**
+- Conventional commits: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`, `test:`
+- Include scope when clear (e.g., `feat(auth):`, `fix(ui):`)
+- Short description (max 72 chars)
+
+If format changes were generated, absorb them:
+
+```bash
+but status --json -f
+but absorb <format-file-id>
+```
+
+### Step 6: Push and create/update PR
+
+Push the branch:
+
+```bash
+but push <branch>
+```
+
+Check if a PR already exists for this branch (must specify `--head` in GitButler workspace):
+
+```bash
+bun run gh-tool pr view --head <branch> 2>/dev/null
+```
+
+**If no PR exists**, create one:
+
+```bash
+but pr new <branch> -t
+```
+
+Or with a custom message for more control:
+
+```bash
+but pr new <branch> -m "<PR title>
+
+## Summary
+<1-2 sentences>
+
+## Changes
+- <bullet list>"
+```
+
+**If PR already exists**, update it:
+
+```bash
+bun run gh-tool pr edit <pr_number> --title "<title>" --body "<body>"
+```
+
+Get the PR number for monitoring:
+
+```bash
+bun run gh-tool pr view --head <branch> --json number -q .number
+```
+
+### Step 7: Monitor CI checks
+
+Inform the user: "PR created/updated. Monitoring CI checks... (say 'stop' to exit)"
+
+#### 7.1 Wait for checks
+
+```bash
+bun run gh-tool pr checks --pr <pr_number> --watch --fail-fast > /dev/null 2>&1; echo $?
+```
+
+**Exit codes:**
+- `0` - All checks passed
+- `1` - One or more checks failed
+
+#### 7.2 Handle check results
+
+**If checks failed (exit code 1):**
+
+1. Get failed check details:
+   ```bash
+   bun run gh-tool pr checks-failed --pr <pr_number>
+   ```
+
+2. Analyze the failure, fix locally
+3. Run `bun run check` to validate
+4. Format, commit, and push the fix:
+   ```bash
+   bun run format
+   but status --json -f
+   but commit <branch> -m "fix: resolve CI check failures" --changes <id>,<id>
+   but push <branch>
+   ```
+5. **Go back to Step 7.1**
+
+**If checks passed (exit code 0):**
+
+1. Check for review comments:
+   ```bash
+   bun run gh-tool pr threads --pr <pr_number> --unresolved-only
+   bun run gh-tool pr issue-comments-latest --pr <pr_number> --author claude --body-contains "Claude Code Review"
+   ```
+
+2. **If unresolved review comments exist:**
+   - Inform user: "CI passed but review comments found. Processing..."
+   - **Execute the pr-fix-comments workflow** (Steps 3-7 from pr-fix-comments command):
+     - Analyze each comment
+     - Apply valid fixes
+     - Reply to each comment and resolve threads
+     - Run `bun run check`
+     - Commit and push fixes using `but commit <branch> --changes`
+   - **Go back to Step 7.1** to re-monitor
+
+3. **If no comments:**
+   - Inform user: "All checks passed and no review comments. PR is ready for review!"
+   - Exit
+
+#### 7.3 Loop exit conditions
+
+Exit when:
+- All checks pass AND no unresolved review comments
+- User says "stop"
+- Maximum 5 iterations reached (ask user to continue)
+
+## PR Body Format
+
+```
+## Summary
+<1-2 sentences>
+
+## Changes
+- <bullet list>
+```
+
+## Constraints
+
+- **NEVER commit without `--changes`** — prevents committing other agents' work
+- **NEVER discard changes** in `zz` that you didn't create
+- **NEVER move files** that don't belong to current work
+- **ALWAYS run `bun run format`** before committing
+- **ALWAYS run `bun run check`** before first push
+- If unsure which files belong, **ASK the user**
+
+## State
+
+!`but status --json -f 2>/dev/null || echo "GitButler not active"`
+
+### Existing PR
+!`bun run gh-tool pr view 2>/dev/null || echo "No PR found for current branch"`
+|||||||

package/command/b-branch.md

@@ -0,0 +1,88 @@
+---
+description: Create a GitButler branch from current changes with a descriptive name
+---
+
+# Create GitButler Branch
+
+Analyze all modified/unassigned files, create a new `but` branch with a meaningful name, and assign changes to it.
+
+## Delegation
+
+Delegate change-scope analysis and branch-name proposal; keep branch creation and staging actions in the main agent.
+Flow: Subagent (analyze/summarize) -> Main agent (decide/execute).
+
+## Additional Instructions
+
+$ARGUMENTS
+
+## Instructions
+
+### Step 1: Sync and check state
+
+```bash
+but pull
+but status --json -f
+```
+
+Review the output:
+- Identify **unassigned changes** (in `zz` or uncommitted)
+- Identify which files YOU modified (if unsure, list them and ask)
+- Check if an existing branch already matches this work
+
+### Step 2: Analyze changes and generate branch name
+
+Look at the modified files and understand the scope of changes:
+
+1. Read the changed files to understand what was done
+2. Classify the change type: `feat/`, `fix/`, `chore/`, `refactor/`, `docs/`
+3. Generate a descriptive branch name (e.g., `feat/add-user-settings`, `fix/auth-token-refresh`)
+
+**Branch name rules:**
+- Use conventional prefix: `feat/`, `fix/`, `chore/`, `refactor/`, `docs/`
+- Use kebab-case after prefix
+- Keep it short but descriptive (max 50 chars total)
+- Must describe WHAT the changes do, not WHERE they are
+
+### Step 3: Create branch and assign changes
+
+```bash
+but branch new <branch-name>
+```
+
+Then check status to get file IDs:
+
+```bash
+but status --json -f
+```
+
+If files are unassigned (in `zz`), stage them to the new branch:
+
+```bash
+but stage <file-id> <branch-name>
+```
+
+Repeat for each unassigned file that belongs to this work.
+
+### Step 4: Verify
+
+```bash
+but status --json -f
+```
+
+Confirm:
+- Branch exists with correct name
+- All relevant files are assigned to the branch
+- No unrelated files were moved
+
+Report: "Branch `<branch-name>` created with N files assigned."
+
+## Constraints
+
+- **NEVER discard changes** in `zz` that you didn't create
+- **NEVER move files** that don't belong to current work
+- If unsure which files belong to the branch, **ASK the user**
+- If a matching branch already exists, **ASK** whether to reuse it or create a new one
+
+## State
+
+!`but status --json -f 2>/dev/null || echo "GitButler not active"`

package/dist/auto-update.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Auto-update check for opencode-gitbutler.
+ *
+ * Queries the npm registry for the latest published version and
+ * returns an update notification if a newer version is available.
+ *
+ * Design constraints:
+ * - Never throws — all fetch/parse failures return null.
+ * - No external semver dependency — uses simple numeric comparison.
+ * - Non-blocking — callers should fire-and-forget.
+ * - Respects config.auto_update === false to disable checks.
+ */
+export type UpdateInfo = {
+    current: string;
+    latest: string;
+    updateAvailable: boolean;
+};
+/**
+ * Check the npm registry for a newer version of opencode-gitbutler.
+ *
+ * @returns UpdateInfo if the check succeeds, null on any failure.
+ */
+export declare function checkForUpdate(currentVersion: string): Promise<UpdateInfo | null>;
+export type AutoUpdateConfig = {
+    currentVersion: string;
+    auto_update?: boolean;
+};
+export type AutoUpdateHook = {
+    onSessionCreated: () => Promise<string | null>;
+};
+/**
+ * Create an auto-update hook that checks once per plugin lifecycle.
+ *
+ * The returned `onSessionCreated` should be called from the event handler
+ * when a new root session is created. It fires the update check on the
+ * first invocation and caches the result; subsequent calls return null.
+ */
+export declare function createAutoUpdateHook(config: AutoUpdateConfig): AutoUpdateHook;
+//# sourceMappingURL=auto-update.d.ts.map

package/dist/auto-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-update.d.ts","sourceRoot":"","sources":["../src/auto-update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAgDF;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA6B5B;AASD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,gBAAgB,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAChD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,gBAAgB,GACvB,cAAc,CAqChB"}