Claude-Code-Monitor/docs/PLUGINS.md

Claude Code Agent Monitor — Plugin Marketplace

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).

Quick Start

Add the marketplace

claude plugin marketplace add Smartgift-AI/Claude-Code-Monitor

Install the dashboard itself

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 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 — its source still points at this repo's main branch, so the two entries install identically:

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

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

# From the repo root, test a plugin locally
claude --plugin-dir plugins/ccam-analytics

Prerequisites

• Claude Code installed and authenticated
• 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)

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. claude plugin install writes the plugin's own hook entries into ~/.claude/settings.json too (${CLAUDE_PLUGIN_ROOT} resolved to the actual cache path) — confirmed against a real install — so those entries also contain hook-handler.js, same as a leftover checkout install. The bootstrap tells them apart by whether the command resolves under ~/.claude/plugins/cache/: only genuine checkout paths are removed (backing ~/.claude/settings.json up as settings.json.ccam-bak first), never the plugin's own. /ccam-doctor reports the state using the same check.

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:

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

Deep analytics on sessions, token usage, costs, cache efficiency, model mix, and productivity.

Skill	Command	Purpose
Session Report	/ccam-analytics:session-report	Per-model tokens (input/output/cache_read/cache_write + baselines), cost, agent hierarchy, tool activity, timeline
Cost Breakdown	/ccam-analytics:cost-breakdown	Per-model cost via the pricing engine, daily trends, cache efficiency, optimization opportunities
Usage Trends	/ccam-analytics:usage-trends	365-day session/event trends, token volume, tool rankings, model distribution, event-type ratios
Productivity Score	/ccam-analytics:productivity-score	Weighted scorecard: completion, token efficiency, tool effectiveness, velocity, cost efficiency
Cache Efficiency	/ccam-analytics:cache-efficiency	Cache hit rate, write-vs-read reuse, sessions with poor cache reuse
Model Mix	/ccam-analytics:model-mix	Share of tokens and cost per model family; expensive models doing cheap work

Commands: /ccam-analytics:cost-today · /ccam-analytics:top-spenders · /ccam-analytics:burn-rate

Agents: analytics-advisor (full advisor incl. workflow intelligence) · token-economist (token economics & reduction tactics)

Hooks: Logs Stop / SubagentStop events. CLI: ccam-stats — terminal stats (sessions, cost, tokens).

---

2. ccam-cost-guard — Budget Guardrails

Spend limits, forecasting, cost alerts, and model-routing savings.

Skill	Command	Purpose
Budget Set	/ccam-cost-guard:budget-set	Define a budget and (optionally) arm a token_threshold alert rule; explains the $→token conversion
Spend Forecast	/ccam-cost-guard:spend-forecast	Project week/month-end spend from the daily trend (moving average × remaining days)
Cost Alert	/ccam-cost-guard:cost-alert	Review alert rules and fired alerts; explain exactly what tripped
Model Savings	/ccam-cost-guard:model-savings	Estimate $ saved by routing eligible work to a cheaper model family
Daily Budget Check	/ccam-cost-guard:daily-budget-check	Today's spend vs a daily budget, pace vs target, projected overage

Commands: /ccam-cost-guard:budget · /ccam-cost-guard:forecast · /ccam-cost-guard:overspend

Agent: budget-sentinel — watches spend vs target, projects month-end, recommends cuts. Hooks: fail-safe Stop event POST so budget tracking sees session ends.

---

3. ccam-productivity — Productivity & Workflows

Standups, weekly/monthly reviews, sprint tracking, focus analysis, and workflow optimization.

Skill	Command	Purpose
Daily Standup	/ccam-productivity:daily-standup	Standup from recent sessions — work by project (cwd), costs, tools, errors, velocity
Weekly Report	/ccam-productivity:weekly-report	Daily session/event trends, per-session costs, token volumes, tool top-20, completion rates
Sprint Summary	/ccam-productivity:sprint-summary	Per-project + per-model costs, token efficiency, subagent effectiveness, retrospective data
Workflow Optimizer	/ccam-productivity:workflow-optimizer	Tool-flow transitions, effectiveness, delegation, error propagation, concurrency, compaction
Monthly Review	/ccam-productivity:monthly-review	Month-over-month sessions, cost, tokens, completion, top projects, notable shifts
Time of Day	/ccam-productivity:time-of-day	Activity/productivity bucketed by hour and day-of-week; peak vs low-output windows

Commands: /ccam-productivity:standup · /ccam-productivity:whats-next · /ccam-productivity:focus-report

Agents: productivity-coach (work-pattern review) · focus-analyst (deep-work / focus blocks). Hooks: session start/end timing.

---

4. ccam-devtools — Developer Tools

Debugging, data-integrity inspection, event tracing, transcript search, diagnostics, export, and health checks.

