ccpilot 0.1.0

Claude Code efficiency dashboard — not just how much, but is it worth it

ccpilot

中文文档

Claude Code efficiency dashboard — not just "how much", but "is it worth it".

What makes ccpilot different

Every other tool tells you token counts and costs. ccpilot tells you what those numbers mean:

• 📊 cache-hit 78%✓ — are your tokens served from cache (cheap) or rebuilt every turn (expensive)?
• 💚 saved $22.21 — exactly how much money the cache saved you this session
• 🔄 compact 3x (~5 turns to next) — how many times your context was compressed, and when the next one is coming
• 🧊 cache cold — warns you when your cache has expired (idle > 5 min)
• ⚡ efficient — one-word verdict on your session's overall efficiency

All calculated from real JSONL transcript data. No guesswork, no estimates.

Install

One command (installs + activates):

pip install ccpilot && ccpilot install

Or with uv:

uv tool install ccpilot && ccpilot install

Or just install — ccpilot will offer to activate on first run:

pip install ccpilot
ccpilot    # → "Activate statusline now? [Y/n]"

Restart Claude Code after activating.

Uninstall

ccpilot install --uninstall
pip uninstall ccpilot

What you see

Session start (auto-hides empty fields):

📂 ~/project/myapp │ 🌿 main │ 🤖 Opus 4.7
💵 today $23.45

While coding (fields appear as data arrives):

📂 ~/project/myapp │ 🌿 main │ 🤖 Opus 4.7
💰 cost $8.50 │ 💵 today $23.45 │ 🔢 180K in 45K out │ ⏱ dur 1h30m │ 📝 +256 -89
🧠 ctx █████████░ 85% │ 📊 cache-hit 60%~ │ 💚 saved $22.21 │ 🔄 compact 3x (~5 turns to next) │ ⏳ warming

Pro/Max users (rate limits auto-detected, hidden for API users):

📂 ~/project/myapp │ 🌿 main │ 🤖 Opus 4.7
💰 cost $8.50 │ 💵 today $23.45 │ 🔢 180K in 45K out │ ⏱ dur 1h30m │ 📝 +256 -89
🧠 ctx █████████░ 85% │ 📊 cache-hit 60%~ │ 💚 saved $22.21 │ 🔄 compact 3x │ ⚡ efficient
⏱️ 5h-limit ████████░░ 78% 1h05m left │ 📅 7d-limit 35%

Line-by-line explanation

Line	What it shows	Updates
Line 1	Where you are: directory, git branch, model	Always visible
Line 2	What you spent: session cost, today's total, tokens in/out, duration, code changes	After first API call
Line 3	How efficient: context bar, cache hit rate, money saved, compaction count + prediction, efficiency verdict	ccpilot exclusive
Line 4	Rate limits: 5-hour and 7-day usage (Pro/Max only)	Auto-hidden for API users

Efficiency status explained

Status	Meaning	Triggered when
⚡ efficient	Session is cost-effective	cache hit > 60%, compaction ≤ 2
⏳ warming	Cache is still building	session just started, or cache hit 30-60%
🔥 costly	Lots of cache rebuilds	cache hit < 30% after 3+ turns
🚨 stale	Context quality degrading	compaction > 3 times

Session report

Analyze any session in detail:

ccpilot session           # latest session
ccpilot session abc123    # specific session
ccpilot list              # compare recent sessions

Configuration (optional)

Create ~/.config/ccpilot/config.yaml to toggle fields:

statusline:
  show:
    cache_hit: true
    compactions: true
    lines_changed: true
    rate_limits: auto    # auto | true | false

No config needed — defaults work out of the box.

How it works

• StatusLine: Claude Code pipes session JSON to ccpilot every 5 seconds. ccpilot reads it, enriches with JSONL transcript analysis, outputs styled text. Zero API calls, zero token cost.
• Efficiency data: Parsed from ~/.claude/projects/*/ JSONL files. Cache hit rate, compaction events, turn durations — data that exists but no other tool uses.
• Today's cost: Scans all session files for today's date, aggregates across all projects.

Requirements

• Python 3.9+
• No Node.js, no npm, no bun

vs alternatives

Feature	ccstatusline	ccusage	cmonitor	ccpilot
Cache hit rate	—	—	—	✓
Cost savings ($)	—	—	—	✓
Compaction prediction	—	—	—	✓
Cache TTL warning	—	—	—	✓
Efficiency verdict	—	—	—	✓
Today's total cost	—	✓	—	✓
Context bar	✓	✓	—	✓
Rate limits	✓	✓	✓	✓
Session cost	✓	✓	—	✓
No Node.js needed	—	—	✓	✓
One-command install	TUI	manual	—	✓

License

MIT