Analyze your Claude Code usage with DuckDB. Load your local ~/.claude session history into a queryable database and get insights about your coding patterns, token usage, costs, and tool usage.
Inspired by ClickHouse/alexeyprompts, but using DuckDB for zero-setup local analytics.
npx clauduckThis will:
- Load all your
~/.claudesession data into DuckDB (~/.claude/clauduck.db) - Run 15 built-in analytics queries
- Print results to the terminal
npx clauduck tuiBrowse pre-built queries, run custom SQL, and explore your data interactively.
npx clauduck --last 7d # last 7 days
npx clauduck --last 4w # last 4 weeks
npx clauduck --since 2025-01-01 # from a date
npx clauduck --since 2025-01-01 --until 2025-06-30 # date range
npx clauduck --source projects # only project sessionsCopy and paste this into your Claude Code session:
Read and follow the instructions at https://raw.githubusercontent.com/duyet/clauduck/main/CLAUDE.md — set up ClauDuck locally and give me insights about my Claude Code usage
Claude will automatically set up, load data, run analytics, and present a rich dashboard.
| Source | Path | Content |
|---|---|---|
| History | ~/.claude/history.jsonl |
User prompt log with timestamps and project |
| Sessions | ~/.claude/projects/*/*.jsonl |
Full conversation transcripts with tool calls, tokens, models |
| Transcripts | ~/.claude/transcripts/*.jsonl |
Lightweight transcripts (older sessions) |
| Metadata | ~/.claude/sessions/*.json |
Session metadata (pid, cwd, kind) |
All data lives in a single events table with a type column:
| Type | Description |
|---|---|
session |
One row per session with aggregated stats (tokens, tools, duration) |
message |
Individual messages with token counts and tool names |
tool_call |
Every tool invocation (Bash, Read, Edit, etc.) |
history |
Every prompt you've typed with timestamps |
| # | Query | What it shows |
|---|---|---|
| 1 | Overview | Total sessions, projects, tokens, hours |
| 2 | Daily activity | Sessions, messages, tokens per day |
| 3 | Top projects | Projects ranked by token usage |
| 4 | Tool ranking | Most used tools across all sessions |
| 5 | Cost estimate | Estimated USD cost by model (Haiku/Sonnet/Opus) |
| 6 | Hourly pattern | What hours you code most |
| 7 | Day of week | Weekday vs weekend patterns |
| 8 | Longest sessions | Sessions by duration |
| 9 | Token-heavy sessions | Most expensive sessions |
| 10 | Cache efficiency | Cache hit rates by project |
| 11 | Complexity distribution | Session size buckets |
| 12 | Weekly trends | Week-over-week usage |
| 13 | Git branches | Activity per branch |
| 14 | Version history | Claude Code versions used |
| 15 | Repeated prompts | Your most-typed commands |
The database is standard DuckDB with a single events table. After running npx clauduck, you can query it directly:
duckdb ~/.claude/clauduck.db-- Find sessions where you used Agent tool more than 10 times
SELECT session_id, project_name, tool_call_count, duration_minutes
FROM events
WHERE type='session' AND 'Agent' = ANY(tools_used) AND tool_call_count > 100
ORDER BY tool_call_count DESC;
-- Average tokens per hour by project
SELECT
project_name,
round(sum(total_input_tokens + total_output_tokens) / nullif(sum(duration_minutes / 60.0), 0) / 1e6, 2) as tokens_M_per_hour
FROM events
WHERE type='session' AND duration_minutes > 10
GROUP BY 1
ORDER BY 2 DESC;git clone https://github.com/duyet/clauduck.git
cd clauduck
bun install
bun run build # Build with tsup
bun run test # Run tests with vitest
bun run dev # Run CLI in dev mode (tsx)All data stays local. ClauDuck reads only from your ~/.claude directory and writes to ~/.claude/clauduck.db. Nothing is sent to any server.
MIT