Skill	Command	Purpose
Session Debug	/ccam-devtools:session-debug	Full event chain, agent hierarchy, token usage with baselines, workflow intelligence
Hook Diagnostics	/ccam-devtools:hook-diagnostics	Hook install, connectivity, handler validation, event delivery, data freshness
Data Export	/ccam-devtools:data-export	Export sessions/events/analytics/costs as JSON/CSV/Markdown
Health Check	/ccam-devtools:health-check	API, SQLite (WAL), WebSocket, endpoints, hooks, disk, data freshness
Event Trace	/ccam-devtools:event-trace	Ordered event timeline for a session, highlighting gaps/failures
Transcript Grep	/ccam-devtools:transcript-grep	Search a session transcript for a string/pattern with context

Commands: /ccam-devtools:doctor · /ccam-devtools:export · /ccam-devtools:tail-events

Agents: issue-triager (cross-component triage) · db-inspector (data-integrity inspection). CLI: ccam-doctor, ccam-export.

---

5. ccam-insights — AI-Powered Insights

Pattern detection, anomaly alerting, forecasting, regression watch, benchmarking, optimization, and comparison.

Skill	Command	Purpose
Pattern Detect	/ccam-insights:pattern-detect	Tool-flow transitions, recurring sequences, agent co-occurrence, delegation habits
Anomaly Alert	/ccam-insights:anomaly-alert	Cost/token/event-ratio/complexity outliers (statistical)
Optimization Suggest	/ccam-insights:optimization-suggest	Model downgrades, cache optimization, compaction reduction, tool reliability
Session Compare	/ccam-insights:session-compare	Side-by-side tokens, costs, complexity, tool-flow, metadata deltas
Regression Watch	/ccam-insights:regression-watch	Rising error rate, falling cache hits, growing compaction, climbing cost/session
Benchmark	/ccam-insights:benchmark	Benchmark a session vs the rolling average; show percentile

Commands: /ccam-insights:insights · /ccam-insights:compare · /ccam-insights:anomalies

Agents: insights-advisor (strategic analysis) · trend-forecaster (near-future cost/usage projection).

---

6. ccam-sessions — Session Forensics

Search, timeline, transcript replay, per-project rollups, and lifecycle management.

Skill	Command	Purpose
Session Search	/ccam-sessions:session-search	Find sessions by project/model/status/date; rank by cost or recency
Session Timeline	/ccam-sessions:session-timeline	Ordered timeline of one session's events with durations and tool names
Transcript Replay	/ccam-sessions:transcript-replay	Walk a transcript turn-by-turn, summarizing each message
CWD Rollup	/ccam-sessions:cwd-rollup	Roll up sessions by working directory: counts, cost, tokens, last-active
Session Cleanup	/ccam-sessions:session-cleanup	Identify stale/empty sessions; preview before the cleanup endpoint deletes (confirm required)

Commands: /ccam-sessions:find-session · /ccam-sessions:replay · /ccam-sessions:recent

Agent: session-investigator — end-to-end investigation of a single session.

---

7. ccam-workflows — Orchestration & Fleet Intelligence

Multi-agent structure analysis using the workflow intelligence API and Workflow-tool run journals.

Skill	Command	Purpose
DAG Map	/ccam-workflows:dag-map	Orchestration DAG: parent→child subagent edges, depth, fan-out
Delegation Audit	/ccam-workflows:delegation-audit	Model delegation + subagent effectiveness; wasted delegations
Concurrency Report	/ccam-workflows:concurrency-report	Concurrency lanes, parallelism, serialization bottlenecks
Error Propagation	/ccam-workflows:error-propagation	Trace failures by depth and how they cascade across subagents
Fleet Runs	/ccam-workflows:fleet-runs	Summarize Workflow-tool fleet runs (no-hook fleets ingested from run journals)

Commands: /ccam-workflows:workflow · /ccam-workflows:dag · /ccam-workflows:runs

Agent: orchestration-analyst — analyzes the 11 workflow datasets + fleet runs.

---

8. ccam-quality — Reliability & SLOs

Error monitoring, hook-delivery health, SLO tracking with error budgets, and regression alerts.

Skill	Command	Purpose
Error Scan	/ccam-quality:error-scan	Scan events for APIError + failure signals; group by tool/model; rank by frequency
API Error Report	/ccam-quality:api-error-report	APIError detail: counts over time, affected sessions/models, likely causes
Hook Failure Audit	/ccam-quality:hook-failure-audit	PreToolUse/PostToolUse balance, missing terminators, stale ingestion
SLO Check	/ccam-quality:slo-check	Completion rate, tool success rate, error rate; error budget remaining
Regression Alert	/ccam-quality:regression-alert	Compare this period's error/failure rates to the prior period; optional alert rule

Commands: /ccam-quality:errors · /ccam-quality:slo · /ccam-quality:health

Agent: reliability-engineer — treats Claude Code usage as a service with an error budget.

---

9. ccam-config — Config & Memory Governance

Audit your Claude Code configuration and curate the file-based memory store via the Config Explorer API.

