lcc — Local Context Compiler

Shrink what you send to the model. Keep every byte you didn't cut. Get a receipt.

lcc decides which parts of a context to send to a model and drops the rest. It works on documents, logs and agent transcripts: duplicates and boilerplate go, blocks that do not serve the objective are dropped or trimmed, and everything kept stays verbatim. Nothing is summarized or rewritten. Every pass writes a JSON report that says what was kept, trimmed or dropped, and why.

Why lcc

• Local. The default judges run on your CPU in plain Python. No API key, no network, no external model. The transcript ranker (specialist-v3) is a 183 KB file that ships in the package.
• Fast. A 300-block agent transcript compacts in about 0.2 s; the ranker alone takes about 0.1 s (benchmark).
• Auditable. Kept spans are byte-identical to the source, and lcc explain gives the reason for every drop.

Quick start

pip install "local-context-compiler[tiktoken]"   # the CLI is `lcc`

lcc compact notes.md -q "what is wrong with the booking flow?" \
  --provider mechanical -o compacted.md -r report.json
lcc explain report.json --source notes.md        # why each block was kept or dropped

Claude Code plugin. Replaces Claude Code's /compact summary with verbatim tool-call compaction, ranked locally by specialist-v3. Function hooks are early access, so the flag is required:

export CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1        # Claude Code 2.1.274+
claude plugin marketplace add lucasmartins-ai/lcc
claude plugin install lcc@lcc

When a pass fails or removes too little, the plugin hands back to the built-in summary. See the Claude Code guide.

MCP (Claude Code, Cursor, Claude Desktop, any stdio client):

{"mcpServers": {"lcc": {"command": "lcc", "args": ["mcp"]}}}

Tools: compact, compact_transcript, inspect, prepare, explain, intake (MCP guide).

Agent transcripts from the CLI:

lcc compact transcript.json -q "finish the parser fix" --mode tool-calls \
  -o compacted.json -r report.json

Providers

specialist-v3 details and limits: SPECIALIST.md. Rules modes: TOOL_CALLS.md. Jev is an optional path you name explicitly (--provider jev); it sends the objective and context blocks to the TypeSafe API, and LCC_DISABLE_NETWORK=1 disables it. compact writes a relevance-compaction-1.2 report; check provider_used and degraded before trusting the output.

Benchmarks

Real sessions (held-out, INFERIDO). A one-shot final test on 193 items from 36 of the maintainer's sessions that started after the training cutoff. Retention AUC over drop budgets of 0–60% of candidate tokens:

The labels are next-action evidence from one maintainer's Claude Code sessions, which favours v3's training target. The sessions are private; only aggregates are published (SPECIALIST.md).

Synthetic, reproducible (python benchmarks/run_judge_bench.py, about 20 s, no network). Nine hand-written edge cases: supersession, contradiction, config change, exception rule, pt/en mixed, prompt injection in a tool output, large git diff, old root cause, re-read.

These cases are lexically easy, so the lexical baselines do well; v3 misses the Portuguese case. Timings are from macOS arm64 under heavy machine load. Method, every arm and the limits: BENCHMARKS.md. Rules modes on real sessions: REAL_SESSION_BENCHMARKS.md.

Reduction depends on how much of a context is noise. Below a 25% gain, the report marks the pass as not worth it, and the Claude Code plugin keeps the built-in summary.

What it does not do

• It does not check that a model will answer correctly. A structural PASS is not an answer quality result.
• No RAG, embeddings or vector store.
• Protection rules and bounded restoration reduce, but do not rule out, lost evidence; see the safety model.
• specialist-v3 was trained on Claude Code transcripts. Other agents and plain documents are out of distribution; plain text uses mechanical unless a TypeSafe key is configured.

Docs

Development

Python 3.11+.

python -m pip install -e '.[dev,tiktoken]'
pytest -q && ruff check . && mypy
npm test                                   # Node API and hook tests
python benchmarks/run_judge_bench.py --check --out /tmp/judge-bench

The PyPI package named lcc is unrelated; this one is local-context-compiler. Contributing: CONTRIBUTING.md. Security: SECURITY.md. Changes: CHANGELOG.md.

License

MIT. The optional Laya integration carries Apache-2.0 attribution in NOTICE. Maintained by LookADev.