⚡ debloat

Claude Code loads dozens of skills into your context every session — and most you've never used. debloat reads your real usage, finds the skills that never fire, and cuts them. Reversibly. Lighter context, every session.

Quick start

One command, zero install:

npx debloat

It shows what's costing you, recommends a safe cut (based on which skills have actually fired in your session logs), lets you choose how deep to go, and reports what you reclaimed — all reversible with skills --enable.

Why care

Every always-loaded token brings compaction closer and competes with your actual work for the model's attention. Most setups accrete this invisibly — old memory entries, skills you installed once, rules files you forgot.

• See the bill — everything loaded before you type: system prompt, CLAUDE.md, memory, skills, agents.
• Evidence, not vibes — usage comes from your real session logs, not guesses.
• Cut safely — disabled skills move to a folder, never deleted. Restore with one command.
• Find dead weight — files you think are loaded that aren't (AGENTS.md is ignored unless @imported).
• Scriptable — --json output and --budget exit codes for CI.

⭐ Reclaimed some tokens? A star helps the next cluttered setup find this.

See the whole bill

Trimming skills is the actionable part. To see everything loaded before you type, run the plain receipt:

npx debloat receipt

 CONTEXT RECEIPT                     claude code · debloat
 2026-07-24 18:03

 ⚡ 19.9k tokens loaded every session before your first word
 10% of a 200k context window

 BREAKDOWN
 claude code system prompt         ███████████████   ~6.2k
 built-in tool schemas             ███████████       ~4.7k
 skill listing, user (76 skills)   ███████            3.0k
 skill listing, plu…ns (34 skills) ██████             2.3k
 CLAUDE.md (global)                ████               1.5k
 CLAUDE.md (Github-Wiki)           ███                1.3k
 agent listing, user (10 agents)   █                   407
   … 3 more                                            486

 itemized                                            19.9k

 DEAD WEIGHT — on disk, NOT loaded
   ../../../../AGENTS.md                        5.3k chars
     ignored unless @imported from CLAUDE.md

 MCP, loads on use: supabase, gbrain

 ~5.3k of it is skill listings  ·  trim: npx debloat

 note: no auto-memory found for this project path
 * chars÷4 estimate · reconcile with /context

skills — cost vs usage, and disable what you never run

The receipt tells you skills cost tokens every session. It doesn't tell you which to cut. skills does, by reading your actual usage out of the session logs:

npx debloat skills            # print the cost-vs-usage table
npx debloat skills --pick     # recommend a safe cut, then one y/n

--pick shows your token burn as before/after bars (context now vs. after the cut), lists exactly which never-invoked skills it recommends disabling (excluding safety rails like git-safety that fire on their own), and asks a single yes/no. Nothing is cut sight-unseen, and nothing is deleted.

 SKILLS — startup cost vs actual usage (user scope)
 tokens = est. context each skill adds to EVERY session (chars÷4)
 ──────────────────────────────────────────────────────
 NEVER INVOKED — never run       tokens  last used
 here-now                           194  never
 codeql                             115  never
 second-opinion                      66  never
 git-safety                          61  never
   …
 ACTIVELY USED — keep            tokens  last used
 resume-studio                      166  9d ago
 glowup                             162  3d ago
 resume-worded                      140  7d ago
 fertility-tracker                  110  4d ago
   …
 ──────────────────────────────────────────────────────
 54/76 never invoked · ~1.6k tokens off every session if cut
 note: some never-run skills are safety rails you may want to keep — you decide
 disable (reversible):  debloat skills --disable <name> [<name>...]
 restore any time:      debloat skills --enable <name>

Usage is real, not guessed: it counts Skill-tool calls and slash-command invocations across ~/.claude/projects/**/*.jsonl. "Never invoked" is evidence, not a verdict — a safety skill you keep loaded may rarely fire, so you decide, not the tool.

Disabling is reversible and never deletes: chosen skills move to ~/.claude/skills-disabled/. Restore any time:

npx debloat skills --disable here-now design-consultation
npx debloat skills --enable here-now

Some skills are load-bearing even when they look unused. A skill bundle ships one small top-level SKILL.md, so it reads as a tiny never-invoked skill while dozens of installed skills symlink into its directory — moving it would break every one of them. debloat counts what resolves into a directory before recommending anything, keeps those out of the recommendation regardless of usage, and refuses to disable them:

  kept  gstack — 55 other skills resolve into it; moving it would break them
        override with: debloat skills --disable gstack --force

explain — which instructions apply to one file

/context tells you what's loaded now. It can't tell you which instructions apply when Claude touches a specific file:

npx debloat explain GitHub/glowup/SKILL.md

 GitHub/glowup/SKILL.md
 inherits 5 instruction layers (~3.3k tokens est)

 1. CLAUDE.md (global)  [1.5k]
    always (startup)
 2. rules/code-structure.md (global)  [264]
    always (startup)
 3. rules/no-silent-catches.md (global)  [91]
    always (startup)
 4. rules/vue-conventions.md (global)  [131]
    always (startup)
 5. CLAUDE.md (Github-Wiki)  [1.3k]
    always (startup)

 note: Claude Code loads all applicable layers simultaneously.
 There is no enforced precedence — nearer files win by convention only.

It resolves the global + project CLAUDE.md chain, nested per-directory CLAUDE.md files (which load lazily), and one level of @imports — then flags headings that appear in more than one layer, since those are where contradictory rules hide. Claude Code loads all applicable layers simultaneously; there is no enforced cascade, so explain reports layers and overlaps rather than pretending a precedence engine exists.

Isn't this just /context?

/context is the ground truth inside a live session — use it. debloat is for what /context can't do: it works without opening a session, it knows which skills you've actually invoked (from your session logs), and it does the cut for you. Run both — the receipt should land within ~8% of /context's total.

All commands

npx debloat                  # interactive trimmer (on a terminal)
npx debloat receipt          # the full itemized receipt
npx debloat receipt ~/proj   # receipt for another project
npx debloat skills           # cost-vs-usage table
npx debloat skills --pick    # recommended cut, one y/n
npx debloat explain <file>   # instruction layers for one file
npx debloat --json           # write debloat.json (diffable, CI-able)
npx debloat --budget 30000   # exit 1 if the estimate exceeds the budget

# Piped, scripted, or agent-run? The bare command prints the static receipt —
# it never prompts without a keyboard.

Method, honestly

• Static scan of the same files Claude Code reads: the global and project CLAUDE.md chain (walking up from the project directory), ~/.claude/rules/, one level of @imports, the project's auto-memory MEMORY.md, skill frontmatter (name + description are listed in context at startup), and agent frontmatter.
• Token counts are estimates (chars ÷ 4). Reconcile against /context inside a live session — that's the ground truth this tool approximates without needing a session.
• The Claude Code base system prompt and built-in tool schemas can't be derived statically; they're included as constants measured via /context on v2.1.215.
• Calibration: on the author's setup the static estimate landed ~17% under the live /context total (22.5k estimated vs 27.2k measured). Treat the receipt as a floor — your real bill is higher.

Roadmap

• Real tokenizer, /context auto-reconciliation
• debloat diff between two receipts (did that PR add 4k always-loaded tokens?)
• Usage-aware pruning for agents and plugin skills too
• Codex CLI, Cursor, Gemini CLI receipts

License

MIT. One file, zero dependencies — free to use, copy, and make yours.

Built by Kat Laszlo · a star helps other cluttered setups find this