token-doctor

token-doctor is a skill for Claude Code, Codex from techwolf-ai/ai-first-toolkit. It costs 123 tokens per session (3,498 once invoked), scanned C, original, MIT.

A diagnostic tool that examines Claude Code, Cowork, or Codex transcripts to show where conversation length, cache rebuilding, and token usage come from.

In plain words
What is it for?
Use it to inspect conversation distributions, marathon sessions, cache costs, and project diagnoses, with an optional deeper analysis of the biggest hotspots.
Why use it?
It turns AI usage costs and long sessions into concrete measurements, including project-level problem areas, instead of relying on impressions.

Skill for Claude CodeCodex

Written for Claude Code and Codex: shipped in a Claude Code plugin, but also reads ~/.codex or $CODEX_HOME. Also seen: reads .claude/ paths; mentions subagents; positional $N argument.

Part of the ai-adoption plugin — 2 skills shipped together

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/techwolf-ai/ai-first-toolkit/token-doctor
Any agent
npx skills add techwolf-ai/ai-first-toolkit --skill token-doctor
Clone the repo
git clone --depth 1 https://github.com/techwolf-ai/ai-first-toolkit

Made for: Claude Code, Codex.

Or install ai-adoption, the plugin that ships this one along with the rest of its 2 skills.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

agentmods badge for token-doctor

README.md
[![agentmods](https://agentmods.dev/badge/skills/techwolf-ai/ai-first-toolkit/token-doctor.svg)](https://agentmods.dev/skills/techwolf-ai/ai-first-toolkit/token-doctor)
Your own site
<a href="https://agentmods.dev/skills/techwolf-ai/ai-first-toolkit/token-doctor"><img src="https://agentmods.dev/badge/skills/techwolf-ai/ai-first-toolkit/token-doctor.svg" alt="Measured on agentmods" height="20"></a>
Per session 123 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 3,498 The whole file, excluding the scripts and references it only reads on demand.
Security scan C 1 finding. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5.1 $0.00123 $0.03498
Opus 5 $0.00062 $0.01749
Sonnet 5 $0.00025 $0.00700
Haiku 4.5 $0.00012 $0.00350

Measured 6d ago against content hash 15251766e0cb, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-06, from the pricing page.

Security

Grade C, and why

token-doctor scanned grade C with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 6d ago.

The scan reads SKILL.md. This mod also ships 7 executable files (scripts/build_payloads.py, scripts/codex_sessions.py, scripts/host_platform.py, …), listed below but not scanned — reading those needs a real analyzer, not pattern matching.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Recursive force deletehighDestructive command

rm -rf with a variable or a broad path is one typo away from removing the wrong tree.

- The user can `rm -rf out/` to wipe everything.
plugins/ai-adoption/skills/token-doctor/SKILL.md · 283 lines

How it starts

The opening of the file, as written. The whole thing — 283 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Token Doctor

Platforms: Claude Code / Cowork and Codex. scripts/inventory.py detects the host (via the platform stamp install.sh writes, or AI_FIRST_PLATFORM) and routes: Claude Code (~/.claude/projects) + Cowork transcripts, or Codex rollouts (~/.codex/sessions). Codex token usage comes from Codex's own per-response token_count events; cost uses OpenAI list rates in pricing.py (gpt-5.4 family; unknown models show token counts with no fabricated cost). Antigravity is unsupported: its IDE store is AEAD-encrypted at rest and its CLI store has no parseable turn/token content, so the skill prints a clear "not available" message and exits.

Two-stage diagnostic. Stage 1 is fast and lands directly in the terminal so the user always walks away with their numbers. Stage 2 is opt-in, fans out subagents over hotspots, and writes a tight Markdown report.

Read this whole file before running.

When to run

Trigger phrases: "diagnose my Claude habits", "why am I spending so much", "where are my tokens going", "audit my spend", "token doctor", "what's driving my Claude bill".

Do NOT trigger for:

  • "what tasks do I do with Claude" → that's task-profile.
  • "where did I work on X" → that's session-search.

The line is: token-doctor is about cost shape, not task inventory or recall.

Prerequisites

  • Claude Code CLI transcripts: ~/.claude/projects/*/*.jsonl
  • Claude Cowork transcripts (optional): ~/Library/Application Support/Claude/local-agent-mode-sessions/*/*/local_*/audit.jsonl
  • Python 3, stdlib only. No external services.

If neither path exists, stop and say so.


STAGE 1 — Fast diagnosis (always runs, you write the report)

The goal is: the user invokes the skill, sees a clean doctor's report within 10 seconds, knows which projects are healthy and which are bleeding, and can decide whether to go deeper. You write the report directly in your message based on the JSON the scripts produce. The scripts compute, you communicate.

Read the full file on GitHub · 283 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 6d ago First seen · 283 lines · 123 tokens per session scan C 15251766e0cb

Subscribe to this mod's changes

token-doctor is a skill published in the GitHub repository techwolf-ai/ai-first-toolkit (98 stars, last pushed 1mo ago), licensed MIT. It adds 123 tokens to every session and 3,498 once invoked, about $0.0006 per session on Opus 5. A static security scan graded it C with 1 finding (recursive force delete). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Related

Other skills, from other repositories

todos

This chat has a shared, live TODO plan — your tasks for the conversation, which the user also edits. Read this skill and reach for the todo tools whenever a request takes more than a couple of steps. It covers the plan model (group = task, items = its steps; loose items are the user's lane), how to work it: propose…

JetBrains/thinkrail · 127 tokens

writing-workflow-skills

Use when adding a new workflow skill to pi-thinkrail-workflow, changing an existing workflow skill's role, trigger, handoff, or structure, or checking a workflow skill against the workflow system's rules. Not for authoring general-purpose skills outside this package.

JetBrains/thinkrail · 60 tokens

writing-specs

Use when a workflow step drafts or revises a spec artifact — a goal-and-requirements, an architecture, or a module SPEC — or when a workflow skill names it at such a step. The shared quality bar for specs — not a workflow, nothing to execute.

JetBrains/thinkrail · 59 tokens

clarify

Adaptive requirements clarification with auto-depth routing. Shallow (Q&A) for simple tasks, Deep (exploration + DRAFT + PLAN) for complex ones. Escalates automatically when ambiguity persists.

mag123c/toktrack · 43 tokens

case-interview-practice

Interactive consulting case interview practice with structured frameworks, feedback mechanisms, and progressive difficulty. Use when preparing for management consulting interviews, case competitions, or business problem-solving exercises.

travisjneuman/.claude · 39 tokens

finance

Financial analysis expertise for financial modeling (DCF, LBO, M&A), valuation, financial statement analysis, capital allocation, treasury management, and corporate finance decisions. Use when building financial models, analyzing statements, or making investment decisions.

travisjneuman/.claude · 48 tokens