claude-lean
Get 5× more from your Claude Code token budget.
Audit, trim, and switch context profiles per project — without touching Claude Code itself.
Why
By default, Claude Code loads every enabled plugin's metadata into your context on every turn. For a fresh install with the default plugin set, that's often 500,000+ tokens of agent descriptions, skill metadata, and MCP preambles — regardless of whether you ever invoke them.
The result: shorter conversations before compaction, slower responses, higher cost, and a tax on multi-agent workflows. claude-lean makes that hidden cost visible — and gives you four levers to reclaim it.
The Four Levers
┌──────────────────────────────────────────────────────────────────┐
│ │
│ 1. AUDIT → See exactly what's eating your context │
│ 2. APPLY → Disable what you don't use (with backup) │
│ 3. PROFILE → Different active set per project / cwd │
│ 4. RESTORE → One command back to any previous state │
│ │
└──────────────────────────────────────────────────────────────────┘
Quick Start
# Install (zero hard dependencies beyond rich, which most setups have)
pipx install claude-lean
# 1. See what's costing you
claude-lean audit
# 2. Apply recommendations interactively (with diff + backup + dry-run safety)
claude-lean apply
# 3. Switch to a focused profile in a specific project
cd ~/my-python-project
claude-lean profile use python-ml
# 4. Undo anything
claude-lean restore --latest
Real Numbers From a Real Setup
A representative audit on a default-everything install:
───────────────────────── claude-lean audit ─────────────────────────
Plugins enabled: 20 · Skills: 262 · Agents: 18
Estimated system-prompt overhead per turn: 593,122 tokens
Top contributors (tokens / turn):
engineering-advanced-skills 129,302 ✓ keep
engineering-skills 123,232 ✓ keep
marketing-skills 111,126 ⚠ disable (no marketing work)
c-level-skills 68,660 ⚠ disable (no exec work)
ra-qm-skills 44,325 ⚠ disable (no regulatory work)
17 findings · Estimated savings if applied: 298,283 tokens / turn
≈ 2.0× more headroom
With per-project profiles (level 3 above), that 2.0× compounds to 5×+ by loading only the plugins relevant to that project's stack.
How It Works
claude-lean is a standalone Python CLI, not a Claude Code plugin. It runs outside Claude Code and operates on the plain files in ~/.claude/. Because it never loads into your prompt context, it costs zero tokens per Claude conversation.
┌─────────────────────────────────┐
│ claude-lean CLI │
│ (runs in your terminal) │
└────────────────┬────────────────┘
│ reads / writes
▼
┌─────────────────────────────────┐
│ ~/.claude/ │
│ • CLAUDE.md │
│ • settings.json │
│ • plugins/cache/ │
│ • projects/*/memory/ │
└─────────────────────────────────┘
See docs/how-it-works.md for the full architecture.
Safety
- Every write creates a backup first to
~/.claude/.claude-lean-backups/{timestamp}/ - Dry-run is the default for non-TTY usage — pipes don't accidentally mutate state
claude-lean restore --latestreverts the most recent change in one command--listshows every snapshot you've ever made
See docs/safety.md for the full safety model.
Documentation
| Doc | Purpose |
|---|---|
| Getting Started | First-time setup, install, the audit→apply loop |
| How It Works | Architecture, the four subsystems, data flow |
| Safety | Backup, restore, dry-run, what we never touch |
| FAQ | Common questions, troubleshooting, limitations |
Commands
| Command | What it does |
|---|---|
claude-lean audit |
Scan ~/.claude/, report opportunities (read-only) |
claude-lean audit --json |
Machine-readable output |
claude-lean apply |
Interactive wizard, applies recommendations with diff + backup |
claude-lean apply --dry-run |
Show what would change without writing |
claude-lean apply --yes |
Skip interactive prompt (still respects --dry-run) |
claude-lean profile list |
Show installed profiles |
claude-lean profile show <name> |
Print a profile's contents |
claude-lean profile use <name> |
Apply a profile (with backup + diff) |
claude-lean restore --latest |
Revert the most recent change |
claude-lean restore --list |
List all snapshots |
Status
v0.1.0 — alpha. The core (audit, apply, restore, profile) is working and tested. The following are roadmapped for later versions:
- v0.3 —
claude-lean monitor(live token-usage dashboard from session logs) - v0.4 — Claude Code hooks integration (auto-switch profile on
cd) - v1.0 — Profile marketplace + community-contributed profiles
License
MIT — see LICENSE.
Contributing
Issues and PRs welcome. Per-project profiles are intentionally easy to contribute — drop a TOML file in src/claude_lean/profile/stock/, add a test, ship a PR.
Metadata
Release files for claude-lean 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| claude_lean-0.1.0.tar.gz | 47.7 kB | Without provenance | Details for claude_lean-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| claude_lean-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for claude_lean-0.1.0-py3-none-any.whl |
Total release size: 83.6 kB
Release files / claude_lean-0.1.0.tar.gz
| Download URL | claude_lean-0.1.0.tar.gz |
|---|---|
| Size | 47.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5ab8afd4dd013de6710615aa4bd2d1f4b4a3000251354c1f233f7dde190608c0
|
|
BLAKE2b-256 checksum How to use checksums |
2ecbbc74d8bf51329f1201629cc76aaed502c4b8d8f9b84b7d1f4a1cbcdad68e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.12
|
Release files / claude_lean-0.1.0-py3-none-any.whl
| Download URL | claude_lean-0.1.0-py3-none-any.whl |
|---|---|
| Size | 35.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3f598616e8f3aa0d171724e166fd9a60c4a8efbefdfc33b5ff508867eeb17966
|
|
BLAKE2b-256 checksum How to use checksums |
7a1d1d21f0dc152fc8341b578df70865d3911517e9096fdc3018631894dd4504
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.12
|
Security for claude-lean 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.