claudalytics

---

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/[email protected]

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