claude-lean 0.1.0__tar.gz

claude_lean-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Linting / type checking
+.ruff_cache/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+
+# Backups (claude-lean's own backups during dev)
+.claude-lean-backups/
+
+# Local
+*.local
+.env

claude_lean-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vipin <contact@buffercode.in>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_lean-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: claude-lean
+Version: 0.1.0
+Summary: Get 5x more from your Claude Code token budget — audit, trim, and switch context profiles per project.
+Project-URL: Homepage, https://github.com/vipin/claude-lean
+Project-URL: Repository, https://github.com/vipin/claude-lean
+Project-URL: Documentation, https://github.com/vipin/claude-lean#readme
+Project-URL: Issues, https://github.com/vipin/claude-lean/issues
+Author-email: vipin <contact@buffercode.in>
+License: MIT
+License-File: LICENSE
+Keywords: anthropic,claude-code,context,optimization,tokens
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: rich>=13.0.0
+Provides-Extra: accurate
+Requires-Dist: tiktoken>=0.5.0; extra == 'accurate'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# `claude-lean`
+
+**Get 5× more from your Claude Code token budget.**
+
+*Audit, trim, and switch context profiles per project — without touching Claude Code itself.*
+
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org)
+[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange)](#status)
+
+</div>
+
+---
+
+## 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
+
+```bash
+# 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](./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 --latest`** reverts the most recent change in one command
+- **`--list` shows every snapshot** you've ever made
+
+See [docs/safety.md](./docs/safety.md) for the full safety model.
+
+## Documentation
+
+| Doc | Purpose |
+|---|---|
+| **[Getting Started](./docs/getting-started.md)** | First-time setup, install, the audit→apply loop |
+| **[How It Works](./docs/how-it-works.md)** | Architecture, the four subsystems, data flow |
+| **[Safety](./docs/safety.md)** | Backup, restore, dry-run, what we never touch |
+| **[FAQ](./docs/faq.md)** | 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](./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.

claude_lean-0.1.0/README.md

@@ -0,0 +1,148 @@
+<div align="center">
+
+# `claude-lean`
+
+**Get 5× more from your Claude Code token budget.**
+
+*Audit, trim, and switch context profiles per project — without touching Claude Code itself.*
+
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org)
+[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange)](#status)
+
+</div>
+
+---
+
+## 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
+
+```bash
+# 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](./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 --latest`** reverts the most recent change in one command
+- **`--list` shows every snapshot** you've ever made
+
+See [docs/safety.md](./docs/safety.md) for the full safety model.
+
+## Documentation
+
+| Doc | Purpose |
+|---|---|
+| **[Getting Started](./docs/getting-started.md)** | First-time setup, install, the audit→apply loop |
+| **[How It Works](./docs/how-it-works.md)** | Architecture, the four subsystems, data flow |
+| **[Safety](./docs/safety.md)** | Backup, restore, dry-run, what we never touch |
+| **[FAQ](./docs/faq.md)** | 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](./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.

claude_lean-0.1.0/docs/faq.md

@@ -0,0 +1,142 @@
+# FAQ
+
+## General
+
+### Why a separate CLI instead of a Claude Code plugin?
+
+Because a plugin's metadata loads into Claude's context every turn — including the metadata of the plugin that's supposed to *save* you tokens. Putting `claude-lean` *outside* Claude Code means it costs zero tokens per conversation. The optimization is purely build-time.
+
+### Is the "5×" claim real?
+
+For a default-everything install on the most popular plugin packs, yes. The breakdown:
+
+| Lever | Approx. saving |
+|---|---|
+| Disabling 7-10 truly unused plugin packs | ~45% |
+| Rewriting forcing rules in CLAUDE.md | ~10% |
+| Memory hygiene | ~5% |
+| `settings.json` permission allowlist | ~8% |
+| **Subtotal (audit + apply)** | **~2.0-2.5×** |
+| Per-project profiles | ~35% |
+| Hooks (auto-switch on cd, v0.4) | ~25% |
+| **Subtotal (with profiles + hooks)** | **~5.0×** |
+
+The first row of numbers (the 2.0-2.5× tier) is what v0.1 ships. The 5× target is end-of-roadmap, with profiles and hooks.
+
+If you've already trimmed your setup manually, the savings will obviously be less — `claude-lean` measures, then suggests; it doesn't make magic numbers up.
+
+### Does this work without `tiktoken` installed?
+
+Yes. The fallback is a byte-based approximation (1 token ≈ 4 bytes). The *order* of plugins by cost is the same — only the absolute numbers differ. If you want exact counts, `pipx install 'claude-lean[accurate]'`.
+
+### Will Anthropic eventually fix the underlying issues?
+
+Probably some of them — and that would be great, the tool would gracefully sunset. The roadmap is built so that even if Anthropic ships lazy plugin loading tomorrow, the per-project profile feature still adds value.
+
+## Setup
+
+### What Python versions are supported?
+
+3.11+. We need `tomllib` (3.11 stdlib) for profile parsing.
+
+### Why `pipx` over `pip`?
+
+`pipx` installs CLI tools into isolated environments, which is the right answer for end-user CLIs. `pip install --user` works too but can clash with other Python tools.
+
+### Does it work on Windows?
+
+Not tested. macOS and Linux only for v0.1. Windows support is on the roadmap; the path encoding logic just needs to handle backslashes.
+
+### Where does `claude-lean` look for `~/.claude/`?
+
+In order:
+1. `--claude-home <path>` CLI flag
+2. `$CLAUDE_HOME` environment variable
+3. `~/.claude` (the default)
+
+## Using It
+
+### What if I disable a plugin and later need it?
+
+`claude-lean restore --latest` reverts the most recent `apply`. Or just toggle the plugin back to `true` in `~/.claude/settings.json` — that's all `apply` actually changes.
+
+### Can I add my own anti-pattern rules?
+
+Not in v0.1 — rules are hard-coded. v0.2 will support a `~/.claude/claude-lean-rules.py` for user rules. You can fork the repo today and add a rule under `src/claude_lean/audit/rules/`; PRs welcome.
+
+### Can I run this in CI?
+
+Yes. `claude-lean audit --json-out audit.json` is non-interactive and produces a stable JSON output. You can fail builds on regression by parsing the result.
+
+### What does "estimated savings" actually mean?
+
+The tokens that would no longer load into Claude's system prompt if you applied the recommendation. It's a forward-looking estimate — measured against the static configuration, not against a specific conversation.
+
+## Profiles
+
+### Where do stock profiles live?
+
+In the installed package: `src/claude_lean/profile/stock/*.toml`. They're bundled with the wheel.
+
+### Can I make a custom profile?
+
+Yes. Copy one of the stock profiles, edit it, save it locally, and pass the path to `profile use` (custom-path support is a v0.2 feature; for v0.1, drop your custom profile into the stock directory and reinstall — clunky but works).
+
+### What about a marketplace?
+
+v1.0. Community profiles will live in a separate repo (`claude-lean-profiles`) and be installable via `claude-lean profile install`. Roadmap.
+
+### Will profiles conflict with `apply`?
+
+A profile is just a more aggressive `apply` — it's all writes to `settings.json` and `CLAUDE.md`. They both go through the same backup system. Running `apply` after `profile use` is a no-op if the apply recommendations are already covered by the profile.
+
+## Memory
+
+### Why doesn't `claude-lean` auto-fix my memory files?
+
+Memory rewriting is risky because memory content is policy + personal context. v0.1 only *reports*. v0.2 will add `apply --rewrite-memories` behind an explicit opt-in flag.
+
+### What's the 200-line cap?
+
+Claude Code's harness truncates `MEMORY.md` after 200 lines. Memories referenced beyond that line are silently invisible. The `memory-index-near-cap` rule warns when you're approaching it.
+
+### Why are my memory descriptions flagged as "vague"?
+
+Because Claude uses the description as the only signal for whether to *load* the memory body. A description like "notes" doesn't match any topic, so the memory body never gets loaded. Aim for 60+ characters mentioning the topic, constraint, or fact.
+
+## Troubleshooting
+
+### "Claude Code home not found at /Users/you/.claude"
+
+Either your install is at a non-default location (use `--claude-home`), or you haven't run `claude` yet to initialize it.
+
+### Audit reports "Agents: 0" but I know I have agents
+
+Agents must live under an `agents/` directory inside a plugin. If your agents are at `~/.claude/agents/`, that's the global-agent location and v0.1 doesn't scan it yet (v0.2 will).
+
+### "Estimated savings" looks way too high
+
+Without `tiktoken`, the byte-based estimate over-counts on text-heavy content. The relative order is still correct; install the `accurate` extra for exact numbers.
+
+### Rich output is garbled in my terminal
+
+`rich` auto-detects terminal capabilities. If output looks weird, try `--json` (machine-readable) or set `TERM=dumb` for plain text.
+
+### Tests fail after `pip install`
+
+Make sure you installed with the `dev` extra:
+
+```bash
+pip install -e '.[dev]'
+pytest
+```
+
+## Privacy
+
+### Does `claude-lean` send any data anywhere?
+
+No. Every operation is local. The optional `profile install` from a marketplace (v1.0) is opt-in and shows you what URL it fetches from.
+
+### What's logged?
+
+Nothing by default. The `monitor` subcommand (v0.3) will *read* `~/.claude/projects/*/` session logs (which Claude Code already writes), but nothing is sent outside your machine.