Smartgift-AI/Claude-Code-Monitor
3
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(plugins): make CCAM installable straight from a Claude Code plugin

Browse Source 
Adds a root `ccam` plugin (`.claude-plugin/plugin.json`, `"source": "./"`) so
`/plugin marketplace add` + `/plugin install ccam@...` is enough on a machine
with nothing but Claude Code: no clone, no npm run setup, no manual npm start.

- scripts/plugin-bootstrap.js: SessionStart hook. Fast-path exit, Node >=22.5
  gate (node:sqlite), mkdir lock with stale reclaim, deps installed into
  ~/.claude/agent-dashboard/runtime/ (never the plugin cache), legacy
  checkout-hook cleanup (backed up), ~/.local/bin/ccam launcher, eager UI
  build so client routes like /run work immediately, detached server spawn.
- scripts/plugin-open.js, scripts/plugin-doctor.js: /ccam-open, /ccam-doctor.
- server/index.js: DASHBOARD_CLIENT_DIST override (plugin cache is read-only).
- mcp/build/ is committed (plugin MCP servers start before any bootstrap could
  build them) and kept honest by scripts/check-mcp-build.js (content hash,
  not mtime), enforced by pre-commit when mcp/src changes.
- plugins/ccam-dashboard/.mcp.json moved under plugins/ccam/ with a working
  ${CLAUDE_PLUGIN_ROOT} path (the old relative path never resolved from a
  marketplace-cached subdir).
- Docs: README, INSTALL, SETUP, ARCHITECTURE, CLAUDE.md, docs/PLUGINS.md,
  docs/MCP.md, docs/CLI.md, docs/HOOKS.md.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
