by inevolin
Empirical analysis of Claude Code token usage: auto-compaction sweet spots across 8 developer workflows and Claude Desktop vs. CLI overhead
# Add to your Claude Code skills
git clone https://github.com/inevolin/claude-code-usage-analysisGuides for using cli tools skills like claude-code-usage-analysis.
See how claude-code-usage-analysis compares with popular alternatives.
claude-code-usage-analysis is an open-source cli tools skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by inevolin. Empirical analysis of Claude Code token usage: auto-compaction sweet spots across 8 developer workflows and Claude Desktop vs. CLI overhead. It has 79 GitHub stars.
claude-code-usage-analysis's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.
Clone the repository with "git clone https://github.com/inevolin/claude-code-usage-analysis" and add it to your Claude Code skills directory (see the Installation section above).
claude-code-usage-analysis is primarily written in Python. It is open-source under inevolin on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other CLI Tools skills you can browse and compare side by side. Open the CLI Tools category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh claude-code-usage-analysis against similar tools.
No comments yet. Be the first to share your thoughts!
Top skills in this category by stars
Available after the catalog security scan passes.
⚠️ Third-Party Software Notice
This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM lists this project for discovery and does not control or maintain the underlying repository.
Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.
Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
See comparison
As engineers and builders we are using LLMs for almost all of our work, and the more we use them the more important it becomes to understand how to optimize the performance, reliability and cost of AI tools. I started this research to better understand and improve my own setup and greatly reduce my token usage and costs.
Claude Code usage is driven by cache misses, not by how much you type. The expensive habits are ways of throwing that cache away.
How long is your cache? 5 minutes on an API key (also Bedrock, Vertex and Foundry). 1 hour on a Pro, Max or Ultra subscription within its usage limits. The Claude CLI and the app behave the same. /usage shows it on its Prompt cache (main) line. (does this apply to you?)
| ✅ Do | ❌ Don't | Usage and evidence |
|---|---|---|
Run /compact before a break longer than your cache |
Leave and resume later | 2.5x vs about 10x3 runs (details) |
After a break, /clear and write 3 lines: goal, done, next |
Run /compact after the break |
about 1x vs about 10x3 runs, 2 for /compact (details) |
| On a subscription, lower the idle-compact minimum to 100k and keep the window open on breaks | Let the laptop sleep mid-session | +76% over a workday when idle compact did not run(estimate) modeled, not tested live (details) |
| Keep one session for small related fixes in a row | /clear between them |
28% less1 run, small history, preliminary (details) |
Keep tool output short: a 1-line summary, or pipe logs through tail -50 |
Leave long logs in the chat, or let Claude reread the whole repo each turn | +15% (750-token log) to +64% (5,000) over the next 6 turns2 runs each, preliminary (details) |
| Pick tools and model at the start | Turn off a tool or switch models mid-task | 22x a normal turn2 runs, preliminary; model switch from docs, not tested (details) |
| Use the Claude Code CLI | Use the Desktop Code tab | Desktop at least 1.80x, T3 Code 1.19x the CLI1 run, preliminary. Slash commands work in the Desktop app too. We did not test the Claude chat app. (details) |
Everyone uses Claude Code differently. The best settings for you depend on your own logs. Paste the text below into Claude Code to check your habits once:
Everyone uses Claude Code differently. Recommend settings that fit MY logs, not general advice.
1. Clone https://github.com/inevolin/claude-code-usage-analysis into a temp folder, then run:
python3 -m pip install -e .
OUT=$(mktemp -d)
python3 -m cc_usage_study.analyze ~/.claude/projects --summary --sessions --calls -o "$OUT/report.json"
Keep that report file outside any git repo. Use only that file: summary numbers, timestamps, token counts, entrypoints, and compact_boundary fields. Do not read, paste, or upload the raw text of my chats. Do not report money amounts. Use % and multipliers.
2. Score my habits with my own numbers:
- Continuing a session after the cache expired: use cache_rebuilds_main.ttl_expired_rebuild (a gap over 5 minutes if cache_creation_5m_tokens are most of the writes, or over 1 hour if cache_creation_1h_tokens are).
- /compact after a break, or before: compare boundary_rows timestamps and trigger with gaps in call_rows.
- Many short sessions close together (a rough sign of /clear between related work) instead of one continued session.
- sdk-cli (claude -p) sessions continued across gaps, instead of a new session each run.
- Which app I used, from by_entrypoint: cli = Claude Code CLI, sdk-cli = claude -p, t3-code = T3 Code, claude-desktop-3p = Desktop Code tab. Prefer the CLI, or T3 Code. Desktop's Code tab used at least 1.80 times the CLI in this study. The Claude chat app was not measured.
- Sessions where one request reaches 300,000 tokens: use one call's prompt_tokens or compact pre_tokens. Do not use the session-sum of prompt_tokens.
3. Write a short report:
(a) the 3 habits costing me the most, with my % or multipliers;
(b) changes that fit my pattern, only from this list: /compact before breaks, /clear plus a 3-line reminder when I am already back, a new `claude -p` session each scheduled run, prefer the CLI or T3 Code over Desktop's Code tab. Mention `--autocompact` only as an unproven idea, and only if my sessions actually get that large;
(c) what you could not tell. If a field is missing, compute it from timestamps and compact_boundary metadata only, or say you cannot tell.
This runs on your computer, on the files in ~/.claude/projects. The prompt tells Claude to use summary numbers and timestamps, not the raw text of your chats. The only thing that leaves your machine is the normal Claude Code conversation. That conversation will include those summary numbers.
Or install the skill, then type /claude-code-usage-check in a new session:
mkdir -p ~/.claude/skills
cp -R skills/claude-code-usage-check ~/.claude/skills/
To run only the analyzer yourself: python3 -m cc_usage_study.analyze ~/.claude/projects --summary --sessions --calls -o ./local-out/report.json. Keep the report file outside git. The tool never copies the text of your prompts.
--autocompact 180000 uses about 43% less. In a live test on a 270,000-token session, it only tied the default. We ran that test once, with no long pauses. (details)CLAUDE.md, adding an MCP server, or changing effort between turns did not break the cache. The next turn used about the same as a normal turn (0.95x to 1.08x on average). (3 runs each, Claude Code 2.1.325; older versions may behave differently) (details)claude -p run (the Claude CLI's scripted mode) instead of starting fresh is estimated at about 3x. Not tested live. (details)A "break" means you were away longer than the prompt cache. That cache lasts 5 minutes if you use an API key or usage credits, and 1 hour if you use a subscription within its usage limits. We measured pauses of 2 to 13 minutes on the 5-minute cache. (does this apply to you?)
Three habits that avoid paying for a cache rebuild. Paste them into your terminal or Claude Code prompt and edit the details.
claude -p session every run and pass state in through a notes file, instead of resuming an old session./compact and tell it what to keep, so the session is small when you return./clear, then give a 3-line reminder (Goal, Done, Next).# Cron and CI: start a new session every run, and keep notes in a file
claude -p "$(cat .agent/handoff.md) Continue the nightly triage." --output-format json
# Before a break
/compact Keep: the open issue, files touched, test command
# Back after a break, new task
/clear
Goal: fix the currency rounding in invoices.
Done: tests in tests/test_invoice.py reproduce it.
Next: patch money.py, run the suite.
Careful with CLAUDE_AUTOCOMPACT_PCT_OVERRIDE. On a 1M-context model, 25 fires at about 245,000 tokens, which is reasonable. On a 200k-context model it fires at 45,000, below what a summary leaves behind, and the session thrashes (+239% in our model). In T3 Code it stacks with "Auto-compact after", so set only one of the two. (details)
T3 Code can compact before a break for you. Its idle-thread setting has three modes: "When you return" (the default, onReturn), "Before the cache expires" (beta, beforeCacheExpires), and "Never". "When you return" compacts after the cache has already expired, so you pay the rebuild anyway. "Before the cache expires" compacts an idle thread while the cache is still warm, which is the automatic version of /compact before a break. Not measured in this study yet.
See your cache. /usage shows a Prompt cache (main) line: warm, with its time limit and the time since your last turn, or cold. You can also show the time since your last turn in your status line. Community mods that