opencode-gitbutler 0.1.0

package/dist/logger.d.ts

@@ -0,0 +1,21 @@
+export type LogLevel = "info" | "warn" | "error";
+export type Logger = {
+    info: (cat: string, data?: Record<string, unknown>) => void;
+    warn: (cat: string, data?: Record<string, unknown>) => void;
+    error: (cat: string, data?: Record<string, unknown>) => void;
+};
+/**
+ * Structured NDJSON logger with explicit levels.
+ *
+ * Each line is a self-contained JSON object:
+ *   {"ts":"...","level":"info","cat":"cursor-ok","subcommand":"after-edit",...}
+ *
+ * Reserved keys: ts, level, cat. All data fields are spread at top level.
+ * Parseable with: jq, grep, or any NDJSON-aware tool.
+ * Filter examples:
+ *   jq 'select(.level == "error")'
+ *   jq 'select(.cat == "cursor-ok")'
+ *   grep '"cat":"llm-' debug.log | jq .
+ */
+export declare function createLogger(logEnabled: boolean, cwd: string): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD,MAAM,MAAM,MAAM,GAAG;IACnB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC5D,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC5D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAC9D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAwBrE"}

package/dist/notify.d.ts

@@ -0,0 +1,11 @@
+import type { Logger } from "./logger.js";
+export type ContextNotification = {
+    message: string;
+    timestamp: number;
+};
+export type NotificationManager = {
+    addNotification: (sessionID: string | undefined, message: string) => void;
+    consumeNotifications: (sessionID: string) => string | null;
+};
+export declare function createNotificationManager(log: Logger, resolveSessionRoot: (sessionID: string | undefined) => string, maxAgeMs?: number): NotificationManager;
+//# sourceMappingURL=notify.d.ts.map

package/dist/notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../src/notify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,eAAe,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1E,oBAAoB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC5D,CAAC;AAEF,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,EAC7D,QAAQ,SAAU,GACjB,mBAAmB,CAuFrB"}

package/dist/plugin.d.ts

@@ -0,0 +1,21 @@
+/**
+ * OpenCode plugin: GitButler integration via Cursor hook facade.
+ *
+ * Bridges OpenCode's plugin hooks to GitButler's `but cursor` CLI:
+ * - tool.execute.after (edit/write)                  -> but cursor after-edit
+ * - session.idle                                     -> but cursor stop
+ * - experimental.chat.messages.transform             -> inject pending state notifications
+ *
+ * This enables automatic branch creation, file-to-branch assignment,
+ * and auto-commit when using GitButler workspace mode with OpenCode.
+ *
+ * Uses Cursor hook format because it has simpler stdin JSON requirements
+ * than Claude Code hooks (no transcript_path needed).
+ *
+ * Multi-agent support: Each OpenCode session gets its own branch via
+ * conversation_id isolation in GitButler's session tracking.
+ */
+import type { Plugin } from "@opencode-ai/plugin";
+import type { GitButlerPluginConfig } from "./config.js";
+export declare function createGitButlerPlugin(config?: GitButlerPluginConfig): Plugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAUzD,wBAAgB,qBAAqB,CACnC,MAAM,GAAE,qBAA6C,GACpD,MAAM,CA+nBR"}

package/dist/reword.d.ts

