codebyplan 1.13.4 → 1.13.5

package/README.md

@@ -87,6 +87,40 @@ Show help message.
 
 Print the CLI version.
 
+## cmux integration
+
+When you run Claude Code inside a [cmux](https://github.com/nicholasgasior/cmux) workspace, the `codebyplan` plugin automatically keeps the workspace metadata in sync with your git context:
+
+- **On session start** — the workspace title is set to the current git branch and the workspace description is set to the repo folder basename.
+- **On `git checkout` / `git switch`** — the same sync runs automatically after the Bash tool call completes (the match is broad and a redundant sync on a file-restore checkout is harmless, since `codebyplan cmux-sync` is idempotent).
+
+This means your cmux workspace always reflects which branch and repo you're working in, without any manual intervention.
+
+### How it works
+
+Two hooks handle the sync:
+
+| Hook                         | Event              | Trigger                                    |
+| ---------------------------- | ------------------ | ------------------------------------------ |
+| `cbp-cmux-workspace-sync.sh` | `SessionStart`     | Every new Claude Code session              |
+| `cbp-cmux-branch-watch.sh`   | `PostToolUse Bash` | Any `git checkout` or `git switch` command |
+
+Both hooks delegate all logic to `codebyplan cmux-sync` — no cmux or git logic lives in the shell scripts.
+
+### Binary resolution order
+
+The `cmux` binary is resolved in this order (by `codebyplan cmux-sync`):
+
+1. `$CMUX_BUNDLED_CLI_PATH` — path cmux injects into its Claude hook environment
+2. `$CMUX_CLAUDE_HOOK_CMUX_BIN` — alternative env var the hook environment may set
+3. `cmux` on `$PATH` — fallback to the system-installed binary
+
+### No-op outside cmux
+
+Both hooks check for `$CMUX_WORKSPACE_ID` before doing anything. If you are not running inside a cmux workspace, the hooks exit immediately with no output and no side effects. Repos that do not use cmux are completely unaffected.
+
+---
+
 ## MCP Server
 
 Claude Code connects to CodeByPlan via a remote MCP server. The `setup` command configures this automatically:

package/dist/cli.js

@@ -14,7 +14,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.13.4";
+    VERSION = "1.13.5";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -1449,8 +1449,8 @@ async function runSetup() {
     const deviceId = await getOrCreateDeviceId(projectPath);
     let branch = "main";
     try {
-      const { execSync: execSync6 } = await import("node:child_process");
-      branch = execSync6("git symbolic-ref --short HEAD", {
+      const { execSync: execSync7 } = await import("node:child_process");
+      branch = execSync7("git symbolic-ref --short HEAD", {
         cwd: projectPath,
         encoding: "utf-8"
       }).trim();
@@ -3069,9 +3069,9 @@ async function eslintInit(repoId, projectPath) {
   Install ${missingPkgs.length} missing packages? [Y/n] `
     );
     if (confirmed) {
-      const { execSync: execSync6 } = await import("node:child_process");
+      const { execSync: execSync7 } = await import("node:child_process");
       try {
-        execSync6(installCmd, { cwd: projectPath, stdio: "inherit" });
+        execSync7(installCmd, { cwd: projectPath, stdio: "inherit" });
         console.log("  Packages installed.\n");
       } catch (err) {
         console.error(
@@ -5586,10 +5586,25 @@ var init_scaffold_publish_workflow2 = __esm({
   }
 });
 
+// src/cli/process-exit-signal.ts
+var ProcessExitSignal;
+var init_process_exit_signal = __esm({
+  "src/cli/process-exit-signal.ts"() {
+    "use strict";
+    ProcessExitSignal = class extends Error {
+      code;
+      constructor(code) {
+        super(`process.exit(${code})`);
+        this.name = "ProcessExitSignal";
+        this.code = code;
+      }
+    };
+  }
+});
+
 // src/cli/resolve-worktree.ts
 var resolve_worktree_exports = {};
 __export(resolve_worktree_exports, {
-  ProcessExitSignal: () => ProcessExitSignal,
   runResolveWorktree: () => runResolveWorktree
 });
 import { execSync as execSync5 } from "node:child_process";
@@ -5713,21 +5728,78 @@ function emitAndExit(worktreeId, errorContext, jsonMode) {
   }
   process.exit(0);
 }
-var ProcessExitSignal;
 var init_resolve_worktree2 = __esm({
   "src/cli/resolve-worktree.ts"() {
     "use strict";
     init_flags();
     init_local_config();
     init_resolve_worktree();
-    ProcessExitSignal = class extends Error {
-      code;
-      constructor(code) {
-        super(`process.exit(${code})`);
-        this.name = "ProcessExitSignal";
-        this.code = code;
+    init_process_exit_signal();
+  }
+});
+
+// src/cli/cmux-sync.ts
+var cmux_sync_exports = {};
+__export(cmux_sync_exports, {
+  runCmuxSync: () => runCmuxSync
+});
+import { execSync as execSync6, execFileSync } from "node:child_process";
+import { basename } from "node:path";
+async function runCmuxSync() {
+  try {
+    if (!process.env.CMUX_WORKSPACE_ID) {
+      process.exit(0);
+    }
+    const bin = process.env.CMUX_BUNDLED_CLI_PATH || process.env.CMUX_CLAUDE_HOOK_CMUX_BIN || "cmux";
+    let branch = "";
+    try {
+      branch = execSync6("git rev-parse --abbrev-ref HEAD", {
+        encoding: "utf8"
+      }).trim();
+    } catch {
+    }
+    let folder = "";
+    try {
+      const toplevel = execSync6("git rev-parse --show-toplevel", {
+        encoding: "utf8"
+      }).trim();
+      folder = basename(toplevel);
+    } catch {
+    }
+    if (branch) {
+      try {
+        execFileSync(bin, [
+          "workspace-action",
+          "--action",
+          "rename",
+          "--title",
+          branch
+        ]);
+      } catch {
       }
-    };
+    }
+    if (folder) {
+      try {
+        execFileSync(bin, [
+          "workspace-action",
+          "--action",
+          "set-description",
+          "--description",
+          folder
+        ]);
+      } catch {
+      }
+    }
+    process.exit(0);
+  } catch (err) {
+    if (err instanceof ProcessExitSignal) throw err;
+    process.exit(0);
+  }
+}
+var init_cmux_sync = __esm({
+  "src/cli/cmux-sync.ts"() {
+    "use strict";
+    init_process_exit_signal();
   }
 });
 
@@ -6009,8 +6081,8 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
     const deviceId = await getOrCreateDeviceId(projectPath);
     let branch = "main";
     try {
-      const { execSync: execSync6 } = await import("node:child_process");
-      branch = execSync6("git symbolic-ref --short HEAD", {
+      const { execSync: execSync7 } = await import("node:child_process");
+      branch = execSync7("git symbolic-ref --short HEAD", {
         cwd: projectPath,
         encoding: "utf-8"
       }).trim();
@@ -6555,10 +6627,10 @@ async function runTechStack() {
         );
       }
       try {
-        const { execSync: execSync6 } = await import("node:child_process");
+        const { execSync: execSync7 } = await import("node:child_process");
         let branch = "main";
         try {
-          branch = execSync6("git symbolic-ref --short HEAD", {
+          branch = execSync7("git symbolic-ref --short HEAD", {
             cwd: projectPath,
             encoding: "utf-8"
           }).trim();
@@ -7467,6 +7539,11 @@ void (async () => {
     await runResolveWorktree2();
     process.exit(0);
   }
+  if (arg === "cmux-sync") {
+    const { runCmuxSync: runCmuxSync2 } = await Promise.resolve().then(() => (init_cmux_sync(), cmux_sync_exports));
+    await runCmuxSync2();
+    process.exit(0);
+  }
   if (arg === "config") {
     const { runConfig: runConfig2 } = await Promise.resolve().then(() => (init_config(), config_exports));
     await runConfig2();
@@ -7565,6 +7642,7 @@ void (async () => {
     codebyplan claude                Claude asset management (install/update/uninstall)
     codebyplan statusline            Show or set the statusline renderer (bash/node/python)
     codebyplan resolve-worktree      Resolve active worktree UUID from device+path+branch tuple
+    codebyplan cmux-sync             Sync cmux workspace title/description to current git branch and repo folder
     codebyplan help                  Show this help message
     codebyplan --version             Print version
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.4",
+  "version": "1.13.5",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

package/templates/hooks/README.md

@@ -2,7 +2,7 @@
 
 The `codebyplan` npm package ships a small, portable set of Claude Code hooks. They run in your project, use only generic primitives (`git rev-parse`, `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_PLUGIN_ROOT}`), and degrade gracefully (exit 0) when their preconditions aren't met.
 
-Hook registration lives in [`hooks/hooks.json`](./hooks.json) — PreToolUse and PostToolUse events are wired. (`Notification`, `SessionStart`, `SessionEnd`, `Stop`, and `SubagentStop` are also schema-permitted but unused here.)
+Hook registration lives in [`hooks/hooks.json`](./hooks.json) — SessionStart, PreToolUse, and PostToolUse events are wired. (`Notification`, `SessionEnd`, `Stop`, and `SubagentStop` are also schema-permitted but unused here.)
 
 **`cbp-statusline.sh` is auto-wired via `settings.project.base.json`.** The `statusLine` block is shipped inside `templates/settings.project.base.json` and merged into the consumer's `.claude/settings.json` automatically by `codebyplan claude install` (and on every `codebyplan claude update`). No manual copy-paste is required.
 
@@ -224,13 +224,41 @@ After a `complete_round` MCP call succeeds, reconciles the round's `files_change
 
 ---
 
+### `cbp-cmux-workspace-sync.sh` — SessionStart, matcher `*`
+
+On every session start, syncs the active [cmux](https://github.com/nicholasgasior/cmux) workspace title to the current git branch and the workspace description to the repo folder basename (the directory that contains `.git/`).
+
+**Blocks vs warns**: never blocks — exit 0 on every path. A SessionStart hook must never prevent a session from opening.
+
+**Skips when**: `$CMUX_WORKSPACE_ID` is unset (not running inside a cmux workspace). No-ops silently — cmux is an optional integration and repos without it are completely unaffected.
+
+**cmux binary resolution order**: `$CMUX_BUNDLED_CLI_PATH` → `$CMUX_CLAUDE_HOOK_CMUX_BIN` → `cmux` on `$PATH`. All three are resolved by the `codebyplan cmux-sync` subcommand; the hook itself does not replicate this logic.
+
+**Opt out**: settings.json override removing this entry, or plugin disable.
+
+---
+
+### `cbp-cmux-branch-watch.sh` — PostToolUse, matcher `Bash`
+
+After any Bash tool call that contains a `git checkout` or `git switch` invocation, syncs the active cmux workspace title to the current branch and the workspace description to the repo folder basename. The match is broad — it also fires on file-restore forms like `git checkout -- <file>` — but `codebyplan cmux-sync` is idempotent, so a redundant sync on a non-branch-change is harmless, and a real branch change is never missed.
+
+**Blocks vs warns**: never blocks — exit 0 on every path. PostToolUse hooks must never abort Claude.
+
+**Skips when**: `$CMUX_WORKSPACE_ID` is unset; or the Bash command contains no `git checkout` / `git switch`; or `jq` is not on `$PATH` (safe parse failure → exit 0). Outside cmux or on commands without checkout/switch, the hook exits immediately with no work done.
+
+**cmux binary resolution order**: same as `cbp-cmux-workspace-sync.sh` — delegated to `codebyplan cmux-sync`.
+
+**Opt out**: settings.json override removing the PostToolUse Bash entry for this hook, or plugin disable.
+
+---
+
 ## Supporting (not registered)
 
 ### `test-hooks.sh` — invoked by `auto-test-hooks.sh`
 
-Test suite for the plugin's 9 registered hooks. Runs two passes:
+Test suite for the plugin's 11 registered hooks. Runs two passes:
 
-1. **Header check** — every registered hook (`lint-format-on-edit`, `test-coverage-gate`, `pre-commit-quality-gate`, `maestro-yaml-validate`, `auto-test-hooks`, `mcp-migration-guard`, `validate-git-stash-deny`, `cbp-mcp-round-sync`) carries the required `# Hook:` and `# Purpose:` header comments. `statusline` uses its own `# Claude Code Status Line` marker.
+1. **Header check** — every registered hook (`lint-format-on-edit`, `test-coverage-gate`, `pre-commit-quality-gate`, `maestro-yaml-validate`, `auto-test-hooks`, `mcp-migration-guard`, `validate-git-stash-deny`, `cbp-mcp-round-sync`, `cbp-cmux-workspace-sync`, `cbp-cmux-branch-watch`) carries the required `# Hook:` and `# Purpose:` header comments. `statusline` uses its own `# Claude Code Status Line` marker.
 2. **Functional smoke tests** — each hook is invoked with synthetic stdin matching its fast-path / graceful-degrade input; all must exit 0.
 
 Not in `hooks.json` — invoked indirectly via `auto-test-hooks.sh` on hook edits, or directly via `bash ${CLAUDE_PLUGIN_ROOT}/hooks/test-hooks.sh`.

package/templates/hooks/cbp-cmux-branch-watch.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# @scope: org-shared
+# Hook: PostToolUse Bash
+# Purpose: After a Bash tool call that contains a git checkout or git switch command,
+#          sync the active cmux workspace title to the current git branch and the
+#          workspace description to the repo folder basename.
+#          Delegates entirely to `codebyplan cmux-sync` — no cmux or git logic here.
+#          Matching is broad: it also fires on file-restore forms such as
+#          `git checkout -- <file>`. That is intentional — `codebyplan cmux-sync` is
+#          idempotent, so a redundant sync on a non-branch-change is harmless, and the
+#          broad match guarantees a real branch change is never missed.
+#          No-ops silently when CMUX_WORKSPACE_ID is unset or the command contains no
+#          checkout/switch. Exit 0 on every path — never blocks tool execution.
+
+# Fast-path: skip npx spawn when clearly not in a cmux workspace.
+[ -n "$CMUX_WORKSPACE_ID" ] || exit 0
+
+# Parse stdin — PostToolUse hooks receive JSON on stdin.
+# Guard against jq absence: if jq is not available the whole block is skipped.
+if command -v jq >/dev/null 2>&1; then
+  INPUT=$(cat 2>/dev/null || true)
+  CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+  # Run the sync when the command contains git checkout/switch. Broad match by design:
+  # also catches file-restore forms (e.g. `git checkout -- <file>`); cmux-sync is
+  # idempotent so a redundant sync is harmless, and a real branch change is never missed.
+  if ! echo "$CMD" | grep -qE 'git[[:space:]]+(checkout|switch)' 2>/dev/null; then
+    exit 0
+  fi
+else
+  # jq not available — drain stdin and skip.
+  cat >/dev/null 2>&1 || true
+  exit 0
+fi
+
+# Delegate to the CLI subcommand (self-no-ops when cmux binary is absent).
+npx codebyplan cmux-sync >/dev/null 2>&1 || true
+
+exit 0

package/templates/hooks/cbp-cmux-workspace-sync.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# @scope: org-shared
+# Hook: SessionStart
+# Purpose: On session start, sync the active cmux workspace title to the current git branch
+#          and the workspace description to the repo folder basename.
+#          Delegates entirely to `codebyplan cmux-sync` — no cmux or git logic here.
+#          No-ops silently when CMUX_WORKSPACE_ID is unset (not inside a cmux workspace).
+#          Exit 0 on every path — never blocks session start.
+
+# Fast-path: skip npx spawn when clearly not in a cmux workspace.
+[ -n "$CMUX_WORKSPACE_ID" ] || exit 0
+
+# Drain stdin — SessionStart hooks receive JSON on stdin; we don't use it.
+cat >/dev/null 2>&1
+
+# Delegate to the CLI subcommand (self-no-ops when cmux binary is absent).
+npx codebyplan cmux-sync >/dev/null 2>&1 || true
+
+exit 0

package/templates/hooks/cbp-test-hooks.sh

@@ -135,8 +135,8 @@ fi
 
 echo ""
 
-# ===== NEW HOOK SMOKE TESTS =====
-echo "## New Hook Smoke Tests (CHK-131)"
+# ===== HOOK SMOKE TESTS — validate-git-stash-deny + cbp-mcp-round-sync =====
+echo "## Hook Smoke Tests — validate-git-stash-deny + cbp-mcp-round-sync (CHK-131)"
 
 # --- validate-git-stash-deny.sh ---
 
@@ -255,6 +255,77 @@ fi
 
 echo ""
 
+# ===== HOOK SMOKE TESTS — cbp-cmux-workspace-sync + cbp-cmux-branch-watch =====
+echo "## Hook Smoke Tests — cbp-cmux-workspace-sync + cbp-cmux-branch-watch (CHK-162)"
+
+# --- cbp-cmux-workspace-sync.sh ---
+
+if [ ! -f "$HOOKS_DIR/cbp-cmux-workspace-sync.sh" ]; then
+  test_result "cbp-cmux-workspace-sync.sh present" "passed" "missing"
+else
+  test_result "cbp-cmux-workspace-sync.sh present" "passed" "passed"
+
+  FIRST_LINE=$(head -1 "$HOOKS_DIR/cbp-cmux-workspace-sync.sh")
+  if echo "$FIRST_LINE" | grep -q '^#!/'; then
+    test_result "cbp-cmux-workspace-sync.sh has shebang" "passed" "passed"
+  else
+    test_result "cbp-cmux-workspace-sync.sh has shebang" "passed" "missing"
+  fi
+
+  if grep -q '@scope: org-shared' "$HOOKS_DIR/cbp-cmux-workspace-sync.sh"; then
+    test_result "cbp-cmux-workspace-sync.sh has @scope: org-shared" "passed" "passed"
+  else
+    test_result "cbp-cmux-workspace-sync.sh has @scope: org-shared" "passed" "missing"
+  fi
+
+  # Graceful-degrade: CMUX_WORKSPACE_ID unset → fast-path exit 0, no output
+  ACTUAL_EXIT=$(env -u CMUX_WORKSPACE_ID bash "$HOOKS_DIR/cbp-cmux-workspace-sync.sh" <<< '{}' >/dev/null 2>&1; echo $?)
+  if [ "$ACTUAL_EXIT" = "0" ]; then
+    test_result "cbp-cmux-workspace-sync.sh graceful-degrade (no CMUX_WORKSPACE_ID) exits 0" "passed" "passed"
+  else
+    test_result "cbp-cmux-workspace-sync.sh graceful-degrade (no CMUX_WORKSPACE_ID) exits 0" "passed" "failed"
+  fi
+fi
+
+# --- cbp-cmux-branch-watch.sh ---
+
+if [ ! -f "$HOOKS_DIR/cbp-cmux-branch-watch.sh" ]; then
+  test_result "cbp-cmux-branch-watch.sh present" "passed" "missing"
+else
+  test_result "cbp-cmux-branch-watch.sh present" "passed" "passed"
+
+  FIRST_LINE=$(head -1 "$HOOKS_DIR/cbp-cmux-branch-watch.sh")
+  if echo "$FIRST_LINE" | grep -q '^#!/'; then
+    test_result "cbp-cmux-branch-watch.sh has shebang" "passed" "passed"
+  else
+    test_result "cbp-cmux-branch-watch.sh has shebang" "passed" "missing"
+  fi
+
+  if grep -q '@scope: org-shared' "$HOOKS_DIR/cbp-cmux-branch-watch.sh"; then
+    test_result "cbp-cmux-branch-watch.sh has @scope: org-shared" "passed" "passed"
+  else
+    test_result "cbp-cmux-branch-watch.sh has @scope: org-shared" "passed" "missing"
+  fi
+
+  # Graceful-degrade: CMUX_WORKSPACE_ID unset → fast-path exit 0
+  ACTUAL_EXIT=$(env -u CMUX_WORKSPACE_ID bash "$HOOKS_DIR/cbp-cmux-branch-watch.sh" <<< '{"tool_input":{"command":"git checkout main"}}' >/dev/null 2>&1; echo $?)
+  if [ "$ACTUAL_EXIT" = "0" ]; then
+    test_result "cbp-cmux-branch-watch.sh graceful-degrade (no CMUX_WORKSPACE_ID) exits 0" "passed" "passed"
+  else
+    test_result "cbp-cmux-branch-watch.sh graceful-degrade (no CMUX_WORKSPACE_ID) exits 0" "passed" "failed"
+  fi
+
+  # Non-checkout command → no-op exit 0 (even with CMUX_WORKSPACE_ID set, non-checkout should skip sync)
+  ACTUAL_EXIT=$(CMUX_WORKSPACE_ID=test-ws bash "$HOOKS_DIR/cbp-cmux-branch-watch.sh" <<< '{"tool_input":{"command":"git status"}}' >/dev/null 2>&1; echo $?)
+  if [ "$ACTUAL_EXIT" = "0" ]; then
+    test_result "cbp-cmux-branch-watch.sh non-checkout command exits 0" "passed" "passed"
+  else
+    test_result "cbp-cmux-branch-watch.sh non-checkout command exits 0" "passed" "failed"
+  fi
+fi
+
+echo ""
+
 # ===== SUMMARY =====
 echo "=== TEST SUMMARY ==="
 echo -e "Passed: ${GREEN}$PASSED${NC}"

package/templates/hooks/hooks.json

@@ -1,5 +1,16 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-cmux-workspace-sync.sh"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Edit|Write|MultiEdit",
@@ -59,6 +70,15 @@
             "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-mcp-round-sync.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-cmux-branch-watch.sh"
+          }
+        ]
       }
     ]
   }

package/templates/settings.project.base.json

@@ -176,6 +176,8 @@
       "Bash(npx codebyplan whoami:*)",
       "Bash(codebyplan resolve-worktree:*)",
       "Bash(npx codebyplan resolve-worktree:*)",
+      "Bash(codebyplan cmux-sync:*)",
+      "Bash(npx codebyplan cmux-sync:*)",
       "Bash(codebyplan statusline:*)",
       "Bash(npx codebyplan statusline:*)",
       "Bash(codebyplan ports:*)",