Guide · Agent skill
How to use the Claude Code Session Report agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The session-report skill is a packaged set of instructions and scripts that teaches Claude Code to analyse your own past sessions and produce an explorable HTML report of your token usage. It is for developers who use Claude Code heavily and want to see which projects, subagent types, skills and prompts consume the most tokens. By the end of this guide you will know what the skill does, how to install it, how to ask for a report, and what to check before sharing the output.
Claude Code Session Reportanthropics/claude-plugins-official · Apache-2.0 Download the skill Quick start
- 1Get the ZIP. Download the session-report ZIP from this skill's page on the directory.
- 2Unzip into a skills folder. Unzip into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
- 4Confirm Node.js and transcripts. Make sure Node.js is installed and that ~/.claude/projects contains Claude Code session transcripts.
- 5Ask for a report. Request a session report in plain language, naming a range such as 24h, 30d or all if you want something other than the default 7 days.
- 6Open the saved file. Find the session-report file the agent saved in your current folder and open it in a browser.
- 7Act on the findings. Review the red, green and blue findings and the optimisation callouts, then adjust how you use subagents, skills or long prompts.
What is an agent skill, and what does session-report make the agent do?
An agent skill is a folder containing a SKILL.md file with instructions, plus any helper files the agent can use. When a skill is installed, Claude Code can follow its steps when a request matches its description.
Once session-report is installed, the agent reads your local Claude Code session logs stored under ~/.claude/projects. It summarises token use over a period you choose, broken down by project, subagent type, skill, cache misses and expensive prompts. It then fills a bundled HTML template with that data and saves a self-contained, explorable report in your current folder, along with a few plain-English findings and optimisation tips.
Install the session-report skill
You can install the skill in one of three places. Download the ZIP from the skill's page on this directory and unzip it into one of the following locations.
Personal install: unzip into ~/.claude/skills/ so the skill is available in all your projects.
Project install: unzip into the .claude/skills/ folder of a specific project so it is available only there.
Claude apps: upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Project: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills
Check the requirements
The skill needs two things. First, Node.js must be installed, because the analyser runs as analyze-sessions.mjs with node. Second, you need local Claude Code session transcripts in ~/.claude/projects. If you have never used Claude Code on this machine, there is nothing to analyse yet.
- Node.js installed (the script is run with node)
- Local Claude Code transcripts in ~/.claude/projects
- The skill folder contains analyze-sessions.mjs, SKILL.md and template.html
Trigger the skill with a natural request
You do not need a special command. Ask Claude Code in plain language for a usage report, token breakdown or session summary. The default window is the last 7 days. If you name a different range, the agent honours it. The source mentions 24h, 30d and all as examples of ranges.
The agent will run the analyser, read the results, copy the template to a file named session-report with a timestamp in the current folder, fill in the data and findings, and tell you the saved file path. It does not open or render the file for you.
- "Make me a session report for the last 7 days."
- "Show me my Claude Code token usage for the last 30 days."
- "Generate a session report across all my sessions."
- "Where did my tokens go in the last 24 hours?"
Read the report and act on the findings
Open the saved HTML file in your browser. The report is self-contained, so it does not need a server. The hero total shows overall usage, and the tables show projects, subagent types, skills, cache breaks and top prompts. Tables can be sorted and expanded, and bars show relative size.
The findings are one-line notes that flag waste, healthy signals or neutral facts. Percentages are calculated as a share of total tokens. Look for a project or skill taking a disproportionate share, cache hit rates below 85%, a single prompt above 2% of total, subagent types averaging more than 1M tokens per call, or cache breaks clustering together. The optimisation callouts at the bottom point at specific rows.
- Bad (red): waste or anomalies
- Good (green): healthy signals
- Info (blue): neutral facts
Keep the report private
The report contains prompt excerpts and project names taken from your private session history. Do not share it publicly or on a shared machine without reviewing it first.
The skill runs scripts and the source says it does not use the network. Its analyser reads local transcripts and writes the report locally. Review the SKILL.md and scripts yourself if you want to confirm this before installing.
- Prompt excerpts and project names are included
- Review the file before sending it to anyone
- Scripts are run on your machine
node <skill-dir>/analyze-sessions.mjs --json --since 7d > /tmp/session-report.jsonWhat people use it for
- Finding which project consumed most of last week's tokens
- Checking whether subagent types average very high token use per call
- Spotting cache misses that may be raising costs
- Identifying single prompts that account for a large share of usage
- Producing a weekly summary of Claude Code usage for yourself or a small team
Frequently asked questions
How do I install the session-report skill?
Download the ZIP from this skill's page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What do I need to run the session-report skill?
You need Node.js, because the analyser runs as analyze-sessions.mjs with node. You also need local Claude Code session transcripts stored in ~/.claude/projects, so the skill has something to analyse.
Does session-report use the internet?
The source lists the skill as not using the network. It runs scripts locally to read your transcripts and write an HTML report to your current folder. The skill does run scripts, so review the files before installing if that matters to you.
Is session-report free to use?
The source does not state pricing or licence terms beyond the listed licence, which is Apache-2.0. Check the licence file in the repository for the terms that apply.
Can the report be shared with my team?
Be careful. The report contains prompt excerpts and project names from your private session history. Review it before sharing, and avoid publishing it or sending it from a shared machine.
Why doesn't the report open automatically, or why can't the agent find my transcripts?
The skill saves the file and reports its path but does not open or render it, so open it yourself in a browser. If no report can be made, check that Node.js is installed and that ~/.claude/projects contains transcripts.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Session-report is a good fit for heavy Claude Code users who want to see where their tokens go, and for teams trying to reduce subagent or cache costs. It is not useful if you do not use Claude Code, because there are no transcripts to analyse. Avoid sharing its reports publicly, since they include private prompt excerpts and project names.
Download the skill