session-report

name	session-report
description	Generate a comprehensive session report with per-model token usage (input, output, cache_read, cache_write including compaction baselines), cost breakdown via the pricing engine, tool invocations, agent hierarchy, compaction events, API errors, turn durations, and thinking block counts. Use when reviewing a specific session or summarizing activity over a date range.

Session Report

Generate a detailed session report from the Claude Code Agent Monitor.

Input

The user provides: $ARGUMENTS

This may be a session ID, "latest", or a date range like "last 24 hours".

Data Sources

All data comes from the Agent Monitor API at http://localhost:4820:

Endpoint	What it returns
GET /api/sessions/{id}	Session with nested .agents[] and .events[]
GET /api/sessions?limit=50	Session list with agent_count, last_activity, and inline cost per session (bulk pricing applied server-side)
GET /api/pricing/cost/{sessionId}	{ total_cost, breakdown: [{ model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost, matched_rule }] }
GET /api/events?session_id={id}	Event stream: each has event_type, tool_name, summary, data (JSON), created_at

Key data points available per session

• Status: active / completed / error / abandoned
• Model: primary model (e.g. claude-sonnet-4-20250514)
• Metadata (JSON): thinking_blocks count, turn_count, total_turn_duration_ms, usage_extras (service_tier, speed, inference_geo)
• Token usage per model: Pricing breakdown reports input_tokens, output_tokens, cache_read_tokens, cache_write_tokens per model (baselines are pre-summed into these totals at the DB level)
• Cost formula: (tokens / 1,000,000) × rate_per_mtok for each of 4 token types, using longest-match pricing rule
• Agent hierarchy: recursive parent_agent_id tree, subagent_type (e.g. "task", "explore", "code-review", "compaction")
• Event types: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, Notification, Compaction, APIError, TurnDuration

Report Sections

1. Session Overview

• ID (first 16 chars), name, status, model, working directory
• Start → end time, total duration
• Turn count and avg turn duration (from metadata)

2. Token Usage (per model)

Include these columns: Model, Input, Output, Cache Read, Cache Write, and Total. Show effective totals (current + baseline) since baselines preserve tokens lost during compaction. Calculate cache hit rate: cache_read / (cache_read + input) × 100.

3. Cost Breakdown

From /api/pricing/cost/{id} — show each model's cost with the matched pricing rule. Note rates are per million tokens.

4. Agent Hierarchy

Render the agent tree (main → subagents, with nested children). For each agent: name, type, subagent_type, status, task (first 60 chars), duration.

5. Tool Activity

Count PreToolUse events by tool_name. Flag tools that appear in error events. Note subagent spawns (tool_name = "Agent").

6. Compaction & Context Health

• Count of Compaction events (each = context was compressed)
• Baseline tokens recovered (sum of baseline_* columns)
• Thinking block count from metadata

7. API Errors

List any APIError events with type (quota, rate_limit, overloaded) and message.

8. Timeline

Key lifecycle events: SessionStart → first tool → compactions → errors → Stop → SessionEnd. Include TurnDuration events.

Output Format

Clean Markdown: executive summary line, structured tables, agent tree, numbered timeline. Bold key metrics.