# Claude Code Monitor Internal SmartGift build. Local-first dashboard for Claude Code: hooks POST every tool call to an Express + SQLite server, a React UI updates over WebSocket, and **lanes** track parallel agent work through a pipeline. Internal build — all rights reserved. *(Tiếng Việt: [README.vi.md](README.vi.md))* ## What it does - **Sessions, agents, events.** Everything Claude Code emits, recorded and searchable: tool calls, token usage, cost, subagent trees, transcripts. - **Lanes.** One lane per working directory, surviving session restarts. A lane moves through pipeline stages and the dashboard shows where it is. - **Stage detection.** The stage is inferred from the tool stream, so a session that never calls `ccam stage` still shows progress — rendered dashed amber and never as done, because an inference is not evidence. - **Run Claude Code or Codex from the browser.** A real terminal (tmux + a real PTY, rendered with xterm.js) attached to a lane's directory — the exact TUI you'd see locally, fully interactive, resumable, and attachable from a real terminal too via `ccam lanes shell`. Which CLI it starts is the lane's own setting. - **Analytics (in-dashboard tab), alerts, and a workflow view**, plus an MCP server and a CLI. ## Requirements Node **>= 20** (`engines` in `package.json`). Node **24** is what the test suites are verified on — node 25 currently breaks 6 server tests through a better-sqlite3 ABI mismatch and 20 client tests through a global `localStorage` change. ## Install as a Claude Code plugin Two commands on a machine that has nothing but Claude Code, no clone and no `npm run setup`: ``` /plugin marketplace add Smartgift-AI/Claude-Code-Monitor /plugin install ccam@claude-code-agent-monitor-plugins ``` The first session start installs the hooks, boots the server, puts `ccam` on PATH and connects the MCP tools; it runs detached, so the session never waits on it. `/ccam-doctor` reports the state, `/ccam-open` builds the UI and prints the URL, `/ccam-update` refreshes after a plugin update. This path needs Node **>= 22.5** (no native `better-sqlite3`, so the server uses `node:sqlite`). Details, including what to delete on uninstall: [`docs/PLUGINS.md`](docs/PLUGINS.md). ## Install from a checkout ```bash npm run setup # root, client and vscode-extension dependencies npm run build # builds the client into client/dist npm start # serves the built client and the API on :4820 ``` Open . Development, with hot reload: ```bash npm run dev # server on :4820, Vite client on :5173 ``` `DASHBOARD_PORT` overrides the port, `DASHBOARD_CLIENT_DIST` overrides where the built UI is served from (defaults to `client/dist`; the plugin install points it at its own runtime directory). `postinstall` writes the Claude Code hook entries that feed the dashboard — do not run it when the `ccam` plugin is installed, or every event is counted twice. ### Run as a service (auto-start on boot) `npm start` only runs while that terminal (or `ccam start`'s background process) is alive — a reboot loses it. On Linux, `ccam service install` sets up a systemd `--user` service instead, so `:4820` is up again on its own after every reboot, with no manual step and no Claude Code (or any AI tool) needed to trigger it: ```bash npm run build # the service serves the built client, same as npm start ccam service install # writes + enables ~/.config/systemd/user/ccam.service ccam service status # systemctl --user status ccam ccam service uninstall # disable and remove it ``` `ccam service install` also tries `loginctl enable-linger` so the service starts on a cold boot, before anyone logs in; if that needs elevated rights on your machine it prints the `sudo loginctl enable-linger ` command to run once yourself. Plugin installs get the same persistence automatically — see [Auto-start on boot](docs/PLUGINS.md#auto-start-on-boot) in `docs/PLUGINS.md`. ## The CLI `ccam` is linked by `npm run setup`; otherwise call `node bin/ccam.js`. ```bash ccam status # is the dashboard up ccam start # start it in the background and wait for healthy ccam service install # auto-start on boot via systemd --user (Linux) ccam sessions # recent sessions ccam lanes # lanes with stage and progress ccam lanes pipeline # this lane's pipeline template, or switch it ccam stage # declare the current lane's stage ccam tail # live event feed ``` `ccam --help` lists the rest. ## Lanes A lane is a working directory the dashboard watches. Two kinds: - **adopted** — a directory you already had. The dashboard only reads it; it is never reset or deleted. - **managed** — a git worktree the dashboard created under `LANES_ROOT`. It owns the full lifecycle and may reset or remove it, behind a three-check destroy guard and a counted preflight the caller has to echo back. ```bash ccam lanes add --cwd /path/to/repo --title "My feature" # adopt ccam lanes add --repo /path/to/repo --slug my-feature # managed worktree ``` Every lane also carries the CLI that drives it — `claude` (the default) or `codex` — picked in the Add-lane modal and fixed for the life of the lane. A Codex lane's run panel offers Codex's own sandbox, approval and reasoning-effort choices, and resumes with `codex resume --last`. Codex emits none of this dashboard's hooks, so a Codex lane records its runs but stays absent from Sessions and Analytics. Its **stage detection** works anyway, from Codex's own rollout journals on disk (`$CODEX_HOME/sessions/**/rollout-*.jsonl`, polled every `DASHBOARD_CODEX_POLL_MS` ms, default 15000), and on a Codex lane a detection also **advances the declared stage** — the one place an inference moves the blue `current` ring, because a Codex session has no hook and nothing else would ever move it. What a Codex lane cannot get for free is *evidence*: an auto-advanced node stays amber (`passed-no-evidence`), never green, since only the session itself can say what it finished. Three things help it get there: the run console pre-fills a codex pane's opening prompt with a stage-declaration checklist built from its own pipeline nodes, `ccam lanes agents install` writes the same instructions as a marker-delimited block in the lane's `AGENTS.md`, and a 60s sweep (`DASHBOARD_CODEX_NUDGE_MS`, `0` disables) types a one-line reminder into a lane's pane if its current stage sits without evidence for more than two minutes. The declared stage comes from `ccam stage`. The inferred stage comes from tool events and expires after `DETECTION_TTL_MS` (default 5 minutes), so a lane can move backwards between work sessions. Detection never writes the declared stage, and an inferred node never renders as done. A lane's pipeline template can be switched after creation — `ccam lanes pipeline