lcc — Local Context Compiler

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

lcc prepares text for model calls: clean duplicates and boilerplate, select context for an explicit objective, and record what was kept, trimmed or omitted. Selected spans stay verbatim (no LLM rewriting), the default path runs offline with no API key, and every pass writes a JSON report you can audit.

The session rows use tool-call mode with the Jev judge; source, commands and limits are in real-session measurements. The demo rows are reproducible with the commands in the GIFs (exact tiktoken counts). Your reduction depends on how much of your context is actually noise; below a 25% gain, lcc tells you it is not worth it.

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 every block was kept or dropped

Use it from any MCP client (Claude Code, Cursor, Claude Desktop…):

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

Or replace Claude Code's lossy /compact summary with verbatim tool-call compaction:

claude plugin marketplace add lucasmartins-ai/lcc
claude plugin install lcc@lcc

The plugin needs the early-access function-hooks flag and a judge (a TypeSafe key for Jev, or provider: laya for fully local); without one it falls back to the built-in summary. See the Claude Code plugin guide.

Where it fits in a token-saving stack

They compose: RTK and caveman cut what flows in and out per turn; lcc cuts what accumulates.

More demos: lcc optimize compiling a messy brief into a structured prompt

What it does not do

A structural PASS does not establish that a model will answer correctly. Cleaning and prompt templates are separate transformations; compaction may add omission markers. The default offline workflow uses lexical scoring and structural checks. Optional semantic providers run locally (Laya) or remotely (Jev). No RAG, embeddings or vector store is implemented.

Project status

The checkout declares Python and Node package version 1.0.0 and Python 3.11+. MSI sprints 1–10 have PASS reports; the research release is complete. The software is classified Beta in package metadata.

The 2026-10-03 audit findings R1–R3 are resolved in Sprint 10: all-attempt cost accounting, shared paired bootstrap, and full-payload drift checks are active in MSI-Bench. Frozen contracts, the architecture paper, prior-art review, limitations and research agenda, version manifest, and master results are published.

Install from source

From a local checkout:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
lcc --version

Runtime dependencies are Typer, Rich and PyYAML. This path requires no model or API key. Installation may download Python dependencies; the workflows below run offline. To install the registry package, use pip install local-context-compiler; its contents may differ from this checkout. The executable is lcc. The unrelated PyPI package named lcc is not this project.

Optional extras:

python -m pip install '.[tiktoken]'  # exact counts when encoding assets are available
python -m pip install '.[laya]'      # local semantic provider; stages model dependencies

Tiktoken installed without cached encoding assets can still yield estimates. Read token_count_method, tokenizer_id and is_estimate in the report; use --require-exact-tokens on supported commands to reject estimated counts. See tokenizer boundaries.

Copyable offline workflow

Create the input before invoking the CLI:

cat > dossier.md <<'EOF'
The mobile booking form erased patient input at step two.

The mobile booking form erased patient input at step two.

LOG: worker heartbeat ok in 554ms.
EOF

lcc optimize dossier.md -o prompt.md -r clean.json
lcc inspect dossier.md -r inspect.json
lcc compact dossier.md -q 'reduce mobile booking friction' \
  --provider mechanical -o compacted.md -r report.json
lcc explain report.json --source dossier.md
lcc diff dossier.md compacted.md

optimize removes boilerplate/duplicates and formats a prompt. inspect reads without modifying the source. compact selects context for the objective; short or protected inputs may remain unchanged. explain audits the report without scoring again. diff prints a comparison and exits 0 even when files are different. Human summaries go to stderr; requested text/JSON files carry machine-readable output. See the quickstart.

Python: compile context with an audit receipt

from pathlib import Path
from lcc.msi import compile

result = compile(
    'reduce mobile booking friction',
    Path('dossier.md').read_text(encoding='utf-8'),
    task_id='booking-01',
)
print(result.context)
print(result.sufficiency)
print(result.receipt.to_spec_dict())

compile() uses planner-1.0, mechanical compaction and bounded structural restoration. It makes no inference call. Its plan describes a route; it does not execute that model. The wrapper fixes risk to low, so use the planner API explicitly for higher-risk tasks. A receipt's zero API cost means no remote call, excluding CPU and energy.

Same inputs produce the same context bytes; receipt clocks may differ. Empty tasks/context and negative restoration budgets raise ValueError. The API contract documents msi-api-1.0 and its limits. For full execution/verification chains, use the separate verification and escalation APIs.

Providers and failure handling

