ccprompts

Collect & analyze Claude Code prompts across your team.

ccprompts is a CLI that reads your local Claude Code session history and turns it into clean, readable reports — daily/weekly Markdown exports plus quick console views for cost, stats, and session listings. Useful for self-review, team coaching, and understanding how your team uses Claude Code.

Install

npm install -g @datnt217/ccprompts

After install, the command is just ccprompts:

ccprompts daily

Requirements

• Node.js >= 18
• Claude Code installed, with at least one session in ~/.claude/projects/

Commands

| Command | Output | Default scope | |---|---|---| | ccprompts daily | Markdown file + console summary | Today | | ccprompts weekly | Markdown file + console summary | Last 7 days | | ccprompts cost | Console only | Today | | ccprompts stats | Console only | Today | | ccprompts list | Console only | All sessions |

daily — full daily conversation report

ccprompts daily
ccprompts daily --date 2026-04-07
ccprompts daily --out ./reports
ccprompts daily --user alice

Scans all Claude Code sessions, filters messages from the target date (local time), and writes a Markdown report ({user}_daily_prompts_{date}.md) to the current directory. The report includes:

• 📈 Overview (sessions, prompts, active time, total cost, total tokens)
• 💰 Cost breakdown per model
• ⏰ 5-hour billing blocks
• 📑 Sessions table of contents (clickable in VS Code preview / GitHub)
• 🔧 Tool usage breakdown (Read, Edit, Bash, Grep, ...)
• 📏 Prompt length stats
• Per-session detail with full prompt + response transcripts and ⚙️ AI actions summaries for tool-only turns

weekly — multi-day aggregated report

ccprompts weekly                    # last 7 days
ccprompts weekly --days 14          # last 14 days
ccprompts weekly --end-date 2026-04-09 --days 7

Aggregates the last N days into a single Markdown file with per-day breakdown, top sessions by cost, model breakdown, tool usage, and prompt-length stats.

cost — quick cost breakdown

ccprompts cost                      # today
ccprompts cost --days 7             # last 7 days
ccprompts cost --date 2026-04-01 --days 30

Console-only cost report. Shows total cost, per-model breakdown, top sessions by cost, and 5-hour billing blocks. No file written.

stats — prompt / tool / model statistics

ccprompts stats
ccprompts stats --days 7

Console-only stats report. Shows message length distribution, tool usage, and model usage. Useful for spotting overly short prompts, unbalanced tool usage, or unexpected model fallback.

list — list sessions

ccprompts list                      # all sessions, max 50
ccprompts list --date 2026-04-09
ccprompts list --limit 200

Console-only table of sessions with date, project, branch, message count, tokens, and cost. Useful to discover which sessions are most expensive or longest.

Common Options

| Flag | Description | Default | |---|---|---| | -d, --date <YYYY-MM-DD> | Target date | Today (local) | | -D, --days <N> | Days back from date | Varies | | -o, --out <dir> | Output directory (file commands) | Current working dir | | -u, --user <name> | Override username | OS user or $CCPROMPTS_USER | | -l, --limit <N> | Max rows to show (list) | 50 | | --offline | Skip LiteLLM pricing fetch | off | | -v, --verbose | Print pricing source diagnostics | off |

Cost & Token Accuracy

ccprompts matches ccusage on cost and token totals. It does this by:

1. Reading usage directly from Claude Code's JSONL files (no client-side tokenization)
2. Deduping by uuid and message.id so resumed sessions don't double-count
3. Counting tool-only turns — assistant API calls that contain only tool_use / thinking blocks (no text) are still billed and are tracked
4. Fetching pricing from LiteLLM — the same source ccusage uses, cached locally for 24 hours at ~/.ccprompts/cache/pricing.json

If LiteLLM is unreachable, ccprompts falls back to a hardcoded pricing table (with a warning when --verbose).

Report Format Example

# Daily Conversation Report — 2026-04-09

**User:** datnt
**Generated:** 4/9/2026, 7:05:12 PM

## 📈 Overview

| Metric        | Value               |
|---------------|---------------------|
| Sessions      | 4                   |
| User prompts  | 47                  |
| AI responses  | 56                  |
| Active time   | 8h 42m              |
| Total cost    | $44.97              |
| Total tokens  | 62,477,664          |

## 💰 Cost Breakdown

| Model     | Input | Output | Cache Write | Cache Read | Cost   | Share  |
|-----------|-------|--------|-------------|------------|--------|--------|
| Opus 4.6  | 316   | 41,689 | 2,210,887   | 60,224,772 | $44.97 | 100.0% |

## 📑 Sessions

| # | Session    | Project      | Branch  | Time                | Active | Msgs | Tokens | Cost   |
|---|------------|--------------|---------|---------------------|--------|------|--------|--------|
| 1 | a1b2c3d4   | acme-app     | main    | 08:42 → 11:57       | 3h 12m | 42   | 14.6M  | $33.00 |

## Session 1 (a1b2c3d4)

- **Project:** acme-app
- **Branch:** `main`
- **Model:** Opus 4.6
- **Time:** 08:42:16 → 11:55:07  (active 3h 12m, idle 30m)
- **Messages:** 42 (18 user · 24 AI)
- **Tokens:** 14,600,000 (...)
- **Cost:** $33.00
- **Top tools:** Read ×48 · Edit ×32 · Grep ×22 · Bash ×15

### [001] 👤 USER — 08:42:16
```
Add a dark mode toggle to the navbar...
```

### ⚙️ AI actions — 08:42:30 → 08:43:45
_Read ×5 · Grep ×8 · Edit ×2 · thinking ×3_

### [002] 🤖 AI — 08:43:48
```
Done. I added ThemeProvider and a useTheme() hook...
```

How It Works

ccprompts reads ~/.claude/projects/*/*.jsonl — the session transcripts Claude Code writes locally. It parses every message, filters system reminders and internal metadata, groups messages by session, deduplicates resumed-session replays, computes token + cost totals using LiteLLM-sourced pricing, and renders the final report.

Nothing is uploaded. Everything runs on your machine, against files already on your disk. The only network call is fetching pricing data from LiteLLM's public GitHub repository (cached for 24 hours; --offline disables it entirely).

Roadmap

• ccprompts coach <user> — automated prompt quality review (LLM-assisted)
• ccprompts leaderboard — compare team members' usage patterns
• ccprompts export — export raw session data as JSON / CSV
• HTML report renderer with charts

License

MIT © datnt