sessions · localixai — Claude Code skill: what it does, how to install
sessions is a Claude Code skill that inspects local session transcripts to break down token usage and costs. It analyzes activity over a requested number of days.
MIT ★ 171 updated 2026-11-17
/plugin marketplace add localixai/tokendoctor
/plugin install tokendoctor@tokendoctorWhat sessions does
The skill inspects local Claude Code session logs across the last 30 days or a custom interval using tokendoctor-sessions and tokendoctor-replay. Both scripts run strictly read-only. They read token counts, timestamps, tool names, and file paths, while message text is never parsed.
Expenditures are calculated against Claude API list prices. The breakdown highlights token distribution between the main prompt and subagents, identifies context-heavy tool outputs, and measures theoretical savings from tighter context compaction windows (autoCompactWindow). Recommended fixes are offered via /tokendoctor:audit or /tokendoctor:optimize, without modifying files autonomously.
The tool cannot inspect sessions hosted on other machines, custom negotiated pricing, or transcripts that Claude Code has already purged.
What it helps with
- identify tools and subagents driving high token consumption
- calculate cost savings from tuning the context compaction window
- locate wasteful Bash commands like redundant file reads or sleep loops
- track token expenditure changes across days or weeks
Example prompts for the agent
- Analyze token usage across my sessions for the past 14 days
- Check where context tokens went in recent subagent runs
- Run sessions to inspect compaction savings
How to install sessions
1Plugin marketplace
/plugin marketplace add localixai/tokendoctor/plugin install tokendoctor@tokendoctorThis installs the whole tokendoctor plugin with all its skills
2Skills CLI (Vercel)
npx skills add localixai/tokendoctor --skill sessions -a claude-code3Manually: put the files in place
~/.claude/skills/sessions/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/sessions/
1Skills CLI (Vercel)
npx skills add localixai/tokendoctor --skill sessions -a codex2Manually: put the files in place
.agents/skills/sessions/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add localixai/tokendoctor --skill sessions -a cursor2Manually: put the files in place
.cursor/skills/sessions/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install localixai/tokendoctor skills/sessions2Manually: put the files in place
.github/skills/sessions/SKILL.md1Skills CLI (Vercel)
npx skills add localixai/tokendoctor --skill sessions -a gemini-cli2Platform CLI
gemini skills install https://github.com/localixai/tokendoctor --path skills/sessionsManually: put the files in place
.devin/skills/sessions/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about sessions
How to install sessions in Claude Code?
Run /plugin marketplace add localixai/tokendoctor and then /plugin install tokendoctor@tokendoctor. Alternatively, install via terminal using npx skills add localixai/tokendoctor --skill sessions -a claude-code.
What does the sessions skill do?
It audits local session transcripts to show token consumption across tools, subagents, and context thresholds, pricing the usage at Claude API rates.
What is required to run sessions?
It requires the tokendoctor-sessions and tokendoctor-replay commands available in your environment. The skill functions solely with local machine transcripts.
Source text
SKILL.md · MIT
---
name: sessions
description: Measure where tokens actually went in recent Claude Code sessions, from the local transcripts.
disable-model-invocation: true
allowed-tools: Bash(tokendoctor-sessions *), Bash(tokendoctor-replay *)
argument-hint: [days]
---
Measure token spend from this machine's session transcripts over the last `$ARGUMENTS` days (30 if
none given).
1. Run `tokendoctor-sessions --json --days <n>` and `tokendoctor-replay --json --days <n>`. Both
are read-only and read only usage figures, timestamps, tool names and file paths from the
transcripts, never message text.
2. Costs are dollars at each model's Claude API list price (lib/prices.mjs). What Claude Code bills
but does not write into transcripts (summary compactions' own requests, titles, WebFetch page
reads) comes from its own session totals where they hold, else an estimate. On a Pro or Max plan
these are what the same work would cost on the API, not what it took from the plan's limits: lead
with shares (percent), and say "at API list prices" with any dollar figure.
3. Open with the person's own number: what share of the period's cost a smaller compaction window
would have saved, from the replay (the 400K row, and 200K or 300K where they save much more).
Call it an upper bound: the replay cannot see the work a model does again after a summary. If
the window is already at or under 400K, or almost no session passed it, say the window would
change little for them, rather than leading with a small number.
Then lead with the two or three largest shares: main thread against subagents, the share spent with
more than 400K tokens in context, and the subagent types that cost the most. Then present each
finding in one or two plain sentences with its doc link.
4. Connect findings to settings where they apply: `late-compaction` to `autoCompactWindow`,
`subagents-on-top-model` to `CLAUDE_CODE_SUBAGENT_MODEL` and the Explore override. Offer
`/tokendoctor:audit` to check and fix them. Never edit files from this skill.
5. Then read `usage` and draw your own conclusions from it: which tools fill the context (calls and
characters of output, main thread and subagents apart), Bash calls that only printed a file
(`fileReads`) or slept in a loop (`waits`), the files read most often, and how large subagent
runs grow (requests, how many passed 200K context). Recommend what would cut the spend you see,
in plain words with the number behind it. A recommendation is either a setting or an instruction:
- a setting: give the exact `/tokendoctor <name> <value>` line, which applies it as typed
(`/tokendoctor` alone lists them). Among them: `bash-output <n>` caps what one Bash call puts
in context, `slide on`, `window <n>`, `subagents <model>`;
- an instruction for Claude (how subagents are briefed and sized, what they report back, when to
read docs, how to wait on a process): draft the few lines and say where they would go (the
project's memory or `CLAUDE.md`).
Offer `/tokendoctor:optimize` to apply several at once: it shows each change and applies only
what the person approves. Leave choices the person made on purpose (in memory or settings) to
them, with what they cost.
6. When asked about a trend or whether a change helped, run `tokendoctor-sessions --by day` (or
`--by week`, with `--days <n>`) and compare the periods before and after. Days older than the
transcripts come from the history the plugin's SessionStart hook records.
7. Say what this cannot see: per-model prices, sessions on other machines, and transcripts Claude
Code has already cleaned up.
© rsaryev · MIT · localixai/tokendoctor
Similar skills
All skills for Agent setup: memory, context, orchestration →sessions by other authors comes first.