git:20260801.0de5ac7 to git:20261013.fbe187d

- description: "The Commander Console: one inline panel — agents, usage, safety, memory, history — plus a prompt bar that reaches this session. Publishing a snapshot is separate and consent-gated."

- argument-hint: "[open | overview | usage | safety | memory | history | launch | refresh | publish | on | off]"

- # $ccc-console — the Commander Console

- **The Console lives in your chat. Publishing makes a snapshot page you can keep or share.**

- One panel instead of four separate decks: who's working, what it cost, what got blocked, what you've done over the last month, and a box you can type into that reaches *this* session. It reads only your own local telemetry under `~/.claude/commander/` — the same logs `$ccc-mission-control`, `$ccc-usage` and `$ccc-safety` already read, composed once by `lib/console-model.js`. The one exception is **Memory**, which reads your own claude-mem store at `~/.claude-mem/` if (and only if) you have one.

- > 🔒 **Opening is local.** The inline widget renders from local logs and nothing leaves the machine. **Publishing is a separate act** and always asks first — see below.

- ## How it routes

- On `$ccc-console` with no argument, open the widget on the **Overview** tab (below). Explicit sub-commands skip straight to their tab or action:

- | Argument | What happens |

- |---|---|

- | `overview` (default) | agents working, anything awaiting your approval, task counts |

- | `usage` | saved / spent / dispatches, cost by app |

- | `safety` | blocked, auto-fixed, approved, tool-failure hotspots |

- | `memory` | recent claude-mem observation titles + counts — **optional**, see below |

- | `history` | the last 30 days day by day: cost, dispatches, tasks, failures, top skills |

- | `launch` | one-click chips for the common Commander workflows |

- | `refresh` | re-read the logs and render a fresh widget |

- | `publish` | build the **snapshot artifact** — consent-gated, see below |

- | `on` / `off` | turn the session-start auto-open on or off (see below) |

- ## 🖥️ Open the console (the default — inline widget)

- Build the widget HTML, then render it **inline with the visualize MCP's `show_widget`** — **not** the Artifact tool. This is the whole point of the surface: an inline widget can call the host's `sendPrompt(text)`, so its chips and its prompt bar reach this live session. A published artifact cannot (strict CSP, no completion capability), which is why publishing is a different verb.

- Prefer the in-plugin copy, falling back to the repo checkout — the same pattern `$ccc-browse` uses, because not every install ships `scripts/`:

- The script prints the widget HTML on stdout (add `--out <path>` to write a file instead; `--no-recompute` skips the `ccusage` refresh when you just want a fast read). Pass the output to `show_widget` as `widget_code`, with a specific snake_case `title` such as `commander_console_overview`.

-

- **Zero-state:** a machine that has never run an agent renders friendly cards ("No agent activity yet — spawn one with `$ccc-spawn`"), not errors, and every stat tile shows `—` rather than a fabricated `0`. Never treat missing telemetry as a failure.

-

- **If the visualize MCP isn't available in this session:** say so plainly and offer the published snapshot instead (`$ccc-console publish`) or the deck skills. Do not fake the widget with a markdown table pretending to be interactive.

-

- ### What the widget can do

-

- - **Prompt bar** — the text box sends **exactly what the user typed** into this session via `sendPrompt(text)`, after `sanitizePromptText()` collapses newlines and caps the text at 500 characters. It is never pre-filled from telemetry.

- - **Chips** — every chip is a **fixed template command** (`$ccc-doctor`, `$ccc-suggest`, `$ccc-usage`, `$ccc-browse`, the deck launchers, `$ccc-console refresh|publish`, and the Launch-tab workflows) and displays the exact command it will send *before* the click.

- - **What chips deliberately cannot do:** no chip payload is ever built from an agent name, a task subject, a branch, a file path or a log line. Anything that can append to a JSONL under `~/.claude/commander/` would otherwise be able to compose a command the user appears to have typed. Model text renders as escaped text only. If you extend this skill, keep that rule — `commander/tests/console-widget.test.js` enforces it.

