Installation
1. Clone and run the port preflight check
git clone https://github.com/jimkeecn/Claudalytics.git
cd Claudalytics
claude
In Claude Code, run:
/preflight-check
This verifies that all required host ports are free before you start Docker. The hooks server and OTel exporter are tightly coupled to these port numbers — if any port is in use, free it (the skill prints the process and the terminate command). Do not remap Claudalytics' ports.
Required host ports
| Port | Purpose |
|---|
| 13000 | Grafana UI |
| 4317 | OTel collector (gRPC receiver) |
| 4318 | OTel collector (HTTP receiver) |
| 4319 | Hooks server |
| 8123 | ClickHouse HTTP |
| 9000 | ClickHouse native TCP |
| 13133 | OTel collector health endpoint |
2. Start the analytics stack
cd docker-stack
docker compose up -d --build
Wait ~30 seconds. Then go back to the repo root:
cd ..
Run /validate-infra to verify all 4 containers, tables, and materialized views are healthy.
3. Install the plugin
Add the Claudalytics marketplace and install the plugin in any project:
/plugin marketplace add jimkeecn/Claudalytics
/plugin install claudalytics@claudalytics
Pin to a specific release:
/plugin marketplace add jimkeecn/Claudalytics@v1.1.0
Local development — if you're iterating on the plugin code itself, install directly from your local checkout instead:
/install-plugin /full/path/to/Claudalytics/plugin
4. Initialize
/init-claudalytics
Follow the prompts — confirm your project name, and the skill configures everything.
5. Restart Claude Code and open dashboards
Restart your session for telemetry to take effect, then open:
http://localhost:13000 (admin / admin)
Navigate to: Home > Dashboards > Claudalytics > Claudalytics - OTel Overview
That's it. Data starts flowing immediately.
Features
Session Timeline
Every action in a single view — prompts, API calls, tool executions, subagent dispatches, permission requests, compaction events — merged from OTel and hooks into one chronological timeline.
Cost & Token Analytics
Track spending across sessions, models, and projects. See cost per 1K output tokens, token usage over time, cache hit rates, and identify your most expensive sessions and prompts.
Skill & Subagent Tracking
Monitor which skills and subagents Claude uses, their success rates, duration, and model selection. Spot inefficiencies — high re-invocation rates mean the first attempt likely failed.
Credential Exposure Detection
Automatically detects when Claude reads sensitive files — .env, AWS credentials, SSH keys, certificates, database configs — across 38 patterns in 13 categories. No configuration needed. Powered by a ClickHouse materialized view that pattern-matches in real-time.
File Mutation Tracking
Every file Claude edits, writes, or deletes is tracked with action type, file extension, and directory. See which files get modified most and spot unexpected deletions.
Blocked Action Detection
Tool calls that were denied or cancelled are automatically detected by tracking PreToolUse events that never received a PostToolUse response. Useful for auditing what Claude tried to do but was stopped from doing.
Tool Latency & Slow URLs
Identify performance bottlenecks — which tools are slowest at p50/p95, and which URLs take the longest to fetch.
37 Dashboard Panels
JuliusBrussee