cc-session-tools

Zero-dependency CLI toolkit for analyzing your Claude Code sessions.

한국어

Install

npx cc-session-tools help        # run without installing
npm install -g cc-session-tools  # or install globally

Requires Node.js 18+.

Commands

| Command | Description | |---------|-------------| | stats | Session statistics + hourly distribution + health warnings | | score | Usage profile (work style, tool mastery, sustainability) | | burnout | Burnout risk assessment with actionable recommendations | | agent-load | AI collaboration profile (delegation style, tool distribution) | | cost | Token usage + cache efficiency (measured from JSONL logs) | | context | Context window utilization (measured from JSONL logs) | | insights | Session insights — goals, outcomes, friction analysis (from facets) | | wrapped | Spotify Wrapped-style summary (HTML) | | handoff | Session handoff management (add/list/done/rm) | | all | Run all analytics commands |

Usage

cc-session-tools stats          # last 30 days (default)
cc-session-tools stats 7        # last 7 days
cc-session-tools score 14       # 14-day usage profile
cc-session-tools insights json  # raw JSON output
cc-session-tools all            # run everything
cc-session-tools --lang ko all  # Korean output

# handoff management
cc-session-tools handoff add "Refactor auth module"
cc-session-tools handoff add "Fix landing page" --scope project --project my-app
cc-session-tools handoff list
cc-session-tools handoff list --all           # include completed
cc-session-tools handoff done 3
cc-session-tools handoff rm 1

Data Sources

cc-session-tools uses two local data sources:

| Source | Path | Used by | |--------|------|---------| | Session metadata | ~/.claude/usage-data/session-meta/*.json | stats, score, burnout, agent-load | | JSONL conversation logs | ~/.claude/projects/*/*.jsonl | cost, context (actual API token data) | | Facets analysis | ~/.claude/usage-data/facets/*.json | insights (goals, outcomes, friction) |

Localization

Output language defaults to English. Set Korean output with:

• CLI flag: --lang ko
• Environment variable: CC_TOOLS_LANG=ko
• System locale: automatically detected from LANG

Design Principles

• No scores or rankings — profiles and patterns, not judgments
• Reliable data only — if the data can't support a claim, we don't show it
• Actionable insights — every metric should help you change behavior (e.g., low cache hit rate → prompt caching guide)

Handoff

Session handoff tracks work across Claude Code sessions. Items persist in ~/.claude/cc-session-tools/.

Storage: Uses better-sqlite3 if available (install via npm i better-sqlite3), otherwise falls back to a JSON file.

Scopes:

• global — visible everywhere (default)
• project — tagged with a project name
• task — granular task-level items

License

MIT