- - **Tabs and refresh cost a round-trip on purpose.** Switching tabs sends `$ccc-console <tab>`; refreshing sends `$ccc-console refresh`. The widget is a snapshot at render time and cannot fetch anything — no polling, no localhost, no live data. That is honest and cheap.

-

- ## 🔆 Auto-open at session start (`on` / `off`)

-

- Since v7.4.0 a SessionStart handler (`hooks/console-autopen.js`) asks the model to render this widget once, near the top of a session. **Opening is local** — it reads your own logs and draws a panel in this chat. It never publishes, and it never asks the network for anything.

-

- It stays quiet unless all of these hold: auto-open isn't switched off · you aren't on CI · the session is genuinely starting (not a resume or a post-compact re-fire) · this session hasn't already been nudged · there is actually telemetry to show. On a fresh install with no agent history, nothing happens. If the user's opening message is a real request, answer that and skip the console.

-

- **Turning it off** — any one of these:

-

- | Off switch | How |

- |---|---|

- | `$ccc-console off` | write `{"autoOpen": false}` to `~/.claude/commander/console.json` (create the file/dir if needed, preserving any other keys), then confirm in one line. `$ccc-console on` writes `{"autoOpen": true}`. |

- | Config file | edit `~/.claude/commander/console.json` by hand |

- | Environment | `CCC_NO_AUTOCONSOLE=1` |

-

- A missing or malformed `console.json` means **on** — a corrupt config must never silently disable something the user didn't turn off.

-

- ## 🧠 The Memory tab — optional, and absent is normal

-

- Memory reads **your own** claude-mem store at `~/.claude-mem/claude-mem.db`, read-only, titles only. Commander does **not** bundle claude-mem: it is AGPL-3.0 and Commander is MIT.

-

- **Most machines will not have it, and that is not a problem to report.** When the store is missing the tab renders one quiet card — "claude-mem not detected", plus how to install it and why it isn't bundled. Do not describe this as an error, do not treat it as a broken install, and do not offer to fix it unless the user asks. `$ccc-doctor` is the wrong pointer here.

-

- Commander reads only `id / project / type / title / created_at_epoch`. It never touches claude-mem's `text`, `facts` or `narrative` columns, and every title is redacted (secret patterns + `/Users/<name>` → `<home>`) and capped before it is rendered. Say so if the user asks what's being read.

-

- ## 📜 The History tab — real data only

-

- History is built from telemetry Commander already writes. **There is no history collector, and you should not invent one.**

-

- - **Backbone:** `mission-control/metrics.jsonl` — durable per-day rollups (cost, dispatches, tasks, failures, sessions). It survives the detail logs' rotation, so it carries the long horizon and is the only source of cost.

- - **Detail (last 30 days):** `skill-runs.jsonl`, `tasks.jsonl`, `agent-runs.jsonl`, `subagent-runs.jsonl`, and the `sessions/` stubs — counted by **filename only**; their contents are never opened.

-

- What does **not** exist and must never be claimed: per-message content, session summaries, or rollups before the first `metrics.jsonl` row. A day with a rollup but no detail is honest — the detail aged out. If a source can't be read, the tab says which one in a muted footnote and shows the rest.

- ## 📤 Publish a snapshot (`$ccc-console publish`)

- A frozen, shareable page — think "export to PDF", not "live dashboard". Render the **artifact** surface for one tab and publish it with the **Artifact** tool.

