Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add localixai/tokendoctor
/plugin install tokendoctor@tokendoctor
Open on GitHub

What 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@tokendoctor

This installs the whole tokendoctor plugin with all its skills

2Skills CLI (Vercel)

npx skills add localixai/tokendoctor --skill sessions -a claude-code

3Manually: put the files in place

~/.claude/skills/sessions/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/sessions/

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.

sessions Insilico-org The sessions Claude Code skill defines how bots work together in Grok group-chat rooms. It covers task briefs, handoffs between members, and closing a round. CX Codex +1 ★ 93repo stars token-optimizer alexgreensh token-optimizer — a skill for Claude Code and Codex that tracks where the context window goes, suggests fixes, and applies the ones you approve. Kick it off when sessions feel tight or the bill starts climbing. CX Codex +1 1,100installs skill-progressive-disclosure-design samber skill-progressive-disclosure-design is a Claude skill that helps decide what stays in SKILL.md and what moves to references/ to manage context loading. CX Codex +1 5,100installs janitor-value Krzysztof Hendzel janitor-value audits installed skills against actual session history to spot context waste. Ideal when checking which prompts overload your context window. CX Codex +1 ★ 140repo stars token-check egorfedorov token-check estimates token usage for snippets, files, or chat history. Shows how context limits are consumed and suggests ways to trim the prompt. CX Codex +1 ★ 134repo stars reap thousandflowers reap shows how much of the context an agent loads goes unused: idle skills, MCP servers, subagents, hooks and always-loaded prose. Measured from real session transcripts. CX Codex +1 ★ 67repo stars context-optimizer Rohit Ghumare The context-optimizer command checks context window fill rates in Claude Code and helps cut token waste before responses degrade. CX Codex +1 ★ 2,966repo stars

From the same set6

Project sponsors

Companies that keep this analytics open