Claude Code Monitor (ccm)

Real-time monitoring dashboard for Claude Code sessions and subagents. Captures every hook event Claude Code emits during a session and renders a timeline of prompts, tool calls, subagent activity, and token usage.

How it works

Claude Code fires hooks at key moments in a session (SessionStart, PreToolUse, SubagentStart, etc.). ccm registers a small bash script as a handler for each of those events. The script appends every event as JSON into logs/{EventName}.json inside the current project. The dashboard reads those files, groups events by session_id, and displays them in a web UI.

Claude Code session ──hook──▶ hook_logger.sh ──▶ {project}/logs/*.json
                                                         │
                                                         ▼
                                             ccm dashboard (localhost:5173)

Session transcripts (.jsonl files with the full message history) live in Claude Code's global store at ~/.claude/projects/<encoded-path>/<session-id>.jsonl. ccm reads them via the transcript_path field embedded in each hook event to extract token usage and error states.

Install

Install the package. You have two options — either works with every command below.

npm install @yevlakhov/claude-code-monitor       # per-project (use via `ccm ...`)
npm install -g @yevlakhov/claude-code-monitor    # system-wide (use as plain `ccm ...`)

A global install is convenient if you use ccm across many projects — the ccm binary ends up on your $PATH and you don't need npx. ccm update will still work because each project's copy of hook_logger.sh is independent from the npm install location.

All commands below assume you installed globally and use ccm directly. If you installed locally, prepend npx to each command (ccm init, etc.).

Then register the hooks. There are two modes — pick one.

Local (per-project)

Hooks are installed into .claude/settings.json of the current project. Useful when you want the configuration committed to git and shared with your team.

ccm init

Creates:

• .claude/hook_logger.sh — the event logger script
• .claude/settings.json — with hook entries for every Claude Code event

Existing keys in settings.json (permissions, model, your own hooks) are preserved. Running init a second time is idempotent.

Global (all projects on this machine)

Hooks are installed into ~/.claude/settings.json once and fire across every project you open with Claude Code. You never have to run init per-project again.

ccm init --global

Creates:

• ~/.claude/hook_logger.sh
• ~/.claude/settings.json — with hook entries pointing at that script

Logs still go into each project's own logs/ directory because the script uses the $CLAUDE_PROJECT_DIR environment variable that Claude Code sets at runtime.

Both at the same time

You can have both. If a local .claude/settings.json defines hooks for an event, it overrides the global one for that event only — useful for projects where you want to disable monitoring or customize it.

Run the dashboard

From the root of any project that has a logs/ directory:

ccm

Open http://127.0.0.1:5173.

Options:

--port, -p <port>     Server port (default: 5173)
--host <host>         Server host (default: 127.0.0.1)
--logs-dir <path>     Path to logs directory (default: ./logs)
--data-dir <path>     Path to data directory (default: ./data)
--dev                 Development mode (verbose logging, port 3100)

Update

When a new version of the package ships with an updated hook_logger.sh, refresh the installed copies:

ccm update            # refreshes both local and global installs if present
ccm update --local    # only the local copy
ccm update --global   # only the global copy

Uninstall

Removes ccm's hook entries from settings.json, leaving other hooks and settings untouched. The hook_logger.sh file is left in place — delete it manually if you no longer need it.

ccm uninstall           # local
ccm uninstall --global  # global

Requirements

• Node.js 18+
• jq in $PATH (used by hook_logger.sh to parse hook payloads)
• Claude Code CLI installed and configured

Data layout

{project}/
├── .claude/                 # only in local install mode
│   ├── settings.json
│   └── hook_logger.sh
├── logs/                    # written by the hook, read by ccm
│   ├── SessionStart.json
│   ├── UserPromptSubmit.json
│   ├── PreToolUse.json
│   └── ...
└── data/                    # ccm's derived session history (auto-created)

It's recommended to add logs/ and data/ to your project's .gitignore.

License

MIT