feat: Claude Code Monitor — lanes, pipelines and a merged workspace
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.
This commit is contained in:
@@ -0,0 +1,23 @@
|
||||
# Optional dev-container image for Claude Code Agent Monitor.
|
||||
# Node 22 to match the production Dockerfile and the project's engines.
|
||||
# Adds the native-addon toolchain (better-sqlite3 builds via node-gyp) plus
|
||||
# Python 3 (statusline.py and helper scripts) and the sqlite3 CLI.
|
||||
#
|
||||
# This image is ONLY used by Dev Containers / Codespaces. Host-based development
|
||||
# (npm run dev / npm start) is unaffected.
|
||||
#
|
||||
# Author: Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
FROM mcr.microsoft.com/devcontainers/javascript-node:22
|
||||
|
||||
# node-gyp needs python3 + a C/C++ toolchain to compile better-sqlite3.
|
||||
# python-is-python3 makes `python` resolve to python3 for node-gyp.
|
||||
# sqlite3 is handy for inspecting the dashboard DB during development.
|
||||
RUN export DEBIAN_FRONTEND=noninteractive \
|
||||
&& apt-get update \
|
||||
&& apt-get install -y --no-install-recommends \
|
||||
build-essential \
|
||||
python3 \
|
||||
python-is-python3 \
|
||||
sqlite3 \
|
||||
&& apt-get clean \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
@@ -0,0 +1,70 @@
|
||||
# Dev Container (optional)
|
||||
|
||||
A ready-to-use, **opt-in** development environment for Claude Code Agent Monitor.
|
||||
It is used **only** when you explicitly choose it — it changes nothing about
|
||||
host-based development (`npm run dev` / `npm start` still work exactly as before).
|
||||
|
||||
## When to use it
|
||||
|
||||
Use it if you want a consistent, batteries-included toolchain without installing
|
||||
Node, build tools, or Python on your machine — or if you're on a GitHub Codespace.
|
||||
|
||||
## How to open it
|
||||
|
||||
- **VS Code:** install the *Dev Containers* extension, then run
|
||||
**"Dev Containers: Reopen in Container"** (Command Palette).
|
||||
- **GitHub Codespaces:** *Code → Create codespace on this branch*.
|
||||
|
||||
The first build runs `.devcontainer/post-create.sh`, which installs all workspace
|
||||
dependencies (`npm run setup`) and builds the MCP server (`npm run mcp:install`,
|
||||
`npm run mcp:build`).
|
||||
|
||||
## What's inside
|
||||
|
||||
| Component | Detail |
|
||||
| ---------------- | ------------------------------------------------------------------- |
|
||||
| Base image | `mcr.microsoft.com/devcontainers/javascript-node:22` (matches prod) |
|
||||
| Native toolchain | `build-essential` + `python3` so `better-sqlite3` compiles |
|
||||
| Python | `python3` / `python` for `statusline.py` and helper scripts |
|
||||
| sqlite3 CLI | inspect the dashboard DB during development |
|
||||
| Features | GitHub CLI, Docker-in-Docker (build/run the project's own Dockerfile) |
|
||||
| Forwarded ports | `4820` (server API + WebSocket), `5173` (Vite client) |
|
||||
| Editor | ESLint + Prettier (format on save), Vitest, Docker, YAML, Tailwind |
|
||||
|
||||
## Everyday commands
|
||||
|
||||
```bash
|
||||
npm run dev # server on :4820 + Vite client on :5173
|
||||
npm start # production-style server (serves client/dist)
|
||||
npm run test:server # node --test
|
||||
npm run test:client # vitest
|
||||
npm run test:mcp # MCP server tests
|
||||
npm run openapi:yaml # regenerate openapi.yaml from the live spec
|
||||
```
|
||||
|
||||
## Claude Code hooks are HOST-side (important — issue #193)
|
||||
|
||||
Claude Code runs on your **host**, so its hooks must point at a handler path that
|
||||
exists on the host. This container therefore:
|
||||
|
||||
- does **not** bind-mount `~/.claude`, and
|
||||
- does **not** install hooks — `scripts/install-hooks.js` **refuses to run inside
|
||||
a container** (it would write a container-internal handler path into your host
|
||||
settings and break every host hook with `MODULE_NOT_FOUND`).
|
||||
|
||||
Install hooks **on your host** instead:
|
||||
|
||||
```bash
|
||||
npm run install-hooks # on the HOST
|
||||
```
|
||||
|
||||
The host hook handler POSTs to `http://localhost:4820`, which this container
|
||||
forwards — so a host-installed hook reaches the containerized dashboard.
|
||||
|
||||
> Escape hatch: if you genuinely run Claude Code *inside* this same container,
|
||||
> set `CCAM_ALLOW_CONTAINER_HOOKS=1` before `npm run install-hooks`.
|
||||
|
||||
## Not supported in the container
|
||||
|
||||
Electron desktop builds (`npm run desktop:*`) need a host with a display and are
|
||||
host-only.
|
||||
@@ -0,0 +1,81 @@
|
||||
{
|
||||
// ─────────────────────────────────────────────────────────────────────────
|
||||
// Optional, opt-in dev environment for Claude Code Agent Monitor.
|
||||
// Used only when you choose "Dev Containers: Reopen in Container" (VS Code) or
|
||||
// open the repo in a GitHub Codespace. It changes nothing for host-based dev.
|
||||
//
|
||||
// Covers the full project: the Express server (4820), the React/Vite client
|
||||
// (5173), the MCP server, and the VS Code extension. The native `better-sqlite3`
|
||||
// addon builds here (build-essential + python3 are installed in the Dockerfile).
|
||||
//
|
||||
// NOTE (issue #193): Claude Code hooks are a HOST-side concern. This container
|
||||
// intentionally does NOT bind-mount ~/.claude and does NOT install hooks — the
|
||||
// installer refuses to run inside a container. Run `npm run install-hooks` on
|
||||
// your host so hooks POST to http://localhost:4820 (forwarded from here).
|
||||
// ─────────────────────────────────────────────────────────────────────────
|
||||
"name": "Claude Code Agent Monitor",
|
||||
"build": {
|
||||
"dockerfile": "Dockerfile",
|
||||
"context": ".."
|
||||
},
|
||||
|
||||
"features": {
|
||||
"ghcr.io/devcontainers/features/github-cli:1": {},
|
||||
// Lets you build/run the project's own production Dockerfile + docker-compose
|
||||
// from inside the dev container (e.g. to reproduce issue #193 deliberately).
|
||||
"ghcr.io/devcontainers/features/docker-in-docker:2": {}
|
||||
},
|
||||
|
||||
// Server (API + WebSocket) and the Vite client dev server. VS Code forwards
|
||||
// these from the container's localhost, so the secure loopback bind is fine.
|
||||
"forwardPorts": [4820, 5173],
|
||||
"portsAttributes": {
|
||||
"4820": {
|
||||
"label": "Dashboard server (API + WebSocket)",
|
||||
"onAutoForward": "notify"
|
||||
},
|
||||
"5173": {
|
||||
"label": "Vite dev client",
|
||||
"onAutoForward": "openBrowser"
|
||||
}
|
||||
},
|
||||
|
||||
// Install root + client + vscode-extension deps and build the MCP server.
|
||||
// Never installs Claude Code hooks (host-only — see note above).
|
||||
"postCreateCommand": "bash .devcontainer/post-create.sh",
|
||||
"waitFor": "postCreateCommand",
|
||||
|
||||
"remoteUser": "node",
|
||||
|
||||
// Dev defaults. NODE_ENV=development so `npm run dev` runs API-only with the
|
||||
// Vite client on 5173 (production mode would serve the prebuilt client/dist).
|
||||
"remoteEnv": {
|
||||
"NODE_ENV": "development"
|
||||
},
|
||||
|
||||
"customizations": {
|
||||
"vscode": {
|
||||
"extensions": [
|
||||
"dbaeumer.vscode-eslint",
|
||||
"esbenp.prettier-vscode",
|
||||
"vitest.explorer",
|
||||
"ms-azuretools.vscode-docker",
|
||||
"redhat.vscode-yaml",
|
||||
"yzhang.markdown-all-in-one",
|
||||
"ms-python.python",
|
||||
"bradlc.vscode-tailwindcss",
|
||||
"GitHub.vscode-pull-request-github"
|
||||
],
|
||||
"settings": {
|
||||
"editor.formatOnSave": true,
|
||||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||||
"editor.codeActionsOnSave": {
|
||||
"source.fixAll.eslint": "explicit"
|
||||
},
|
||||
"eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"],
|
||||
"files.eol": "\n",
|
||||
"terminal.integrated.defaultProfile.linux": "bash"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Executable
+41
@@ -0,0 +1,41 @@
|
||||
#!/usr/bin/env bash
|
||||
# Dev-container bootstrap. Installs all workspace dependencies and builds the
|
||||
# MCP server. Runs once, after the container is created.
|
||||
#
|
||||
# Deliberately does NOT install Claude Code hooks: hooks are a host-side concern
|
||||
# (issue #193) and `scripts/install-hooks.js` refuses to run inside a container.
|
||||
# @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
set -euo pipefail
|
||||
|
||||
echo "▶ Installing server + client + vscode-extension dependencies (npm run setup)…"
|
||||
npm run setup
|
||||
|
||||
echo "▶ Installing and building the MCP server…"
|
||||
npm run mcp:install
|
||||
npm run mcp:build
|
||||
|
||||
cat <<'EOF'
|
||||
|
||||
✅ Dev environment ready.
|
||||
|
||||
Develop:
|
||||
npm run dev # server on :4820 + Vite client on :5173
|
||||
npm start # production-style server (serves client/dist)
|
||||
|
||||
Test:
|
||||
npm run test:server # node --test
|
||||
npm run test:client # vitest
|
||||
npm run test:mcp # MCP server tests
|
||||
npm run mcp:typecheck # MCP type check
|
||||
|
||||
Docs:
|
||||
npm run openapi:yaml # regenerate openapi.yaml from the live spec
|
||||
|
||||
⚠ Claude Code hooks are HOST-side. Do NOT run `npm run install-hooks` in this
|
||||
container — it is refused on purpose (issue #193). Run it on your HOST so the
|
||||
hook handler path exists there and POSTs to http://localhost:4820 (forwarded
|
||||
from this container).
|
||||
|
||||
Electron desktop builds (npm run desktop:*) also need a host with a display
|
||||
and are not supported inside this container.
|
||||
EOF
|
||||
Reference in New Issue
Block a user