@@ -0,0 +1,104 @@
+import type { Logger } from "./logger.js";
+import type { Cli } from "./cli.js";
+import type { BranchOwnership } from "./state.js";
+import type { NotificationManager } from "./notify.js";
+import type { GitButlerPluginConfig } from "./config.js";
+export type RewordDeps = {
+    cwd: string;
+    log: Logger;
+    cli: Cli;
+    config: GitButlerPluginConfig;
+    defaultBranchPattern: RegExp;
+    addNotification: NotificationManager["addNotification"];
+    resolveSessionRoot: (sessionID: string | undefined) => string;
+    conversationsWithEdits: Set<string>;
+    rewordedBranches: Set<string>;
+    branchOwnership: Map<string, BranchOwnership>;
+    editedFilesPerConversation: Map<string, Set<string>>;
+    savePluginState: (conversations: Set<string>, reworded: Set<string>, ownership: Map<string, BranchOwnership>) => Promise<void>;
+    internalSessionIds: Set<string>;
+    reapStaleLocks: () => void;
+    client: {
+        session: {
+            messages: (opts: {
+                path: {
+                    id: string;
+                };
+                query: {
+                    limit: number;
+                };
+            }) => Promise<{
+                data?: Array<{
+                    info: {
+                        role: string;
+                    };
+                    parts: Array<{
+                        type: string;
+                        text?: string;
+                    }>;
+                }>;
+            }>;
+            create: (opts: {
+                body: {
+                    title: string;
+                };
+            }) => Promise<{
+                data?: {
+                    id: string;
+                };
+            }>;
+            prompt: (opts: {
+                path: {
+                    id: string;
+                };
+                body: {
+                    model: {
+                        providerID: string;
+                        modelID: string;
+                    };
+                    system: string;
+                    tools: Record<string, never>;
+                    parts: Array<{
+                        type: "text";
+                        text: string;
+                    }>;
+                };
+            }) => Promise<{
+                data?: {
+                    parts: Array<{
+                        type: string;
+                        text?: string;
+                    }>;
+                };
+            }>;
+            delete: (opts: {
+                path: {
+                    id: string;
+                };
+            }) => Promise<unknown>;
+            update: (opts: {
+                path: {
+                    id: string;
+                };
+                body: {
+                    title: string;
+                };
+            }) => Promise<unknown>;
+        };
+    };
+};
+export declare const COMMIT_PREFIX_PATTERNS: Array<{
+    pattern: RegExp;
+    prefix: string;
+}>;
+export declare function detectCommitPrefix(text: string): string;
+export declare function toCommitMessage(prompt: string): string;
+export declare function toBranchSlug(prompt: string, maxLength: number): string;
+export type RewordManager = {
+    fetchUserPrompt: (sessionID: string) => Promise<string | null>;
+    generateLLMCommitMessage: (commitId: string, userPrompt: string) => Promise<string | null>;
+    postStopProcessing: (sessionID: string | undefined, conversationId: string, stopFailed?: boolean) => Promise<void>;
+};
+export declare function classifyRewordFailure(stderr: string): string;
+export declare function createRewordManager(deps: RewordDeps): RewordManager;
+//# sourceMappingURL=reword.d.ts.map

package/dist/reword.d.ts.map

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

package/dist/state.d.ts

@@ -0,0 +1,38 @@
+import type { Logger } from "./logger.js";
+export type HookInput = {
+    tool?: string;
+    sessionID?: string;
+    callID?: string;
+};
+export type HookOutput = {
+    title?: string;
+    output?: string;
+    metadata?: Record<string, unknown>;
+};
+export type EventPayload = Record<string, unknown> & {
+    type?: string;
+    properties?: Record<string, unknown>;
+};
+export type BranchOwnership = {
+    rootSessionID: string;
+    branchName: string;
+    firstSeen: number;
+};
+export type PluginState = {
+    conversationsWithEdits: string[];
+    rewordedBranches: string[];
+    branchOwnership: Record<string, BranchOwnership>;
+};
+export declare const SUBAGENT_TOOLS: Set<string>;
+export type StateManager = {
+    loadPluginState: () => Promise<PluginState>;
+    savePluginState: (conversations: Set<string>, reworded: Set<string>, ownership: Map<string, BranchOwnership>) => Promise<void>;
+    loadSessionMap: () => Promise<Map<string, string>>;
+    saveSessionMap: (map: Map<string, string>) => Promise<void>;
+    resolveSessionRoot: (sessionID: string | undefined) => string;
+    trackSubagentMapping: (input: HookInput, output?: HookOutput) => Promise<void>;
+    trackSessionCreatedMapping: (event: EventPayload) => Promise<void>;
+    parentSessionByTaskSession: Map<string, string>;
+};
+export declare function createStateManager(cwd: string, log: Logger): StateManager;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAClD,CAAC;AAEF,eAAO,MAAM,cAAc,aAIzB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG;IACzB,eAAe,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5C,eAAe,EAAE,CACf,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,EAC1B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,EACrB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,KACpC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,cAAc,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,kBAAkB,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,CAAC;IAC9D,oBAAoB,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E,0BAA0B,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,0BAA0B,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjD,CAAC;AAEF,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,YAAY,CA6Md"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "opencode-gitbutler",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OpenCode plugin for GitButler integration",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target bun --format esm && tsc --emitDeclarationOnly",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run clean && bun run build",
+    "postinstall": "node postinstall.mjs",
+    "test": "bun test"
+  },
+  "files": [
+    "dist",
+    "postinstall.mjs",
+    "skill",
+    "command"
+  ],
+  "keywords": [
+    "opencode",
+    "plugin",
+    "gitbutler",
+    "git",
+    "branches",
+    "ai"
+  ],
+  "author": "gaboe",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gaboe/opencode-gitbutler.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gaboe/opencode-gitbutler/issues"
+  },
+  "homepage": "https://github.com/gaboe/opencode-gitbutler#readme",
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "typescript": "^5.3.0"
+  }
+}

