time-report

Time Report

Generate an interactive HTML Gantt chart report showing Claude Code session activity.

Arguments

$ARGUMENTS contains the user input. Parse as:

• --list → List all projects with session counts
• <project> <YYYY-MM> → Report for a specific month
• <project> <from-date> <to-date> → Report for a date range
• No arguments → Same as --list

Execution

Step 1: Ensure DB freshness

Call MCP tool to index any new sessions:

mcp__cccmemory__index_all_projects(incremental=true)

Step 2: Generate report

python3 ${CLAUDE_PLUGIN_ROOT}/skills/time-report/scripts/time-report.py $ARGUMENTS --open

Transcript visualization (opt-in). If the user's request mentions transcripts or session visualization — e.g. "transcript(s)", "可视化", "会话可视化", "看会话内容", "view sessions", "session viewer" — append --transcripts:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/time-report/scripts/time-report.py <project> <range> --transcripts --open

This renders every in-range session into a static HTML bundle via claude-code-transcripts (run through uvx; the tool is fetched/cached on first use) and turns the Title column of the cost table into a link to each session's transcript. Bundles are written to <project path>/time-report-transcripts/<session-id>/ by default (override with --transcripts-dir DIR); generation is idempotent (existing bundles are reused). Requires uv/uvx on PATH.

AI one-line summary (on by default). The Summary column shows a one-sentence "what this session actually accomplished" synopsis, generated by reading each session's activity (prompts, replies, edited files, commands, completed todos) — not the first prompt. It is produced by the Claude Code CLI (claude -p --model haiku), so it reuses the user's existing Claude Code login / subscription — no ANTHROPIC_API_KEY needed. Summaries are cached at <project path>/time-report-summaries/<session-id>.txt (override with --summaries-dir DIR), so the cost is paid once per session and later runs reuse the cache. If the claude CLI is missing or a call fails, that row falls back to the first-prompt text. Disable with --no-ai-summary; change the model with --ai-summary-model <name>.

If the script reports an error, display the error message to the user.

Output

The skill produces an interactive HTML report (written to /tmp/time-report-<project>-<range>.html) and opens it in the default browser (the --open flag handles this). It has two parts:

1. Gantt chart — each session as a horizontal bar on a per-day timeline, with hover tooltips and click-to-expand detail.
2. Token Usage & Cost table — one row per session with columns: Started, Title, Summary, Messages, Input, Output, Cache Write, Cache Read, Total, Cost. Title is the session's auto-generated aiTitle (falls back to the first-prompt summary); with --transcripts it links to that session's rendered transcript. Summary is an AI-generated one-line synopsis of what the session accomplished (on by default; falls back to the first user message when AI summaries are disabled or unavailable — see the AI summary note above). Numeric/time columns are sortable (default: Total tokens, descending); tables longer than 15 rows paginate, and the TOTAL footer always reflects the full dataset. A glossary below the table explains the pricing logic.

The terminal also prints a text summary (active time, total tokens, estimated cost, per-model cost breakdown) followed by a per-session table report with the same token/cost columns.

Sources & dedup. The report includes both Claude Code (transcripts under ~/.claude/projects) and Codex (~/.codex/sessions + archived_sessions) sessions. Sessions are deduped by their external_id, so a session that ran in a git worktree under the repo — and is therefore registered under both the repo path and the worktree path — is counted once. Active Time unions every session's events per calendar day, so parallel sessions (including Codex running alongside Claude) only count their overlapping wall-clock once.

When --list is used instead, the script prints a plain-text table of projects with their session counts to stdout — no HTML file is produced.

Cost methodology

Costs are computed from each assistant message's usage block in the session JSONL, priced as if every call went through the first-party Anthropic API at standard (non-batch) rates — Opus $5/$25, Sonnet $3/$15, Haiku $1/$5 per 1M input/output tokens; cache writes 1.25× (5-min) / 2× (1-hour) input, cache reads 0.1× input (pricing cached from the claude-api skill, 2026-05-26). Model family is inferred from the model field per message, so mixed-model sessions (e.g. Haiku subagents) are priced correctly. This is an API-equivalent estimate, not your actual Claude Code subscription charge — subscriptions are billed differently. Codex sessions are not priced (they run OpenAI models): their time and token counts are included, but the Cost column shows "—" and they are excluded from the $ total, keeping it a pure Anthropic-API-equivalent figure. To refresh prices, edit the PRICING dict in scripts/time-report.py.

Price references:

• Per-model token prices: https://www.anthropic.com/pricing#api
• Prompt-cache write/read multipliers: https://platform.claude.com/docs/en/build-with-claude/prompt-caching