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