lcc compact dossier.md -q 'reduce mobile booking friction' --provider jev \
  -o compacted.md -r report.json

Jev's optional path evaluates typed relevance questions instead of generating summaries. Its decisions do not prove downstream answer quality. See Jev and Laya for limits and fallback contracts. LCC_DISABLE_NETWORK=1 disables the Jev path. Explicit unavailable Jev keeps context and reports degradation; unavailable Laya uses a named mechanical fallback. Check provider_used, degraded, degradation_reason, sufficiency failures and review flags before using the output.

compact writes a relevance-compaction-1.2 report. Optional IR is context-ir/0.1; the Python MSI receipt is inference-receipt/0.1. Read the artifact's version before interpreting its fields.

The pipeline applies selection, deterministic protection, bounded restoration and structural checks. Optional semantic verification is a separate single pass. The safety model, IR and restoration limits explain where evidence can still be lost. Preservation is not a security verdict.

Agents, MCP and Node

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

The stdio MCP server exposes compact, compact_transcript, inspect, prepare, explain and intake. compact defaults to mechanical scoring. Tool-call transcripts use a semantic provider; user/assistant messages remain pinned. See MCP, tool-call mode and Claude Code integration. Plugin transport and live model execution were not exercised by the offline usability benchmark.

The Node API supports deterministic cleaning, prompt templates and intake; it has no Python MSI/IR/planner parity. Node token counts are heuristic. From this checkout:

const { LccCompressor } = require('./index.js');
const result = new LccCompressor().compress('context text');
console.log(result.compressedText);

agent and route are separate optional execution paths requiring configured backends. semantic-retrieval reports a disabled/blocked boundary: no retrieval adapter is implemented. Command requirements are listed in the quickstart matrix.

Evidence and usability

The workflow benchmark installs a wheel into a fresh base-only venv and runs outside the source directory. On macOS ARM64, Python 3.12.14, at code commit 310ab9e:

Times include process startup. This is executable workflow coverage, not a human usability score or a guarantee for other machines. Full stdout/stderr, package versions, input/runner/wheel hashes and commands are in results.json.

Existing quality evidence is reported separately:

Source, exact commits, reproduction and all failures: real-world integration. The oracle arm is not lcc.msi.compile. No result above establishes live-agent success, inference latency, actual billing savings or production transfer.

The sprint-7 pilot has 12 curated tasks and 72 arm runs. In Sprint 10, audit findings R1–R3 were resolved: full-chain attempt costs are accounted for, bootstrap sampling is paired across arms, and --check asserts complete payload stability. Historical semantic-provider experiments live in research status, transcript A/B and real-session measurements. They were not rerun with live providers in this audit.

External feedback exists: one contributor reported Laya weight reloads (#19) and network-guard thread interference (#18). Both issues are closed and have offline regression tests. Their historical timing/incident reports are user observations, not new benchmark measurements.

Reproduce and validate

From the repository root, with Python 3.11 or 3.12:

python -m pip install -e '.[dev,tiktoken]'
mypy
ruff check src tests benchmarks/usability/run.py
pytest -q
npm test
python examples/msi_quickstart.py
PYTHONPATH=src:benchmarks/msi-bench python benchmarks/msi-bench/run.py --check
PYTHONPATH=src:benchmarks/msi-bench:benchmarks/msi-replay \
  python benchmarks/msi-replay/session_replay.py --check
PYTHONPATH=src:benchmarks/msi-bench:benchmarks/msi-replay \
  python benchmarks/msi-replay/replay.py --check

The CI enforces Python tests, lint and configured-package mypy on Python 3.11/3.12, plus Node 20 unit and hook tests. Optional live Laya/Jev tests and uncached exact-token tests may skip; a green suite does not validate them. See audit evidence for commands and results.

To rerun the usability harness against a packaged artifact:

python -m build --outdir /tmp/lcc-dist
python benchmarks/usability/run.py \
  --wheel /tmp/lcc-dist/local_context_compiler-1.0.0-py3-none-any.whl \
  --output /tmp/lcc-usability.json --repeats 3

Benchmark reproduction needs a repository checkout, including frozen datasets; a runtime wheel alone is not the research archive.

Architecture and license

The deterministic core is cleaning, token_budget, prompt_builder, reporting, pipeline, inspection and benchmarking. Relevance providers, MSI composition and model execution live outside it. See ADR 0010, architecture and the ADR index.

LCC uses the MIT license. The optional Laya integration has Apache-2.0 attribution in NOTICE, included with packaged license files. Maintained by LookADev.