English | 中文 | 日本語 | Français | Deutsch

Claudalytics

Local analytics dashboard for Claude Code

Track costs, tokens, tool usage, and session activity across all your projects. Zero cloud dependencies. Your data stays on your machine.

Installation · Features · Updating · Team Use · Changelog

---

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

Category	Panels
KPIs	Sessions, events, cost/1K tokens, total tokens, per-user cost
Cost	Cost over time, top expensive sessions/prompts, cost per active minute, commits vs cost
Tools	Tool usage, model usage, accept/reject rates, cache hit-rate
Latency	API latency percentiles, tool execution latency, slowest WebFetch URLs
Timeline	Full session event history (2000 row limit)
Workflow	Skills used, websites visited, MCP server calls, subagent usage
Files	Most modified files with action breakdown
Code	Lines of code per user, prompt length distribution
Security	Blocked actions, blocked rate over time, credential exposures
Ops	Config changes, compaction events/frequency, recent errors
Feedback	Survey funnel

---

Updating

See CHANGELOG.md for the list of changes in each release.

cd Claudalytics
git pull
cd docker-stack
docker compose up -d --build

Additive schema changes (new tables, new materialized views) are applied automatically by the hooks-server on startup. If a release includes destructive schema changes (column type changes, re-partitioning), run /migrate-db from the Claudalytics project — it will walk you through a safe, side-by-side migration with backup prompts.

Hook scripts and hook declarations now ship inside the plugin, so a git pull + plugin reload is enough to pick up hook changes. If you are upgrading from 1.0.0, re-run /init-claudalytics once in each project — it will sweep the legacy per-project hook files out of .claude/hooks/ and strip the stale hook entries from .claude/settings.local.json. OTel env vars and your project name are preserved.

---

Team Use

This project is designed for individual developers. To adapt it for a team:

1. Deploy to a shared server — the Docker stack works on any server. Each developer points their OTel endpoint and the HOOKS_URL inside plugin/hooks/forward-hook.sh to the server address instead of localhost.
2. Add a team name attribute — include team.name in OTEL_RESOURCE_ATTRIBUTES alongside project.name.
3. Forward team.name from the hook script — extend plugin/hooks/forward-hook.sh to append &teamName=<TEAM> to the hooks URL, and update the hooks server to record it.
4. Update ClickHouse tables — add a team_name column to the target tables and materialized views.
5. Update Grafana — add a Team dropdown variable and filter all panels by it.

Before deploying to a server, you must secure the stack:

• Set a ClickHouse password (the default config has no authentication)
• Change the Grafana admin password
• Change host port bindings in docker-compose.yaml from 127.0.0.1:PORT:PORT to PORT:PORT (or a specific interface) so team members can reach the stack — the default shipped bindings are localhost-only for individual-developer safety on public WiFi
• Restrict port access with a firewall — only expose ports 4317 (OTel gRPC), 4319 (hooks), and 13000 (Grafana)
• Add TLS for encrypted transport

The Docker Compose file works on a cloud server as-is — but without these security steps, your telemetry data is exposed to anyone who can reach the ports.

---

Built with Claude Code

If this project helps your workflow, give it a star!

FAQ

My ports are available from /preflight-check but docker build still has port issue.

If you have winNAT is running. please run the following commands in PowerShell (Run as administrator)

1. Step 1 - stop WinNAT (Release dynamic exclusions or reserved ports) net stop winnat

2. Step 2 - start it back (re-allocates from a different offset, usually avoids 4318) net start winnat

Then re-run /preflight-check and retry docker compose up -d --build