lean-context

A tiny, drop-in context optimizer for OpenAI Codex, Claude Code, and Google Antigravity.

It does not change model pricing. It reduces avoidable context consumption by giving coding agents a small project map and a shared set of context-discipline rules, so they can search narrowly instead of repeatedly scanning large repositories.

npx lean-context init . --chat

Measured impact

Benchmarked with an A/B harness that runs the same coding-agent task twice — once against a clean baseline, once with lean-context installed — alternating order across repeated runs on a real cross-file bug-fix task:

| | Baseline | With lean-context | Change | | --- | ---: | ---: | ---: | | Total tokens | 537,233 | 485,589 | −9.6% | | Agent wall time | 34.3s | 30.2s | −11.9% | | Cost per run | $0.2062 | $0.1945 | −5.7% | | Task pass rate | 100% | 100% | no change |

n=10 runs per side (20 total), one task/repo/model, Claude Code + Sonnet. This is the number worth trusting: smaller samples on the same task swung anywhere from 4.6% to 25.2% run to run — noise from the model's own stochastic tool-use choices, not the tool. Token savings are workload-dependent and this task has a modest ceiling (one shared helper to locate, in a modest-sized repo) — see Important caveat. What moves the needle: recognizing shared-logic files (lib/, utils/, helpers/) as high-signal in the generated project map, and auto-loading that map as always-on context for Claude Code so the agent doesn't have to remember to check it before reaching for a repo-wide search.

Version 0.4 adds a key symbols index, oversized data-file exclusion, shared-logic file detection, and an auto-loaded project map for Claude Code, on top of the saved token usage reports (v0.3) and optional chat-native skills (v0.2). After one setup command, Claude Code, Codex, and Antigravity can run lean-context from their own chat panels without you opening a terminal.

Why this design

Large always-loaded instruction files consume context themselves. lean-context therefore uses two layers:

1. A very small always-on protocol in AGENTS.md / CLAUDE.md.
2. On-demand Agent Skills and a generated project map that are only loaded when needed.

• Codex reads AGENTS.md and repo skills from .agents/skills/.
• Claude Code reads CLAUDE.md and project skills from .claude/skills/.
• Antigravity recognizes workspace AGENTS.md and Agent Skills under .agents/skills/.

The managed protocol tells agents to search before reading, avoid generated/lock/vendor files, use targeted commands, and keep tool output narrow.

Recommended setup: terminal + chat

Run this once from the project you want to optimize:

npx lean-context init . --chat

That installs the normal low-token context layer and chat commands for the coding agents.

If lean-context was already initialized without chat support, add chat support later with:

npx lean-context chat .

To try unreleased changes straight from GitHub instead of the published npm package, swap lean-context for github:jaymac95/lean-context in any command below.

Run it directly from agent chats

Claude Code extension — VS Code or compatible host

Type in the Claude chat:

/lean-context

That uses smart mode. You can also run:

/lean-context refresh
/lean-context check
/lean-context stats
/lean-context report
/lean-context init

Claude's project skill is stored at:

.claude/skills/lean-context/SKILL.md

It is configured for explicit invocation only, so Claude does not automatically load the full skill on unrelated tasks.

Codex extension — VS Code or compatible host

Type in the Codex chat:

$lean-context

Or use /skills and select Lean Context. Actions can be appended:

$lean-context refresh
$lean-context check
$lean-context stats
$lean-context report
$lean-context init

Codex loads the shared skill from:

.agents/skills/lean-context/SKILL.md

Its agents/openai.yaml disables implicit invocation, so the skill only runs when you deliberately call it.

Antigravity Agent chat

Type:

/lean-context

or:

/lean-context refresh
/lean-context check
/lean-context stats
/lean-context report
/lean-context init

Antigravity uses the same shared Agent Skill under .agents/skills/lean-context/.

What smart mode does

smart is the default chat action:

1. Check whether .ai-context/project-map.md is current.
2. If stale, refresh it.
3. If state is missing/corrupt, repair initialization.
4. Print the approximate context footprint.

From a terminal the equivalent command is:

lean-context smart .

What gets created

