opencode-gitbutler 0.1.3 → 0.1.5

package/README.md

@@ -13,7 +13,7 @@ This plugin bridges the gap by bringing GitButler's virtual branch power directl
 ### What This Plugin Does Differently
 
 - Only tool that combines automatic branch creation, LLM commits, file assignment, and context injection.
-- Zero-config setup. Just run `bun add` and add it to your plugins.
+- 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.
 - Unique multi-agent session mapping.
@@ -21,37 +21,29 @@ This plugin bridges the gap by bringing GitButler's virtual branch power directl
 
 ## Installation
 
-Install the package from npm:
+### 1. Add plugin to OpenCode config
 
-```bash
-bun add opencode-gitbutler
-```
-
-Or add it to your plugins array in `.opencode/config.json`:
+Add to your `opencode.json` (global or project-level):
 
 ```json
 {
-  "plugins": ["opencode-gitbutler"]
+  "plugin": [
+    "opencode-gitbutler@latest"
+  ]
 }
 ```
 
-## Prerequisites
+OpenCode will install the plugin automatically on next launch.
 
-- **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)
+### 2. Install GitButler CLI
 
-The postinstall script checks for the GitButler CLI and warns if missing (install never fails).
-
-## Quick Start
+```bash
+brew install gitbutler
+```
 
