llmlean

A Python CLI that scans a local codebase and produces an actionable token-efficiency report. Helps developers reduce token usage in LLM-assisted development sessions (Claude Code, Cursor, Copilot, etc.).

Works fully offline — no API calls, no network required.

Install

uv tool install llmlean

Or run directly from the repo:

uv run llmlean scan .

Usage

llmlean scan [path]          # scan a directory (default: cwd)
llmlean scan [path] --json   # machine-readable JSON output
llmlean init [path]          # write .llmignore + AGENTS.md stubs

Example output

llmlean report — /my/project — 42 files scanned

  [PASS] LLM ignore file present       100
  [PASS] Agent context file present    100
  [WARN] Large files (>300 lines)       70   3 file(s) over 300 lines
  [PASS] Dead imports                  100
  [FAIL] Deep nesting (>4 levels)       22   35 line(s) with nesting depth > 4
  [WARN] Large functions (>50 lines)    44   7 function(s) over 50 lines
  [PASS] Binary/generated files         100

  Overall score: 76

--- deep_nesting ---
  src/app/routes.py:187  depth 5
  src/app/routes.py:203  depth 6
  ...

  Run `llmlean init` to generate .llmignore and AGENTS.md stubs.

Checks

ID	What it flags
large_files	Source files over 300 lines
no_llmignore	Missing .llmignore or .claudeignore at project root
no_agents_md	Missing AGENTS.md, CLAUDE.md, or CURSOR_RULES at root
dead_imports	Python imports that are never used (via ast)
deep_nesting	Code indented more than 4 levels deep
large_functions	Functions/methods over 50 lines
binary_or_generated	Lock files, .pyc, .min.js, .map, migration files not gitignored

Scores are 0–100. PASS ≥ 80, WARN ≥ 40, FAIL < 40.

Initialise a project

llmlean init .

Creates two files if they don't exist:

• .llmignore — gitignore-style file telling LLM tools what to skip
• AGENTS.md — template for documenting your project's stack, conventions, and file map

JSON output

llmlean scan . --json

{
  "path": "/my/project",
  "files_scanned": 42,
  "overall_score": 76,
  "checks": [
    { "id": "large_files", "label": "Large files (>300 lines)", "score": 70, "finding": "3 file(s) over 300 lines", "files": [...] }
  ]
}

Requirements

• Python 3.10+
• pathspec (installed automatically)