https://github.com/spences10/claude-code-analytics
๐ Local-first analytics and statusline for Claude Code - capture sessions, tool calls, costs, and performance into SQLite for fast, actionable insights.
https://github.com/spences10/claude-code-analytics
analytics claude claude-code cli sqlite statusline
Last synced: about 1 month ago
JSON representation
๐ Local-first analytics and statusline for Claude Code - capture sessions, tool calls, costs, and performance into SQLite for fast, actionable insights.
- Host: GitHub
- URL: https://github.com/spences10/claude-code-analytics
- Owner: spences10
- License: mit
- Created: 2025-08-30T19:39:36.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-04-10T05:03:36.000Z (2 months ago)
- Last Synced: 2026-04-10T07:14:56.045Z (2 months ago)
- Topics: analytics, claude, claude-code, cli, sqlite, statusline
- Language: TypeScript
- Homepage:
- Size: 243 KB
- Stars: 10
- Watchers: 0
- Forks: 3
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Claude Code Analytics
This is Claude Code Analytics! It uses ClaudeCode statusline and
Claude Code hooks to store information about your Claude Code sessions
in a local SQLite database.
## Hook-Driven Architecture
**Why use hooks instead of just reading statusline data?**
The statusline updates every 300ms, so we _could_ do all analytics
calculations in real-time. But this marvellous monstrosity explores a
different approach:
- **Hooks do heavy lifting** during natural Claude Code pauses
(PostToolUse, UserPromptSubmit)
- **Statusline stays responsive** with sub-millisecond lookups of
pre-computed data
- **True zero-impact analytics** - expensive queries happen when
Claude Code is already waiting
- **Separation of concerns** - data processing vs. display logic
The result? A statusline that can show complex productivity insights,
cache efficiency metrics, and sparkline visualizations without ever
slowing down your workflow.
_Sometimes the best solution is the most over-engineered one!_ ๐
There's a CLI for reports and analytics, for example Cost Analytics...
```ascii
โ How many days to analyze?
โ 7
Cost Trend (Last 7 Days)
$21.47 โค โญโโโโโโโโโโโโโโโโโฎ
$19.55 โค โญโโฏ โฐโโโฎ
$17.63 โค โญโโฏ โฐโโโฎ
$15.71 โค โญโโฏ โฐโโโฎ
$13.78 โค โญโโโฏ โฐโโโโฎ
$11.86 โค โญโโฏ โฐโ
$9.94 โค โญโโโฏ
$8.02 โค โญโโโโโโโโโโฏ
$6.10 โผโโโโฏ
Total Cost โ$68.11
Total Sessions โ87
Avg Cost/Session โ$0.78
Daily Average โ$9.73
```
Activity patterns...
```ascii
โ How many days to analyze?
โ 7
Activity Heatmap (Last 7 Days)
Total: 88 sessions across 5 days
Peak: 13 sessions on 2025-08-27 at 20:00
00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23
Sun โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ
Mon โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ
Tue โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ
Wed โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ
Thu โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ
Fri โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ
Sat โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ โโ
โโ High (9+) โโ Medium (5-9) โโ Low (0-5)
Top Activity Hours:
1. Wed 20:00 (2025-08-27): 13 sessions
2. Thu 09:00 (2025-08-28): 9 sessions
3. Tue 10:00 (2025-08-26): 8 sessions
4. Thu 18:00 (2025-08-28): 7 sessions
5. Thu 16:00 (2025-08-28): 6 sessions
```
## Installation
Install globally with your preferred package manager:
```bash
# npm
npm install -g claude-code-analytics
# pnpm
pnpm add -g claude-code-analytics
# bun
bun add -g claude-code-analytics
# volta
volta install claude-code-analytics
```
## First Run (Onboarding)
Run interactive setup to install the statusline and hooks:
```bash
claude-code-analytics config
```
This lets you:
- Install the statusline and/or lightweight hooks in
`~/.claude/settings.json`.
- Enable or disable local data collection in
`~/.claude/claude-code-analytics.json`.
Note: Running `claude-code-analytics` with no arguments is intended
for Claude Code statusline integration and isnโt useful on its own in
a terminal. Use subcommands like `config`, `analytics`, or
`quick-stats`.
Tip: To confirm the CLI is available on your PATH, try:
```bash
claude-code-analytics -h
```
This should print the help text.
## Commands
- `claude-code-analytics config`: Interactive configuration
(statusline, hooks, settings).
- `claude-code-analytics analytics`: Interactive analytics dashboard
(tables and ASCII charts).
- `claude-code-analytics quick-stats`: One-shot 7โday summary.
- `claude-code-analytics install | uninstall`: Install/remove
statusline and hooks without prompts.
- `claude-code-analytics --help | --version`: Show help/version.
Default behaviour: When invoked without arguments (or by Claude Code),
the binary runs in statusline mode.
## Usage
- Use Claude Code normally. The statusline and hooks record session
metadata locally for analytics.
- View analytics anytime with `claude-code-analytics analytics` or a
quick summary with `claude-code-analytics quick-stats`.
## Data & Privacy
- Database: `~/.claude/claude-code-analytics.db` (SQLite, local-only).
- Config: `~/.claude/claude-code-analytics.json`.
- Claude integration: `~/.claude/settings.json` (non-destructive; only
our entries).
- No telemetry or network calls.
To disable collection, set `data_collection: false` in
`~/.claude/claude-code-analytics.json`.
### PerโProject Configuration
You can override settings per project with a local config file at:
- `/.claude/claude-code-analytics.json`
Example (this repo):
`claude-code-analytics/.claude/claude-code-analytics.json`
Project config deepโmerges over the global config. Useful for:
- Disabling collection in a specific repo
- Customizing the statusline layout per project
Example:
```json
{
"data_collection": true,
"display": {
"layout": [
["git", "model"],
["cost", "duration", "lines_changed"]
]
}
}
```
## Theming & Display
You can customize the statuslineโs look globally or perโproject.
- Config files:
- Global: `~/.claude/claude-code-analytics.json`
- Project: `/.claude/claude-code-analytics.json` (overrides
global)
Display keys
- `display.theme`: `minimal` (default), `ascii`, or `emoji`
- `display.icons`: enable/disable icons globally (default: true)
- `display.powerline`: boolean (autoโdetect when omitted)
- `display.icon_overrides`: map of symbol name โ string
- `display.layout`: string[][] to control segment order and lines
Examples
Minimal (default) with Powerline forced:
```json
{
"display": {
"theme": "minimal",
"powerline": true
}
}
```
Pure ASCII:
```json
{
"display": {
"theme": "ascii",
"icons": true
}
}
```
Emoji (optโin) with simple overrides:
```json
{
"display": {
"theme": "emoji",
"icon_overrides": {
"branch": " ๎ ",
"ahead": "โ",
"behind": "โ"
}
}
}
```
Notes
- No environment variables are used for theming. Configure via JSON
only.
- Project config deepโmerges over global config.
## Terminal Visuals
The CLI uses color and layout for readability without relying on heavy
emoji.
- `chalk` for subtle, meaningful color (headings, axes, legends)
- `cli-table3` for clean, aligned tables
- `asciichart` for compact line charts with scaled yโaxis labels
- Powerline glyphs when the terminal supports them (autoโdetected)
Upcoming improvements
- Color cues for session rank, cache efficiency, and tool success
- Theme presets that bundle layout + color choices (e.g., Minimal,
Dense)
- Optional ASCIIโonly mode across all views for maximal portability
## Statusline Segments
Add segments to `display.layout` (each inner array is a row).
Available segments:
- Core: `git`, `model`, `cost`, `duration`, `lines_changed`,
`tool_performance`, `cache_efficiency`, `working_directory`
- Gauges: `tool_gauge` (tool success %), `cache_gauge` (cache
efficiency %), `context_gauge` (context tokens vs limit)
- Bars: `lines_bar` (added vs removed)
- Sparklines: `cost_sparkline` (recent session costs),
`cache_reads_sparkline` (cache read tokens per session)
- Activity: `activity_strip` (last 24h hourly activity), `streak_bar`
(last 7 days usage)
- Mix: `model_mix` (top 3 models compact bands)
- Ambient: `ambient_wave`, `ambient_bounce`, `ambient_marquee`,
`ambient_spinner`, `ambient_twinkle`, `ambient_wave_sine`
Segment options (under `display`)
- `colors`: boolean โ enable color cues (default: true)
- `bar_width`: number โ width for gauges/bars (default: 10โ12)
- `sparkline`: `{ width, height, points }` โ size and history length
for sparklines
- `context`: `{ token_limit, mode, recent_n }` โ context gauge
configuration
- `token_limit`: default `200000` (200k tokens)
- `mode`: `latest` | `session_total` | `recent_n` (default `latest`)
- `recent_n`: number of assistant turns when `mode = recent_n`
Example multiโrow layout
```json
{
"display": {
"theme": "minimal",
"colors": true,
"bar_width": 12,
"sparkline": { "width": 20, "height": 2, "points": 20 },
"context": {
"token_limit": 200000,
"mode": "latest",
"recent_n": 5
},
"layout": [
["working_directory"],
["git", "model"],
["cost", "duration"],
["tool_gauge", "cache_gauge"],
["context_gauge"],
["activity_strip"],
["streak_bar"],
["model_mix"],
["cache_reads_sparkline"],
["ambient_wave"],
["ambient_bounce"],
["ambient_marquee"],
["ambient_spinner"],
["ambient_twinkle"],
["ambient_wave_sine"],
["cost_sparkline"]
]
}
}
```