-Add to your OpenCode config (`.opencode/config.json`):
+See [GitButler installation docs](https://docs.gitbutler.com/installation) for other methods.
 
-```json
-{
-  "plugins": ["opencode-gitbutler"]
-}
-```
+### 3. Restart OpenCode
 
 The plugin automatically:
 - Creates and renames branches based on your prompts

package/command/b-branch-gc.md

@@ -6,6 +6,14 @@ description: Clean up empty or orphaned GitButler branches
 
 Identify and remove empty or orphaned `ge-branch-*` branches that have accumulated from past sessions.
 
+## When to Run
+
+- **After multi-session work** — each agent session may create `ge-branch-*` branches that become empty after commits are moved or squashed
+- **When `but status` shows 3+ `ge-branch-*` branches** — workspace clutter slows down branch selection and increases lock contention
+- **After `but cursor stop` failures** — the plugin's auto-cleanup has ~12% failure rate; empty branches may persist
+- **When user reports "too many branches"** — proactively offer to run this command
+- **User-named branches are NEVER auto-cleaned** — only `ge-branch-*` pattern branches are candidates
+
 ## Additional Instructions
 
 $ARGUMENTS

package/dist/index.js

@@ -892,8 +892,46 @@ function createRewordManager(deps) {
     let cleanupCount = 0;
     let failCount = 0;
     let latestBranchName = null;
+    const owner = branchOwnership.get(conversationId);
+    const ownershipMatches = !owner || owner.rootSessionID === rootSessionID;
+    if (!ownershipMatches && owner) {
+      log.warn("branch-ownership-mismatch", {
+        conversationId,
+        expectedRootSessionID: owner.rootSessionID,
+        actualRootSessionID: rootSessionID
+      });
+    }
+    const candidateBranchCliIds = new Set;
+    if (ownershipMatches && editedFiles && editedFiles.size > 0) {
+      for (const filePath of editedFiles) {
+        const branchInfo = cli.findFileBranch(filePath, status);
+        if (branchInfo.branchCliId) {
+          candidateBranchCliIds.add(branchInfo.branchCliId);
+        }
+      }
+    }
+    if (ownershipMatches && owner?.branchName && !owner.branchName.startsWith("conversation-")) {
+      for (const stack of status.stacks) {
+        for (const branch of stack.branches ?? []) {
+          if (branch.name === owner.branchName) {
+            candidateBranchCliIds.add(branch.cliId);
+          }
+        }
+      }
+    }
+    const candidateBranches = status.stacks.flatMap((stack) => stack.branches ?? []).filter((branch) => candidateBranchCliIds.has(branch.cliId));
+    if (candidateBranches.length === 0) {
+      log.info("post-stop-no-candidate-branches", {
+        conversationId,
+        rootSessionID,
+        editedFiles: editedFiles?.size ?? 0,
+        ownerBranchName: owner?.branchName
+      });
+    }
     for (const stack of status.stacks) {
       for (const branch of stack.branches ?? []) {
+        if (!candidateBranchCliIds.has(branch.cliId))
+          continue;
         if (branch.branchStatus !== "completelyUnpushed")
           continue;
         if (branch.commits.length === 0)
@@ -993,18 +1031,27 @@ function createRewordManager(deps) {
         }
       }
     }
-    if (!latestBranchName) {
-      const existing = status.stacks.flatMap((s) => s.branches ?? []).filter((b) => b.commits.length > 0 && !defaultBranchPattern.test(b.name));
-      if (existing.length > 0) {
-        latestBranchName = existing[existing.length - 1].name;
-      }
+    const shouldSetTitle = candidateBranches.length === 1;
+    if (!shouldSetTitle && candidateBranches.length > 1) {
+      log.info("session-title-skipped-ambiguous", {
+        conversationId,
+        rootSessionID,
+        candidateBranches: candidateBranches.map((b) => ({
+          cliId: b.cliId,
+          name: b.name
+        }))
+      });
     }
-    if (latestBranchName) {
-      client.session.update({
-        path: { id: rootSessionID },
-        body: { title: latestBranchName }
-      }).catch(() => {});
-      addNotification(sessionID, `Session title updated to \`${latestBranchName}\``);
+    if (shouldSetTitle) {
+      const singleBranch = candidateBranches[0];
+      const titleToSet = latestBranchName ?? singleBranch.name;
+      if (titleToSet) {
+        client.session.update({
+          path: { id: rootSessionID },
+          body: { title: titleToSet }
+        }).catch(() => {});
+        addNotification(sessionID, `Session title updated to \`${titleToSet}\``);
+      }
     }
     for (const stack of status.stacks) {
       for (const branch of stack.branches ?? []) {

package/dist/reword.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reword.d.ts","sourceRoot":"","sources":["../src/reword.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reword.d.ts","sourceRoot":"","sources":["../src/reword.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-gitbutler",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "OpenCode plugin for GitButler integration",
   "main": "dist/index.js",

package/skill/gitbutler/SKILL.md

@@ -60,6 +60,9 @@ You can batch multiple file edits before committing - no need to commit after ev
    - After edits, run `but status --json` and move your file/hunk IDs to the correct branch via `but stage` or `but commit --changes`.
 3. **Validate branch ownership before commit.**
    - Confirm each changed file/hunk belongs to the intended branch/task, then commit only those IDs.
+4. **Respect branch ownership across sessions.**
+   - In multi-agent environments, branches may belong to other agent sessions. Never reword, rename, or push branches you didn't create in this session.
+   - If you need to modify another session's branch, ask the user first.
 
 ## Quick Start
 
@@ -257,6 +260,34 @@ but absorb                                         # Absorb any auto-formatted c
 | Lefthook `pre-commit.old` accumulates | Lefthook creates `pre-commit.old` backup that conflicts on next install | Add `rm -f .git/hooks/pre-commit.old` to `prepare` script in package.json |
 | `but pull` before unapply | Pulling with merged branches still applied causes orphan errors | **Always** `but unapply <merged-branch>` before `but pull` |
 | `but unapply` after remote branch deletion | `but unapply` fails with "branch not found" when remote deleted the branch (e.g. `--delete-branch` on merge), and subsequent `but pull` fails with "resolution mismatch" | Use GitButler desktop app to pull, or `but teardown` → `but setup` → `but config target origin/<branch>` |
+| Split-hunk files stuck in `zz` | File has hunks locked to commits on different branches — GitButler sets `stack_id=None`, plugin considers file "handled" via lock reference | Manually commit each hunk: `but diff --json` to get hunk IDs, then `but commit <branch> -m "msg" --changes <hunk-id>` for each |
+| Plugin auto-cleanup misses empty branches | `ge-branch-*` cleanup has ~12% failure rate; user-named empty branches are never auto-cleaned | Run `/b-branch-gc` command or manually `but unapply <branch-id>` |
+| Notifications not reaching agent | Plugin notification delivery is ~55% (259 queued vs 142 delivered in observed sessions) | Always verify state with `but status --json` — don't rely on `<system-reminder>` notifications alone |
+
+### Diagnosing `zz` Stuck Files
+
+When files are stuck in `zz` (unassigned) and don't auto-recover:
+
+1. **Identify the cause:**
+   ```bash
+   but status --json -f    # Look for files in zz with [LOCKED] markers
+   but diff --json          # Get hunk-level IDs and see lock targets
+   ```
+
+2. **If hunks are locked to different branches** (split-hunk scenario):
+   - Each hunk must be committed to its locked branch individually
+   - `but commit <branch> -m "msg" --changes <hunk-id>` for each hunk
+   - Or `but rub <hunk-id> <commit-id>` to amend into the locked commit
+
+3. **If files have no locks but are still in `zz`:**
+   - Plugin's `after-edit` may have failed silently — stage manually
+   - `but stage <file-id> <branch>` or commit with `--changes`
+
+4. **If many files are stuck after `but cursor stop`:**
+   - Run `but rub <file-id> <branch-id>` for each file to force assignment
+   - This is the most reliable recovery method
+
+**Key insight:** Auto-recovery won't fix multi-branch locked files. If you see `[LOCKED]` in `zz`, manual intervention is required.
 
 ## Critical Safety Rules
 
@@ -273,3 +304,27 @@ but absorb                                         # Absorb any auto-formatted c
 6. Use `--dry-run` flags (push, absorb) when unsure
 7. **Run `but pull` frequently** — at session start, before creating branches, and before pushing. Stale workspace = merge conflicts
 8. When updating this skill, use `but skill install --path <known-path>` to avoid prompts
+9. **Check for `zz` files with locks before finishing work.** Run `but status --json -f` and look for files in `zz` with `[LOCKED]` markers. These won't auto-recover — you must manually commit each hunk to its correct branch using `--changes <hunk-id>`. See [references/concepts.md — Hunk Locking](references/concepts.md) for details.
+10. **Don't trust notifications alone** — plugin notification delivery is ~55%. Always verify workspace state with `but status --json` before making assumptions about branch assignments or commit status.
+
+## Plugin Auto-Behaviors (What Happens Behind the Scenes)
+
+The GitButler plugin performs several actions automatically. **You do NOT need to do these yourself** — but you should know they happen so you don't duplicate work or get confused by unexpected state changes.
+
+| Behavior | Trigger | What It Does |
+|----------|---------|--------------|
+| **File auto-assign** | After each file edit | Finds which branch owns the file and runs `but cursor after-edit` or `but rub` to assign it |
+| **Auto-commit** | Session idle (agent stops editing) | Runs `but cursor stop` which commits all uncommitted changes to their assigned branches |
+| **LLM commit reword** | After auto-commit | Rewrites generic commit messages using Claude Haiku based on the actual diff |
+| **Branch rename** | After auto-commit | Renames `ge-branch-*` branches to descriptive names based on user's prompt |
+| **Empty branch cleanup** | After auto-commit | Removes `ge-branch-*` branches with 0 commits (~88% success rate) |
+| **Session title sync** | After auto-commit | Updates session title from branch name |
+| **Context injection** | Before each agent message | Injects `<system-reminder>` with workspace notifications (branch created, commits made, etc.) |
+
+### What This Means for You
+
+1. **Don't manually rename `ge-branch-*` branches** — the plugin will do it after idle
+2. **Don't reword auto-generated commit messages** — the plugin rewrites them with LLM
+3. **If you see unexpected commits** — check if the plugin auto-committed during an idle event
+4. **Notification delivery is ~55%** — not all injected notifications reach you. Always verify state with `but status --json` rather than relying on notifications
+5. **Empty branch cleanup can fail** — if you see stale `ge-branch-*` branches, run `/b-branch-gc`

package/skill/gitbutler/references/cheatsheet.md

@@ -201,6 +201,7 @@ but pull                        # Then pull merged changes
 | `M` | Modified |
 | `D` | Deleted |
 | `[LOCKED]` | File depends on specific commit (absorb target) |
+| `zz` | Unassigned — file not staged to any branch |
 | `●` | Commit |
 | `CONFLICTED` | Needs conflict resolution |
 
@@ -269,3 +270,16 @@ but pr new feat/my-feature -t
 but unapply feat/my-feature
 but pull
 ```
+
+---
+
+## Troubleshooting Quick Reference
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Files stuck in `zz` with `[LOCKED]` | Hunks locked to commits on different branches | `but diff --json` → commit each hunk individually with `--changes <hunk-id>` |
+| Files in `zz` after edits (no locks) | Plugin `after-edit` didn't auto-assign | `but stage <file-id> <branch>` or `but commit <branch> -m "msg" --changes <id>` |
+| Many empty `ge-branch-*` branches | Plugin auto-cleanup failed (~12% failure rate) | Run `/b-branch-gc` or `but unapply <branch-id>` for each |
+| `but absorb` puts hunk on wrong commit | Hunk locked to commit on different branch | Use `but amend <file-id> <commit-id>` for explicit control |
+| `but pull` fails after PR merge | Merged branch still applied in workspace | `but unapply <merged-branch>` first, then `but pull` |
+| Changes "disappear" after `but cursor stop` | Plugin auto-committed to a `ge-branch-*` | `but status --json -f` — check all branches for your files |

package/skill/gitbutler/references/concepts.md

@@ -177,6 +177,40 @@ Prevents you from creating broken states:
 - Can't stage changes to wrong branches
 - Ensures each branch remains independently functional
 
+## Hunk Locking & Split Files
+
+When a file has changes touching lines that belong to commits on **different branches**, GitButler "locks" those hunks.
+
+### How Locking Works
+
+```
+File: src/api.ts
+  Line 10-15: depends on commit C1 (branch: feat/auth)
+  Line 40-50: depends on commit C3 (branch: fix/validation)
+  Line 80-90: new code, no dependency
+```
+
+- Lines 10-15 are **locked to** `feat/auth` — shown as `[LOCKED → C1]`
+- Lines 40-50 are **locked to** `fix/validation` — shown as `[LOCKED → C3]`
+- Lines 80-90 are **free** — can be staged/committed to any branch
+
+### Split Hunk Assignment (`zz` Trap)
+
+When a file's hunks are locked to **multiple different branches**, GitButler cannot auto-assign the file to any single branch. The file stays in `zz` (unassigned) with lock markers.
+
+**This is the most common cause of files "stuck in `zz`"** — the plugin's `after-edit` hook sees the file is mentioned on a branch (via lock) and considers it "handled", but the file remains unassigned.
+
+**Resolution:**
+
+1. Run `but status --json -f` to identify locked files in `zz`
+2. Use `but diff --json` to see individual hunk IDs and their lock targets
+3. Commit or amend each hunk individually: `but commit <branch> -m "msg" --changes <hunk-id>`
+4. Or use `but rub <hunk-id> <commit-id>` to amend specific hunks into their locked commits
+
+### Key Takeaway
+
+If files are stuck in `zz` with `[LOCKED]` markers, **don't wait for auto-recovery** — it won't happen for multi-branch locks. Manually assign each hunk to its correct branch.
+
 ## Empty Commits as Placeholders
 
 You can create empty commits: