session-report

Generate an interactive HTML report of Codex session token usage from local transcripts.

Updated Jul 10, 2026
One-click install
npx skills add https://github.com/AvaTar-ArTs/.Agent-skills --skill session-report-avatar-arts
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: session-report
Source: https://github.com/AvaTar-ArTs/.Agent-skills/tree/main/skills/session-report
Command: npx skills add https://github.com/AvaTar-ArTs/.Agent-skills --skill session-report-avatar-arts

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codex usage data is scattered across raw session transcripts, making it hard to see where tokens, cache, and subagent costs actually go. This Skill turns those transcripts into a single explorable HTML report with totals, breakdowns, and anomaly callouts. ## Core Features & Use Cases - Usage Aggregation: Runs a bundled Node.js analyzer over ~/.Codex/projects transcripts to compute token totals, per-project and per-skill breakdowns, cache-hit rates, and top prompts. - Interactive HTML Report: Embeds the JSON into a self-contained template with sortable tables, drill-downs, and block-char bar charts. - Anomaly Narrative: Fills dedicated sections with findings such as disproportionate project spend, low cache-hit rates, or oversized prompts, plus optimization suggestions. - Use Case: After a heavy week of Codex work, generate a report to discover that one project consumed 41% of tokens across three sessions and that cache-hit rate dropped below 85%. ## Quick Start Generate a session report of my Codex usage for the last 7 days and save the HTML file here.

Frequently Asked Questions about session-report

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate a Codex session usage report?▼

Run the bundled analyze-sessions.mjs script with Node.js against your ~/.Codex/projects transcripts, then embed the JSON output into the provided HTML template. The report is saved as a self-contained HTML file in your current working directory.

How do I analyze token usage for a specific time range?▼

Pass a --since flag to the analyzer, such as 24h, 7d, or 30d, to limit the window. Omitting the flag analyzes all available session history.

What metrics does the Codex session report include?▼

The report covers overall input and output tokens, per-project and per-skill breakdowns, subagent type usage, cache-hit rates and cache breaks, and the most expensive prompts. Subagent tokens are rolled into their originating prompts.

Does the session report require an internet connection?▼

No. The analyzer reads local transcript files from ~/.Codex/projects and the HTML template renders entirely client-side from embedded JSON. No external services are contacted.

What are the limitations of the session usage analyzer?▼

It only reads Codex transcripts stored under ~/.Codex/projects, so sessions from other tools or machines are excluded. Very large JSON outputs are trimmed to 100 top prompts and 100 cache breaks before embedding.