Metadata-Version: 2.4
Name: ccpilot
Version: 0.1.0
Summary: Claude Code efficiency dashboard — not just how much, but is it worth it
License: MIT
Project-URL: Homepage, https://github.com/lingmu/ccpilot
Project-URL: Repository, https://github.com/lingmu/ccpilot
Project-URL: Issues, https://github.com/lingmu/ccpilot/issues
Keywords: claude-code,statusline,token-usage,cache-efficiency,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Dynamic: license-file

# ccpilot

[中文文档](README_CN.md)

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):

```bash
pip install ccpilot && ccpilot install
```

Or with uv:

```bash
uv tool install ccpilot && ccpilot install
```

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

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

Restart Claude Code after activating.

## Uninstall

```bash
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:

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

## Configuration (optional)

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

```yaml
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
