/claude-slim

See it in action

Where the bloat hides — measured on one real install:

Skill listings are the part people underestimate: each installed skill contributes one - name: description line to the system prompt, and those run anywhere from 30 to 509 tokens each. Sixty terse skills and sixty verbose ones are not the same bill.

That's slower responses. Hitting your usage cap faster. Paying for context you're not using — on every turn, of every session.

One command. Five steps.

/claude-slim

 ┌────────┐   ┌──────────┐   ┌─────────┐   ┌─────────┐   ┌────────┐
 │  Scan  │ → │ Classify │ → │ Propose │ → │  Clean  │ → │ Report │
 │        │   │          │   │         │   │         │   │        │
 │measure │   │ broken   │   │  you    │   │ move to │   │before  │
 │ every  │   │ dupes    │   │ choose  │   │.disabled│   │  vs    │
 │source  │   │ bloat    │   │  what   │   │  dir    │   │ after  │
 └────────┘   └──────────┘   └─────────┘   └─────────┘   └────────┘

Scan — Measures everything: local skills, plugin skills, CLAUDE.md, memory files, MCP servers. Token counts are measured with js-tiktoken, not guessed.

Classify — Finds the waste automatically:

Propose — Three tiers, you decide:

Clean — Moves selected skills and project memory to ~/.claude/skills.disabled/. Failed-install temp caches and dead symlink files are the only permanent cleanups, and they are labeled before selection.

Report — Shows exactly what changed:

╭────────────────────────────────────────╮
│  claude-slim report                    │
│                                        │
│  Before: 14,510 tokens at startup      │
│  After:   5,181 tokens at startup      │
│  Saved:   9,329 tokens (64.3%)         │
│                                        │
│  Top offenders removed:                │
│  • office-hours              23,008 tok│
│  • harness                    7,902 tok│
│  • manpower                   4,764 tok│
│                                        │
│  Est. monthly savings: ~$1.68          │
│  (2 sessions/day × $0.003/1K tok)      │
╰────────────────────────────────────────╯

  ┌──────────────────┬──────────┬──────────┬────────────┐
  │                  │  Before  │  After   │  Saved     │
  ├──────────────────┼──────────┼──────────┼────────────┤
  │ Local skills     │    14    │     4    │  -10       │
  │ System prompt    │   ~124   │   ~114   │  -10       │
  │ Memory files     │  19.5KB  │   5.7KB  │  -13.8KB   │
  │ Est. tokens      │ ~14,510  │  ~5,181  │  ~9,329    │
  └──────────────────┴──────────┴──────────┴────────────┘

Try it (10 seconds)

No install needed — run once and see what's in your ~/.claude/:

npx claude-slim scan

Happy with what you see? Make it part of your Claude Code workflow:

claude plugin marketplace add iops-leo/claude-slim
claude plugin install claude-slim

Then just type /claude-slim in any session.

Or install it through the skills.sh directory, which can also place the skill into Codex, Cursor, and OpenCode. What claude-slim analyzes is unchanged: ~/.claude/ and ~/.codex/.

npx skills add iops-leo/claude-slim

Usage

/claude-slim                          # Full pipeline: scan → propose → clean → report
/claude-slim scan                     # Report only, no changes
/claude-slim scan --json              # Machine-readable JSON output
/claude-slim scan --lookback-days 30  # Treat skills idle for 30+ days as unused
/claude-slim scan --project-dir PATH  # Count PATH's project memory (default: cwd)
/claude-slim doctor                   # Check scanner prerequisites and data fidelity
/claude-slim check-update             # Is a newer version published?
/claude-slim restore                  # Bring back anything you disabled

CLI equivalents:

npx claude-slim clean                    # Full pipeline
npx claude-slim clean --dry-run          # See what would happen (no changes)
npx claude-slim clean --auto             # Non-interactive, Tier 1 only (CI/scripts)
npx claude-slim clean --lookback-days N  # Tune the unused-skill detection window
npx claude-slim scan                     # Report only
npx claude-slim scan --no-codex          # Skip the ~/.codex scan
npx claude-slim doctor                   # Diagnose Node/Claude/session-log readiness
npx claude-slim doctor --offline         # Same, without the version check (no network)
npx claude-slim check-update             # Report-only version check
npx claude-slim update                   # Run the upgrade for this install method
npx claude-slim restore                  # Undo
npx claude-slim report                   # Show savings from last clean