package/postinstall.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { execSync } from "child_process";
+
+try {
+  execSync("but --version", { stdio: "pipe" });
+  console.log("✓ GitButler CLI found");
+} catch {
+  console.warn("⚠ GitButler CLI not found. Install with: brew install gitbutler");
+}

package/skill/gitbutler/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: but
+version: 0.19.0
+description: Commit, push, branch, and manage version control. Use for git commit, git status, git push, git diff, creating branches, staging files, editing history, pull requests, or any git/version control operation. Replaces git write commands with 'but' - always use this instead of raw git.
+author: GitButler Team
+---
+
+# GitButler CLI Skill
+
+Help users work with GitButler CLI (`but` command) in workspace mode.
+
+## New Session Workflow
+
+**EVERY new agent session that involves code changes MUST follow this flow:**
+
+1. **Sync first** → `but pull` to get latest upstream changes (prevents conflicts and stale base)
+2. **Check state** → `but status` to see existing branches and unstaged changes
+3. **Decide branch** →
+   - If an existing branch matches the task → reuse it (it's already applied)
+   - If this is new work → `but branch new <task-name>` (e.g. `feat/add-auth`, `fix/login-bug`)
+   - If you need to resume unapplied work → `but apply <branch>`
+4. **Make changes** → Edit files as needed
+5. **Stage & commit** → `but commit <branch> -m "message" --changes <id>,<id>`
+6. **Refine** → Use `but absorb` or `but squash` to clean up history
+7. **Push when ready** → `but push <branch>`
+8. **Create PR** → `but pr new <branch> -t` (uses default target branch)
+
+**Branch naming**: Use conventional prefixes: `feat/`, `fix/`, `chore/`, `refactor/`
+
+**Commit early, commit often.** Don't hesitate to create commits - GitButler makes editing history trivial. You can always `squash`, `reword`, or `absorb` changes into existing commits later. Small atomic commits are better than large uncommitted changes.
+
+## After Using Write/Edit Tools
+
+When ready to commit:
+
+1. Run `but status --json` to see uncommitted changes and get their CLI IDs
+2. Commit the relevant files directly: `but commit <branch> -m "message" --changes <id>,<id>`
+
+You can batch multiple file edits before committing - no need to commit after every single change.
+
+## Critical Concept: Workspace Model
+
+**GitButler ≠ Traditional Git**
+
+- **Traditional Git**: One branch at a time, switch with `git checkout`
+- **GitButler**: Multiple stacks simultaneously in one workspace, changes assigned to stacks
+
+**This means:**
+
+- ❌ Don't use `git status`, `git commit`, `git checkout`
+- ✅ Use `but status`, `but commit`, `but` commands
+- ✅ Read-only git commands are fine (`git log`, `git diff`)
+
+## Hard Safety Rules (Non-Negotiable)
+
+1. **Never discard changes you did not create.**
+   - `zz` (unassigned) often contains work from other sessions/agents/users.
+   - If unrelated changes exist, leave them untouched and ask before any discard action.
+2. **Never leave your own changes in `zz` at the end of work.**
+   - 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.
+
+## Quick Start
+
+**Installation:**
+
+```bash
+curl -sSL https://gitbutler.com/install.sh | sh
+but setup                          # Initialize in your repo
+but skill install --path <path>    # Install/update skill (agents use --path with known location)
+```
+
+**Note for AI agents:**
+- When installing or updating this skill programmatically, always use `--path` to specify the exact installation directory. The `--detect` flag requires user interaction if multiple installations exist.
+- **Use `--json` flag for all commands** to get structured, parseable output. This is especially important for `but status --json` to reliably parse workspace state.
+
+**Core workflow:**
+
+```bash
+but status --json       # Always start here - shows workspace state (JSON for agents)
+but branch new feature  # Create new stack for work
+# Make changes...
+but commit <branch> -m "…" --changes <id>,<id>  # Commit specific files by CLI ID
+but push <branch>       # Push to remote
+```
+
+## Essential Commands
+
+For detailed command syntax and all available options, see [references/reference.md](references/reference.md).
+For a hands-on learning guide, see [references/tutorial.md](references/tutorial.md).
+For a one-page quick lookup, see [references/cheatsheet.md](references/cheatsheet.md).
+
+**IMPORTANT for AI agents:** Add `--json` flag to all commands for structured, parseable output.
+
+**Understanding state:**
+
+- `but status --json` - Overview (START HERE, always use --json for agents)
+- `but status --json -f` - Overview with full file lists (use when you need to see all changed files)
+- `but show <id> --json` - Details about commit/branch
+- `but diff <id>` - Show diff
+
+**Flags explanation:**
+- `--json` - Output structured JSON instead of human-readable text (always use for agents)
+- `-f` - Include detailed file lists in status output (combines with --json: `but status --json -f`)
+
+**Organizing work:**
+
+- `but branch new <name>` - Independent branch
+- `but branch new <name> -a <anchor>` - Stacked branch (dependent)
+- `but stage <file> <branch>` - Pre-assign file to branch (optional, for organizing before commit)
+
+**Making changes:**
+
+- `but commit <branch> -m "msg" --changes <id>,<id>` - Commit specific files or hunks (recommended)
+- `but commit <branch> -m "msg" -p <id>,<id>` - Same as above, using short flag
+- `but commit <branch> -m "msg"` - Commit ALL uncommitted changes to branch
+- `but commit <branch> --only -m "msg"` - Commit only pre-staged changes (cannot combine with --changes)
+- `but amend <file-id> <commit-id>` - Amend file into specific commit (explicit control)
+- `but absorb <file-id>` - Absorb file into auto-detected commit (smart matching)
+- `but absorb <branch-id>` - Absorb all changes staged to a branch
+- `but absorb` - Absorb ALL uncommitted changes (use with caution)
+
+**Getting IDs for --changes:**
+- **File IDs**: `but status --json` - commit entire files
+- **Hunk IDs**: `but diff --json` - commit individual hunks (for fine-grained control when a file has multiple changes)
+
+**Editing history:**
+
+- `but rub <source> <dest>` - Universal edit (stage/amend/squash/move)
+- `but squash <commits>` - Combine commits
+- `but reword <id>` - Change commit message/branch name
+
+**Remote operations:**
+
+- `but pull` - Update with upstream
+- `but push [branch]` - Push to remote
+- `but pr new <branch>` - Push and create pull request (auto-pushes, no need to push first)
+- `but pr new <branch> -m "Title..."` - Inline PR message (first line is title, rest is description)
+- `but pr new <branch> -F pr_message.txt` - PR message from file (first line is title, rest is description)
+- For stacked branches, the custom message (`-m` or `-F`) only applies to the selected branch; dependent branches use defaults
+
+## Key Concepts
+
+For deeper understanding of the workspace model, dependency tracking, and philosophy, see [references/concepts.md](references/concepts.md).
+
+**CLI IDs**: Every object gets a short ID (e.g., `c5` for commit, `bu` for branch). Use these as arguments.
+
+**Parallel vs Stacked branches**:
+
+- Parallel: Independent work that doesn't depend on each other
+- Stacked: Dependent work where one feature builds on another
+
+**The `but rub` primitive**: Core operation that does different things based on what you combine:
+
+- File + Branch → Stage
+- File + Commit → Amend
+- Commit + Commit → Squash
+- Commit + Branch → Move
+
+## Workflow Examples
+
+For complete step-by-step workflows and real-world scenarios, see [references/examples.md](references/examples.md).
+
+**Starting independent work:**
+
+```bash
+but status --json
+but branch new api-endpoint
+but branch new ui-update
+# Make changes, then commit specific files to appropriate branches
+but status --json  # Get file CLI IDs
+but commit api-endpoint -m "Add endpoint" --changes <api-file-id>
+but commit ui-update -m "Update UI" --changes <ui-file-id>
+```
+
+**Committing specific hunks (fine-grained control):**
+
+```bash
+but diff --json             # See hunk IDs when a file has multiple changes
+but commit <branch> -m "Fix first issue" --changes <hunk-id-1>
+but commit <branch> -m "Fix second issue" --changes <hunk-id-2>
+```
+
+**Cleaning up commits:**
+
+```bash
+but absorb              # Auto-amend changes
+but status --json       # Verify absorb result
+but squash <branch>     # Squash all commits in branch
+```
+
+**Resolving conflicts:**
+
+```bash
+but resolve <commit>    # Enter resolution mode
+# Fix conflicts in editor
+but resolve finish      # Complete resolution
+```
+
+**Managing workspace:**
+
+```bash
+but config target origin/test   # Set default PR target (requires unapply all branches first)
+but unapply <branch>            # Remove branch from workspace (keeps commits)
+but apply <branch>              # Bring branch back into workspace
+but teardown                    # Exit GitButler mode → normal git
+but setup                       # Re-enter GitButler mode
+but discard <ids>               # Discard unstaged changes
+```
+
+## Post-Merge PR Flow
+
+After a PR is squash-merged on GitHub, follow this exact sequence:
+
+```bash
+but unapply <merged-branch>    # MUST do BEFORE pull - prevents orphan branch errors
+but pull                        # Pull merged changes from remote
+```
+
+**Critical**: If you `but pull` before unapplying the merged branch, GitButler will error with orphan branch conflicts. Always unapply first.
+
+**If `but unapply` fails** (branch already gone from workspace after remote deletion with `--delete-branch`), `but pull` may also fail with "resolution mismatch" errors because the ghost stack still exists internally. In this case, the GitButler desktop app can handle it — tell the user to run `but pull` from the GUI. Alternatively, use `but teardown` → `but setup` → `but config target origin/<branch>` to reset.
+
+**After `but teardown` → `but setup`**: Target config resets. Run `but config target origin/<branch>` again.
+
+## Using `--no-hooks` Safely
+
+When pre-commit hooks fail on pre-existing errors unrelated to your changes, use `--no-hooks`. But this skips the formatter too:
+
+```bash
+bun run format                                    # Format FIRST
+but commit <branch> -m "msg" --changes <ids> --no-hooks  # Then commit without hooks
+```
+
+Alternatively, commit normally and absorb formatter fixes:
+
+```bash
+but commit <branch> -m "msg" --changes <ids>      # Commit (hooks may fix formatting)
+but absorb                                         # Absorb any auto-formatted changes
+```
+
+## Known Issues & Workarounds
+
+| Issue | What happens | Workaround |
+|-------|-------------|------------|
+| `but resolve` loses target config | After entering resolve mode, `but config target` resets to "not set" | Run `but config target origin/<branch>` again after `but resolve finish`. If finish fails, do `git checkout gitbutler/workspace` → `but teardown` → `but setup` |
+| `but absorb` hunk lock | Absorb assigns hunk to wrong commit when it's locked by another commit on a different branch | Use `but amend <file> <commit>` for explicit control instead of absorb |
+| `but pr new` has no `--base` flag | Always creates PR against default target | Set target first: `but config target origin/<branch>` |
+| `but config target` requires unapply | Cannot change target with applied branches | `but unapply` all → change target → `but apply` |
+| `but config forge auth` is interactive | Cannot run in non-interactive agent mode | User must run in terminal + grant org access on GitHub |
+| `but commit` pre-commit hook fails | Hook fails on pre-existing errors unrelated to your changes | `but commit --no-hooks` if errors are not from your changes. **Always `bun run format` first** since `--no-hooks` skips the formatter |
+| `but branch delete` last segment | Cannot delete if it would leave anonymous segment | Use `but unapply` instead of delete |
+| `but stage` prefix matching | Branch name can be abbreviated | `but stage <id> ch` works for `chore/gitbutler-setup` |
+| `but discard` hunk range error | Discarding file-level changes sometimes fails with hunk range errors | Use `git checkout -- <file>` instead of `but discard` for file-level discards |
+| `but teardown` + `but setup` resets target | After teardown/setup cycle, target config is lost | Run `but config target origin/<branch>` again after setup |
+| 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>` |
+
+## Critical Safety Rules
+
+1. **NEVER discard changes you didn't create.** Unassigned changes in `zz` may belong to other agents, sessions, or the user. Always ask the user before running `but discard` or `git checkout --` on any change you don't recognize. In GitButler workspace, multiple actors work in parallel — discarding "stale" or "already merged" changes is a destructive assumption.
+2. **Always assign your changes to a branch immediately.** Don't leave edits sitting in `zz` (unassigned). After editing files, stage them to your working branch with `but stage <file-id> <branch>` or commit directly with `--changes`.
+
+## Guidelines
+
+1. Always start with `but status --json` to understand current state (agents should always use `--json`)
+2. Create a new stack for each independent work theme
+3. Use `--changes` to commit specific files directly - no need to stage first
+4. **Commit early and often** - don't wait for perfection. Unlike traditional git, GitButler makes editing history trivial with `absorb`, `squash`, and `reword`. It's better to have small, atomic commits that you refine later than to accumulate large uncommitted changes.
+5. **Use `--json` flag for ALL commands** when running as an agent - this provides structured, parseable output instead of human-readable text
+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