With chat mode enabled:

YOUR_PROJECT/
├─ AGENTS.md
├─ CLAUDE.md
├─ .agents/
│  └─ skills/
│     └─ lean-context/
│        ├─ SKILL.md
│        └─ agents/
│           └─ openai.yaml
├─ .claude/
│  └─ skills/
│     └─ lean-context/
│        └─ SKILL.md
└─ .ai-context/
   ├─ project-map.md
   ├─ state.json
   ├─ .gitignore
   └─ tool/
      ├─ package.json
      ├─ bin/lean-context.js
      └─ lib/index.js

The .ai-context/tool/ copy is intentional. Chat skills call this local deterministic runner, so they do not need another network fetch or spend model tokens reimplementing the scan. lean-context excludes .ai-context/, .agents/, and .claude/ from its project fingerprint and navigation map.

Existing AGENTS.md and CLAUDE.md files are preserved. lean-context only owns the text between <!-- lean-context:start --> and <!-- lean-context:end --> markers.

CLI commands

| Command | Purpose | | --- | --- | | lean-context init [project] [--chat] | Add/update managed instructions, generate the map, optionally install chat skills | | lean-context chat [project] | Enable/refresh chat-native skills and the local runner | | lean-context smart [project] | Check, refresh only if needed, then show stats | | lean-context refresh [project] | Regenerate only the project map | | lean-context stats [project] | Show a rough chars/4 token estimate | | lean-context report [project] | Save a Markdown token usage/context report under .ai-context/reports/ | | lean-context check [project] | Exit non-zero when the map fingerprint is stale |

Generate a token usage report

Create a local report with:

npx lean-context report .

The report is saved under .ai-context/reports/ and includes project-map status, indexed file count, always-on instruction footprint, and on-demand skill/map footprint.

If Claude, Codex, Antigravity, or an API exposes actual usage numbers, attach them without mixing them into the estimates:

npx lean-context report . \
  --provider=codex \
  --model=gpt-5.3-codex \
  --input-tokens=18420 \
  --cached-input-tokens=12100 \
  --output-tokens=2380

You can also choose the report path with --output=reports/my-run.md. The report explicitly labels local characters ÷ 4 numbers as estimates rather than billing measurements.

From the agent chats, use /lean-context report in Claude/Antigravity or $lean-context report in Codex. If you include provider usage numbers in the request, the skill passes them to the local runner.

How it reduces waste

1. One canonical rule set instead of separately maintaining large Codex/Claude/Antigravity instruction files.
2. Small always-loaded instructions that act as a navigation protocol rather than a project encyclopedia.
3. Progressively loaded skills so maintenance instructions are not fully loaded on unrelated coding tasks.
4. Generated project map that records the stack, common commands, important files, and directory counts without embedding the whole source tree.
5. Noise filtering for dependencies, build output, caches, lockfiles, binaries, images, source maps, minified assets, and agent configuration folders.
6. Oversized data-file exclusion so fixtures/dumps/logs over 64KB (.json, .csv, .log, .sql, .xml, .yaml, .ipynb, …) are kept out of the index and flagged, instead of tempting an agent to read the whole thing.
7. Key symbols index listing top-level exports/definitions for high-signal files, so an agent can grep a known name instead of opening the file to find it.
8. Targeted exploration rules that ask the agent to search for symbols and open the smallest useful file slice.
9. Local deterministic chat runner so refresh/check/stats do not require the model to reconstruct the workflow.

Important caveat

Token savings are workload-dependent. Claude Code, Codex, and Antigravity have their own context management, caching, compaction, system instructions, tools, and billing rules. Measure real usage before and after where your provider exposes it.

Platform notes

• Claude Code skills can be invoked directly from chat and their bodies load only when used. The VS Code extension supports commands and skills, although the graphical extension exposes a subset of CLI commands.
• Codex standalone skills are available in the IDE extension. Repo-scoped skills are discovered from .agents/skills; explicit invocation is through $skill-name or the /skills selector.
• Antigravity skills under .agents/skills/<name>/SKILL.md support progressive context loading and slash-command invocation.

License

MIT