Staying current

An outdated claude-slim doesn't just miss features — it reports wrong numbers. Versions before 2.8.0 inflated the startup estimate roughly 8×, and nothing told you that you were behind.

doctor now compares your installed version against npm and prints the upgrade command for how you actually installed it:

! Version: 2.0.0 installed, 2.8.1 available
    Outdated versions report wrong token totals. Update with:
    claude plugin marketplace update claude-slim && claude plugin update claude-slim@claude-slim

claude-slim never updates itself — that's your package manager's job, and writing into a directory claude plugin owns is how installs get corrupted. It only tells you. The check is the tool's only outbound request, is skipped with --offline, caches for 24h, and fails open when you're offline.

Safety first

What claude-slim never touches

• ~/.claude/CLAUDE.md — your system instructions, read-only.
• ~/.claude/settings.json — MCP server config, hooks, and any other settings. Read-only.
• ~/.claude/agents/ and ~/.claude/commands/ — measured and reported since v2.8, never moved or deleted. There is no restore path for them yet, and a destructive action without its undo isn't worth shipping.
• Plugin internals (~/.claude/plugins/config.json, individual plugin.json files) — left alone; use claude plugin to manage plugins.
• Git / project sources — claude-slim only looks inside ~/.claude/, never at your code.
• ~/.codex/ — scanned and, since v2.11, cleanable under the same tiers. Moves go to ~/.codex/skills.disabled/ and reverse with restore. The path guard is per-agent, so a Codex item can never resolve into ~/.claude/. Unused-skill detection is still not offered there: Codex session logs record the skill catalog, not invocations, so there is no honest usage signal to act on.
• Anything outside ~/.claude/ — a path-containment guard refuses destructive ops anywhere else, even if a tampered manifest asked it to.

Only touched: entries under ~/.claude/skills/, ~/.claude/plugins/cache/temp_local_*, and ~/.claude/projects/*/memory/. Skill and memory entries are moved to skills.disabled/; broken symlink files are unlinked and temp_local_* failed-install caches are removed outright.

How it works

claude-slim scans these locations. No plugin-specific logic — pure filesystem analysis.

~/.claude/
├── skills/                  ← user-installed skills
├── plugins/cache/           ← plugin skills, agents, commands, MCP servers
├── agents/                  ← user agents (measured, read-only)
├── commands/                ← user slash commands (measured, read-only)
├── CLAUDE.md                ← system instructions (read-only)
├── projects/*/memory/       ← auto-memory files (current project counts toward startup)
└── settings.json            ← MCP server count (read-only)

Works with any setup: OMC, gstack, marketplace plugins, custom skills, or vanilla Claude Code.

Real-world results

From a real cleanup session:

A note on the numbers

claude-slim reports what a session in this directory pays. Memory is per-project — Claude Code loads ~/.claude/projects/<slug>/memory/ for the project you're in, not every project on disk — so running scan from two different repos will legitimately give you two different totals.

Token counts come from js-tiktoken against the actual file contents. The only estimates left are marked with ~: MCP tool schemas (~8 tokens/tool) and skills whose frontmatter can't be parsed (~30 tokens). Everything else is measured.

v2.13.1 — What's new

• Fixed: scan promised the tool never touches ~/.codex/, while clean --auto deletes from it permanently. The Codex summary closed with Reported only — claude-slim never modifies ~/.codex/. That was true in v2.10 and false from v2.11 on, when clean gained the Codex tiers. Measured here: clean --dry-run selects [Auto] [codex] temp_cache: .tmp (146MB of install leftovers) (permanent) — Tier 1, which --auto applies without prompting and no restore undoes.
• The summary now says what actually happens: scan only reads, clean acts under the same tiers as ~/.claude/, moves land in ~/.codex/skills.disabled/ and reverse with restore, and Tier 1 install leftovers are deleted permanently.

A test was holding the false claim in place. It asserted the summary must say "never modifies", so the line could not be corrected without a test failing — and all 461 tests stayed green across four releases that contradicted it. The assertion is now inverted: the summary must not promise ~/.codex/ is left alone, and must name the permanent deletion and --auto.

Tests: 461 → 462.

For older release notes, see CHANGELOG.md.

Requirements

• Node.js 20+
• macOS or Linux
• Claude Code CLI

License

MIT