codebyplan 1.13.14 → 1.13.16

package/README.md

@@ -91,7 +91,7 @@ Print the CLI version.
 
 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 session start** — the workspace title is set to the current git branch, the workspace description is set to the repo folder basename, and the workspace color is applied from `.codebyplan/cmux.json` (configured via `/cbp-setup-cmux`). If no color is set, a one-line nudge is printed to session output.
 - **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.
@@ -109,7 +109,7 @@ Both hooks delegate all logic to `codebyplan cmux-sync` — no cmux or git logic
 
 ### Binary resolution order
 
-The `cmux` binary is resolved in this order (by `codebyplan cmux-sync`):
+The `cmux` binary is resolved in this order (by `codebyplan cmux-sync` and `codebyplan cmux-status`, both delegating to `resolveCmuxBin()` in `lib/cmux.ts`):
 
 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
@@ -119,6 +119,81 @@ The `cmux` binary is resolved in this order (by `codebyplan cmux-sync`):
 
 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.
 
+### Status surface
+
+`codebyplan cmux-status` pushes CodeByPlan development state into the cmux workspace sidebar. The lifecycle skills (`cbp-task-start`, `cbp-task-complete`, `cbp-round-execute`) call it automatically — no manual invocation is needed.
+
+**Flags:**
+
+| Flag                  | Description                                                     |
+| --------------------- | --------------------------------------------------------------- |
+| `--checkpoint <text>` | Set the `cbp-checkpoint` status key                             |
+| `--task <text>`       | Set the `cbp-task` status key                                   |
+| `--qa <text>`         | Set the `cbp-qa` status key                                     |
+| `--progress <val>`    | Set the sidebar progress bar (0.0–1.0 float, or `N/D` fraction) |
+| `--clear`             | Clear all four keys from the sidebar                            |
+
+**Examples:**
+
+```bash
+# Pushed by cbp-task-start when you start a task:
+npx codebyplan cmux-status --checkpoint "CHK-176: cmux status" --task "TASK-2: implement cmux-status"
+
+# Pushed by cbp-task-complete when a task finishes:
+npx codebyplan cmux-status --task "TASK-2: implement cmux-status done" --progress 2/5
+
+# Pushed by cbp-round-execute after each round:
+npx codebyplan cmux-status --qa "R1 completed"
+
+# Clear all status keys:
+npx codebyplan cmux-status --clear
+```
+
+**`auto_status` toggle.** The command is gated by the `auto_status` field in `.codebyplan/cmux.json` (configured via `/cbp-setup-cmux`). When `auto_status` is `false`, every call is a no-op. The default is `true` — status pushing is enabled as long as the file exists or is absent (absent defaults to enabled).
+
+**No-op outside cmux.** Like `codebyplan cmux-sync`, this command checks for `$CMUX_WORKSPACE_ID` before doing anything. Outside a cmux workspace it exits immediately with no output, so it is safe to call unconditionally from scripts and hooks.
+
+### Auto dev server (`codebyplan cmux-serve`)
+
+`codebyplan cmux-serve` auto-starts the dev server for any app whose source files are touched by the current round, and opens a cmux browser pane pointing at the allocated port. `cbp-round-execute` calls it automatically at round-execution start — no manual invocation is needed.
+
+**How it works:**
+
+The command receives the round's changed file list via `--files <comma-separated paths>`. It reads `.codebyplan/server.json` `port_allocations[]` and resolves which apps' source directories intersect the file list. For each matching app it:
+
+1. Probes the allocated port (500ms `node:net` connection attempt — no `curl`, no `timeout`).
+2. If the port is **not** listening: creates a `cmux new-split down` terminal pane and sends the dev command via `cmux send`.
+3. Opens a browser pane via `cmux new-pane --type browser --url http://localhost:<port>`.
+
+If the port is already listening (another worktree, or a previously started server) it skips straight to step 3 — only the browser pane is opened. This mitigates the multi-worktree port collision by never starting a second server on an already-occupied port.
+
+**App-source-dir heuristic mapping** (from `port_allocations[].label` when `command` / `working_dir` are null):
+
+| Label                          | App dir                    |
+| ------------------------------ | -------------------------- |
+| `Web Dev`                      | `apps/web`                 |
+| `Web Dev (codebyplan-desktop)` | `apps/desktop`             |
+| `Backend Dev`                  | `apps/backend`             |
+| `MCP Dev`                      | `apps/mcp`                 |
+| `Docs Ingest`                  | `apps/docs-ingest`         |
+| `E2E Tests`                    | skipped (not a dev server) |
+
+When `allocation.command` and `allocation.working_dir` are both set (Tier 1), those values are used directly — the label heuristic is skipped. When no mapping exists for a label, one log line is emitted and the allocation is skipped; the rest continue.
+
+**`auto_dev_server` toggle.** Gated by the `auto_dev_server` field in `.codebyplan/cmux.json` (configured via `/cbp-setup-cmux`). When `auto_dev_server` is `false`, every call is a no-op. The default is `true` — the feature is enabled as long as the file is absent or the key is not explicitly set to `false`.
+
+**No-op outside cmux.** Like `codebyplan cmux-status`, this command checks for `$CMUX_WORKSPACE_ID` before doing anything. Outside a cmux workspace it exits immediately with no output and no side effects.
+
+**Examples:**
+
+```bash
+# Called automatically by cbp-round-execute with the round's files:
+npx codebyplan cmux-serve --files "apps/web/src/app/page.tsx,apps/web/src/components/Button.tsx"
+
+# Target a specific app dir instead of a file list:
+npx codebyplan cmux-serve --app apps/backend
+```
+
 ---
 
 ## MCP Server