Skill	Command	Purpose
Config Audit	/ccam-config:config-audit	Counts per surface (user vs project), duplicate skills/agents, shell-running hooks
Memory Review	/ccam-config:memory-review	CLAUDE.md + per-project auto-memory files grouped by project; flag stale/oversized facts
Skill Inventory	/ccam-config:skill-inventory	Installed skills + contributing plugins; overlap with your own skills
MCP Audit	/ccam-config:mcp-audit	MCP servers (user + project): transport, command/args/env names, source file
Hook Inventory	/ccam-config:hook-inventory	Hooks across settings + the hooks scripts dir; flag network/arbitrary-command hooks

Commands: /ccam-config:audit-config · /ccam-config:memory · /ccam-config:inventory

Agent: config-auditor — audits config sprawl, duplication, risky hooks, and stale memory.

Memory Review can also edit the per-project memory store: auto-memory files are mutable via PUT/DELETE /api/cc-config/file with { scope: "auto-memory", type: "auto-memory", project, name } (always backed up first).

---

10. ccam-dashboard — Dashboard Connector

Direct MCP integration, quick status, live watch, and endpoint probing.

Skill	Command	Purpose
Dashboard Status	/ccam-dashboard:dashboard-status	Health: API connectivity, session/event counts, hook status, data freshness
Quick Stats	/ccam-dashboard:quick-stats	One-line metrics: active sessions, total cost, events, top tool, cache efficiency
Live Watch	/ccam-dashboard:live-watch	Poll a few times to show live deltas (active sessions/agents, events, ws connections)
Endpoint Probe	/ccam-dashboard:endpoint-probe	Probe each major API route and report reachability/shape

Commands: /ccam-dashboard:status · /ccam-dashboard:ping · /ccam-dashboard:open-dashboard

Agent: dashboard-operator — verifies the dashboard is up and guides start/restart/import. MCP Server: direct tool access to the Agent Monitor API. Settings: default agent model.

---

Data Model Reference

These plugins query the Agent Monitor API at http://localhost:4820. Key data shapes:

Token Tracking

• 4 token types: input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens
• 4 baselines: baseline_input, baseline_output, baseline_cache_read, baseline_cache_write (preserve pre-compaction tokens)
• Effective total = current + baseline (the /api/analytics totals are pre-summed)

Cost Calculation

• Formula: (tokens / 1,000,000) × rate_per_mtok for each token type
• Model matching: longest model_pattern wins (e.g., claude-sonnet-4-5% beats claude-sonnet-4%)
• Pre-seeded rates for Opus, Sonnet, Haiku families

Session Metadata (JSON)

• thinking_blocks: count of extended thinking blocks
• turn_count: number of conversation turns
• total_turn_duration_ms: cumulative turn processing time
• usage_extras: { service_tiers[], speeds[], inference_geos[] }

Event Types

PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, Notification, Compaction, APIError, TurnDuration, ToolError, Interrupted

Workflow Intelligence API (/api/workflows/{sessionId})

11 datasets: stats, orchestration (DAG), toolFlow (transitions), effectiveness (subagent success), patterns (recurring sequences), modelDelegation, errorPropagation (by depth), concurrency (lanes), complexity (score), compaction (impact), cooccurrence (agent pairs)

Alert Rules (/api/alerts/rules)

Rule types: token_threshold ({ total_tokens } — the spend-relevant guardrail), event_pattern, inactivity, status_duration.

Config Explorer (/api/cc-config/*)

Read every Claude Code surface (skills, agents, commands, output-styles, plugins, marketplaces, mcp, hooks, settings, keybindings, statusline, memory). memory includes the per-project file-based store with scope: "auto-memory" (carrying project, name, isIndex, frontmatter); those files plus CLAUDE.md are mutable via PUT/DELETE /api/cc-config/file with always-on timestamped backups.

Plugin Development

To create your own plugins for the Agent Monitor, see the Claude Code plugin documentation.

Plugin structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: name (== dir name), description, version
├── skills/
│   └── my-skill/
│       └── SKILL.md         # Skill (description-only frontmatter; uses $ARGUMENTS)
├── agents/
│   └── my-agent.md          # Agent (name == filename, model, tools, instructions)
├── commands/
│   └── my-command.md        # Slash command (description, optional argument-hint)
├── hooks/
│   └── hooks.json           # Event hooks (fail-safe, non-blocking)
├── bin/
│   └── my-cli-tool          # CLI scripts (added to PATH)
├── .mcp.json                # MCP server configuration
└── settings.json            # Plugin settings

Structure is validated by server/__tests__/plugins-marketplace.test.js, which enforces the marketplace↔directory bijection, plugin.json shape, name/dir agreement, and required frontmatter on every agent / skill / command.

Testing locally

claude --plugin-dir /path/to/my-plugin   # then use /my-plugin:my-skill some args

Troubleshooting

Dashboard not reachable

cd /path/to/Claude-Code-Agent-Monitor
npm start        # or: npm run dev

Hooks not installed

cd /path/to/Claude-Code-Agent-Monitor
npm run setup

Plugin not found

claude plugin marketplace list
claude plugin marketplace add Smartgift-AI/Claude-Code-Monitor

License

Internal SmartGift build — all rights reserved.