nntrivi2001
2026-08-10 16:05:37 +07:00
parent 5a793e70cc
commit 8a82895c65
59 changed files with 5982 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PLUGINS.md
+126 -14
View File
@@ -1,6 +1,6 @@
# Claude Code Agent Monitor — Plugin Marketplace
Official Claude Code plugins for the Agent Monitor dashboard. **10 plugins** extend Claude Code with skills, agents, slash commands, hooks, and CLI tools for deep analytics, cost guardrails, productivity automation, developer tools, AI-powered insights, session forensics, workflow/fleet intelligence, reliability & SLOs, config & memory governance, and dashboard connectivity.
Official Claude Code plugins for the Agent Monitor dashboard. The **`ccam`** plugin _is_ the dashboard — hooks, server, `ccam` CLI and MCP tools, no checkout required. On top of it, **10 focused plugins** extend Claude Code with skills, agents, slash commands, hooks, and CLI tools for deep analytics, cost guardrails, productivity automation, developer tools, AI-powered insights, session forensics, workflow/fleet intelligence, reliability & SLOs, config & memory governance, and dashboard connectivity.
Every plugin is powered by the local Agent Monitor REST API at `http://localhost:4820`. They are read-only advisors unless a skill explicitly documents a mutating endpoint (and those preview + confirm before acting).
@@ -12,19 +12,43 @@ Every plugin is powered by the local Agent Monitor REST API at `http://localhost
claude plugin marketplace add Smartgift-AI/Claude-Code-Monitor
```
### Install a plugin
### Install the dashboard itself
```bash
claude plugin install ccam-analytics@smartgift-claude-code-monitor
claude plugin install ccam-cost-guard@smartgift-claude-code-monitor
claude plugin install ccam-productivity@smartgift-claude-code-monitor
claude plugin install ccam-devtools@smartgift-claude-code-monitor
claude plugin install ccam-insights@smartgift-claude-code-monitor
claude plugin install ccam-sessions@smartgift-claude-code-monitor
claude plugin install ccam-workflows@smartgift-claude-code-monitor
claude plugin install ccam-quality@smartgift-claude-code-monitor
claude plugin install ccam-config@smartgift-claude-code-monitor
claude plugin install ccam-dashboard@smartgift-claude-code-monitor
claude plugin install ccam@claude-code-agent-monitor-plugins
```
That is the whole install: no clone, no `npm run setup`, no `npm run install-hooks`, no manual `npm start`. See [The `ccam` plugin](#the-ccam-plugin) below for what it does on first session start.
### Or via the Smartgift skills marketplace
`ccam` is also listed as a standalone entry in
[`smartgift-claude-skills`](https://git.smartgift.io.vn/Smartgift-AI/smartgift-claude-skills)
— its `source` still points at this repo's `main` branch, so the two entries
install identically:
```bash
claude plugin marketplace add https://git.smartgift.io.vn/Smartgift-AI/smartgift-claude-skills.git
claude plugin install ccam@sg
```
Pick whichever marketplace you already have added; installing `ccam` from both
at once is redundant but harmless (Claude Code treats it as one plugin per
marketplace name, not per source).
### Install a focused plugin
```bash
claude plugin install ccam-analytics@claude-code-agent-monitor-plugins
claude plugin install ccam-cost-guard@claude-code-agent-monitor-plugins
claude plugin install ccam-productivity@claude-code-agent-monitor-plugins
claude plugin install ccam-devtools@claude-code-agent-monitor-plugins
claude plugin install ccam-insights@claude-code-agent-monitor-plugins
claude plugin install ccam-sessions@claude-code-agent-monitor-plugins
claude plugin install ccam-workflows@claude-code-agent-monitor-plugins
claude plugin install ccam-quality@claude-code-agent-monitor-plugins
claude plugin install ccam-config@claude-code-agent-monitor-plugins
claude plugin install ccam-dashboard@claude-code-agent-monitor-plugins
```
### Or install locally during development
@@ -37,11 +61,99 @@ claude --plugin-dir plugins/ccam-analytics
## Prerequisites
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
- Agent Monitor dashboard running at `http://localhost:4820` (see [SETUP.md](../SETUP.md))
- Hooks installed: `npm run setup` from the Agent Monitor project
- Node **>= 22.5** when installing via the `ccam` plugin. A plugin install has no
native `better-sqlite3`, so the server stores data through `node:sqlite`, which
landed in 22.5. The bootstrap refuses with one line on anything older instead
of letting the server crash. (A checkout install still works on Node >= 20.)
- The Agent Monitor dashboard reachable at `http://localhost:4820` — the `ccam`
plugin starts it for you; a checkout starts it with `npm start` (see
[SETUP.md](../SETUP.md))
Skills and commands are invoked as `/ccam-<plugin>:<name>`. Agents are dispatched automatically by Claude Code (or named explicitly).
## The `ccam` plugin
The marketplace's root entry (`"source": "./"`) is the entire repository, so
`server/`, `client/`, `mcp/`, `scripts/` and `bin/ccam.js` all land under
`${CLAUDE_PLUGIN_ROOT}` when Claude Code caches it. That is what makes a
checkout unnecessary.
### What it installs
| Component | Where it comes from |
|---|---|
| The eight event hooks | inline `hooks` in `.claude-plugin/plugin.json`, each running `scripts/hook-handler.js` |
| The dashboard server | started detached by the bootstrap, from the plugin cache |
| The `ccam` CLI | a launcher written to `~/.local/bin/ccam` |
| The MCP tools | `plugins/ccam/.mcp.json`, pointing at the committed `mcp/build/index.js` |
| The dashboard UI (`/run` and every other client route) | built into the runtime dir by the bootstrap, so it works the moment `claude` starts |
| `/ccam-doctor`, `/ccam-update`, `/ccam-open` | `plugins/ccam/commands/` |
Because the plugin ships the hooks itself, `npm run install-hooks` is not needed
for plugin users — and must not be run alongside it. Events carry no id, so two
handlers mean every token and cost figure is counted twice. The bootstrap
removes the older checkout-installed entries automatically (backing
`~/.claude/settings.json` up as `settings.json.ccam-bak` first), and
`/ccam-doctor` reports the state.
### First session start
`scripts/plugin-bootstrap.js` runs from `SessionStart`. It returns within
milliseconds — the real work happens in a detached worker, so a session never
waits on an install:
1. **Fast path** — recorded state matches this plugin build and a server is live → exit.
2. **Node gate** — refuse below 22.5 with one line (see Prerequisites).
3. **Lock** — atomic `mkdir` lock holding the PID; reclaimed when the owner is dead or the lock is older than 10 minutes, so two sessions cannot race the install or spawn two servers.
4. **Install** — `npm install --omit=dev --ignore-scripts` into the runtime dir (never into the plugin cache, which is garbage-collected and replaced on every update). `--ignore-scripts` keeps the root `postinstall` from pulling the whole Vite client toolchain.
5. **Legacy hook cleanup** — see above.
6. **CLI** — write the `~/.local/bin/ccam` launcher, never clobbering a `ccam` the bootstrap did not write.
7. **UI build** — `client/` is copied into the runtime dir and built there (`npm install && npm run build`), landing in `runtime/client-dist` — the same directory the server serves from. Skipped when a bundle for the current version already exists; a failure here does not fail the bootstrap (API and MCP still work, and `/ccam-open` can retry) but does mean `/run` 404s until it's fixed.
8. **Server** — spawn `server/index.js` detached, with `NODE_PATH` at the runtime `node_modules` and `DASHBOARD_CLIENT_DIST` at the runtime `client-dist`.
9. **Record state** — `runtime/state.json`.
The first run takes a few minutes — most of it is the UI build, which is what
makes client-only routes (`http://localhost:4820/run`, and every other page)
work the moment `claude` starts, with no manual `/ccam-open` step. Progress
goes to `~/.claude/agent-dashboard/runtime/bootstrap.log`; `npm run build`'s own
output goes to `client-build.log` next to it; the server's own output goes to
`server.log`.
### Commands
| Command | Does |
|---|---|
| `/ccam-doctor` | Node version, bootstrap state, runtime deps, server liveness, duplicate hooks, CLI launcher + PATH, MCP build freshness, UI bundle |
| `/ccam-update` | Reinstall dependencies and restart the server against the current plugin version (`plugin-bootstrap.js --force`) |
| `/ccam-open` | Build the UI bundle if missing, then print the dashboard URL |
### Where things live
| Thing | Location | Survives a plugin update |
|---|---|---|
| SQLite DB, transcripts | `~/.claude/agent-dashboard/` | yes |
| `node_modules`, `client-dist`, logs, lock, `state.json` | `~/.claude/agent-dashboard/runtime/` | yes (re-verified on every session start) |
| Source, hooks, `mcp/build` | the plugin cache version directory | no — re-bootstrapped |
The bootstrap deliberately does **not** set `DASHBOARD_DATA_DIR`: leaving the
default keeps a plugin-run server and a developer's `npm run dev` server on one
data directory, where `ingestGroupKey` already deduplicates hook ingest to a
single port.
### Uninstalling
`claude plugin uninstall ccam@claude-code-agent-monitor-plugins` removes the hooks
and the cached source. It does not touch the state the plugin created outside
the cache — remove those by hand if you want a clean machine:
```bash
kill "$(node -e 'console.log(JSON.parse(require("fs").readFileSync(require("os").homedir()+"/.claude/.agent-dashboard.json","utf8")).servers[0].pid)')"
rm -rf ~/.claude/agent-dashboard/runtime # deps, UI bundle, logs, state
rm -f ~/.local/bin/ccam # the CLI launcher
# ~/.claude/agent-dashboard/ still holds the database — delete it only if you
# want the recorded history gone too.
```
## Available Plugins
### 1. `ccam-analytics` — Analytics & Monitoring