nntrivi2001
d2fc4a4701
Internal SmartGift build of a Claude Code monitoring dashboard. Lanes: a durable unit of parallel agent work, one per working directory, tracked across session restarts. Managed lanes are git worktrees the dashboard provisions and can reset or remove behind a three-check destroy guard and a counted preflight; adopted lanes are directories you already own and are never destroyable. Pipelines: a lane moves through pipeline stages. A stage the agent declares with evidence renders green; a stage inferred from the tool-event stream renders dashed amber and never counts as done. Detection is forward-only within a 30-minute window, and never writes the declared stage. Workspace: one page at /run with a lane grid, the selected lane's pipeline, and a full Claude console behind a disclosure.
115 lines
4.2 KiB
Markdown
115 lines
4.2 KiB
Markdown
# 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.
|
|
|
|
## 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 from the browser.** Spawn a session in a lane's directory, stream
|
|
its output, send follow-ups, resume any past session.
|
|
- **Analytics, alerts, Kanban 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 and run
|
|
|
|
```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 <http://localhost:4820>.
|
|
|
|
Development, with hot reload:
|
|
|
|
```bash
|
|
npm run dev # server on :4820, Vite client on :5173
|
|
```
|
|
|
|
`DASHBOARD_PORT` overrides the port. `postinstall` writes the Claude Code hook
|
|
entries that feed the dashboard.
|
|
|
|
## 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 sessions # recent sessions
|
|
ccam lanes # lanes with stage and progress
|
|
ccam stage <name> # 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
|
|
```
|
|
|
|
The declared stage comes from `ccam stage`. The inferred stage comes from tool
|
|
events and expires after `DETECTION_TTL_MS` (default 30 minutes), so a lane can
|
|
move backwards between work sessions. Detection never writes the declared stage,
|
|
and an inferred node never renders as done.
|
|
|
|
[`docs/LANES.md`](docs/LANES.md) has the pipeline model, the destroy guard, the
|
|
preflight contract, the Workspace page, and `GET /api/lanes/:id/git`.
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
npm run test:server # node:test
|
|
npm run test:client # Vitest
|
|
```
|
|
|
|
Both must be green before a commit; the pre-commit hook runs them plus Prettier.
|
|
|
|
## Layout
|
|
|
|
| Path | What |
|
|
|---|---|
|
|
| `server/` | Express API, SQLite schema, hook ingest, lane and worktree libraries |
|
|
| `client/` | React 18 + Vite + Tailwind dashboard |
|
|
| `bin/ccam.js` | CLI |
|
|
| `mcp/` | MCP server exposing read-only dashboard tools |
|
|
| `desktop/` | Electron wrapper that embeds the server |
|
|
| `docs/` | Architecture, API, lanes, database, deployment |
|
|
| `plugins/` | Claude Code plugins shipped with the dashboard |
|
|
|
|
## Docs
|
|
|
|
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — request flow, schema, WebSocket surface
|
|
- [`docs/LANES.md`](docs/LANES.md) — lanes, pipelines, stage detection
|
|
- [`docs/API.md`](docs/API.md) — REST endpoints (`openapi.yaml` is generated)
|
|
- [`docs/DATABASE.md`](docs/DATABASE.md) — tables and migrations
|
|
- [`INSTALL.md`](INSTALL.md) · [`DEPLOYMENT.md`](DEPLOYMENT.md) · [`DESKTOP.md`](DESKTOP.md)
|
|
- [`CLAUDE.md`](CLAUDE.md) — the rules an agent working in this repo must follow
|