- **LIVING PATTERN:** always render to the same file path so republishing updates one page instead of leaving a trail. That path is the **Cockpit's** existing one, `<scratchpad>/commander-cockpit.html` (the session-placeholder convention `$ccc-browse` uses — not a literal `scratchpad/` directory relative to cwd) — the console snapshot **absorbs the Cockpit's living URL** rather than minting a fifth Commander URL (Kevin's call, v7.4.0). `$ccc-browse` republishes the same path with the catalog page; both keep favicon `🎛️`, so the bookmark stays the one Commander page it has always been.

- ```bash

- mkdir -p <scratchpad>

- node "${CLAUDE_PLUGIN_ROOT}/scripts/build-console.mjs" \

- --surface artifact --tab overview --out <scratchpad>/commander-cockpit.html

- ```

- (Same `if [ -f … ]` fallback as above when `${CLAUDE_PLUGIN_ROOT}/scripts/` isn't present.)

- Publish that file with favicon `🎛️` and the stable title **"Commander Console"**. Never invent a new path or filename for it — a new path is a new URL, and every existing bookmark stops updating.

- **Same-file-path alone only redeploys to the same URL within the session that first published it.** A fresh session that never itself ran `$ccc-browse` or `$ccc-console publish` has no memory of the Commander Cockpit's URL, and publishing by file path alone in that session mints a brand-new URL instead of updating the shared one. Before publishing, check whether you already know the URL (from earlier in this same session); if not, call the Artifact tool's `list` action to find the existing "Commander Cockpit" artifact and pass its URL via `url=` on the publish call. Only fall back to a plain file-path publish (which mints a new URL) if `list` finds no prior "Commander Cockpit" artifact at all.

- The four deck skills work the same way in reverse: `$ccc-mission-control`, `$ccc-usage` and `$ccc-safety` publish **one tab each** through this same builder onto their own existing paths (`<scratchpad>/mission-control-live.html`, `<scratchpad>/ccc-usage-live.html`, `<scratchpad>/ccc-safety-live.html`), so their URLs keep updating in place and every page comes from one renderer — the same `url=` lookup applies to each of them.

- **Confirm before the FIRST publish this session:** use `AskUserQuestion` to tell the user that **agent names, task subjects and timings will leave the machine** for their private claude.ai artifact URL — private to their account, but off the machine. Publish only after an explicit confirmation, and never publish automatically. **Re-invoking `$ccc-console publish` IS the refresh consent** — republish the same path without re-asking.

- `--tab launch` has no artifact form (a chip launcher is meaningless on a static page); the script refuses it rather than emitting a dead page. `--tab memory` and `--tab history` both publish. **Memory adds a consent consideration:** publishing it sends claude-mem observation *titles* off the machine — name that explicitly in the confirmation, not just "agent names and task subjects".

- > **On Codex:** some panels are thin on Codex today — Safety's failure hotspots, the agent roster and Usage's savings hero are fed by Claude-side hooks. The same note the decks carry applies here.

- ## When you'd reach for it

- - "What's going on?" at the top of a session — one panel instead of four commands.

- - Mid-session, when you want to fire off `$ccc-doctor` or `$ccc-suggest` without breaking your train of thought.

- - End of day: `publish` a snapshot as the durable record.

- ## When NOT to use

- - You want the **full** roster, event feed and charts — that's `$ccc-mission-control` (and the deck artifacts are richer than 680px allows).

- - You want the searchable skill/agent catalog with the prompt enhancer — that's `$ccc-browse` (the Cockpit).

- - You want advice rather than a report — that's `$ccc-suggest`.

- ## Limitations

- - The console only sees work journaled by the plugin's hooks — agents run without CC Commander installed leave no trace.

- - The widget is a snapshot at render time; it has no network access in either direction. `refresh` re-runs the read.

- - `agent-runs.jsonl` rotates at 10MB, so ancient detail ages out.

- - `--tab launch` is widget-only: a chip launcher is meaningless on a static page, so it has no published form.

- ## Related

- - `$ccc-mission-control` — the full agent board (live dashboard + snapshot)

- - `$ccc-usage` — the money deck in full

- - `$ccc-safety` — blocked and auto-fixed actions in full

- - `$ccc-browse` — the Cockpit catalog

- - `$ccc-doctor` — check your hooks are actually wired