lcc (Local Context Compiler)
You can use this MCP server to compact and audit coding-agent context locally, verbatim, and recoverably.
compact: Drop context blocks irrelevant to an objective from text/documents, with offline mechanical default or optional providers.compact_transcript: Compact session transcripts by pairing tool calls/results and dropping spent pairs while keeping messages verbatim; supports local ranker, rules modes, and stashed recovery.recall: Retrieve exact bytes removed bycompact_transcriptinstashedrules mode, hash-checked on read.inspect: Run read-only diagnostics on text for tokens, structure, duplication, cleanup projection, and recommendations.prepare: Perform inspect-first deterministic prompt preparation without summarizing or paraphrasing.explain: Explain a compaction report, showing why blocks were kept, trimmed, or dropped.intake: Triage raw prompt input with readiness reasons, risk flags, clarifying questions, filler receipts, and a cache-stable compiled prompt.
Defaults are offline and fail-safe; optional remote/provider paths are opt-in.
lcc — Local Context Compiler
Compact coding-agent context without summarizing it away. lcc cuts what the model does not need, keeps everything else byte for byte, and writes a receipt.
/compact vs lcc
Claude Code's /compact replaces your session with a summary written by a model. Summaries
drop the exact error, path or line the agent needs two turns later. lcc does the opposite: old
tool outputs leave the context but stay one recall away, and every user and assistant message
is kept as it was.
One real Claude Code session (193 messages, 75 tool calls) | tokens | user and assistant messages | removed tool outputs |
before | 57,083 | 43, as written | — |
| one summary | rewritten into the summary | gone |
lcc ( | 28,807 (−49.5%) | 43 / 43 byte for byte | 33, each one |
Measured with lcc measure-session (PyPI 1.2.0, offline, exact o200k_base token count;
re-run 2026-10-23). On main, whose stash note now states lines and size, the same session
gives 28,983 (−49.2%). That session is one of the best cases. Across all 299 of my long sessions (100+ messages each,
36.3 M tokens) the median cut was 21.8% (middle half 15% to 31%, best 65%), with 0 messages
lost (python benchmarks/research/long_sessions.py, 2026-10-23, main). These are all my sessions: run it on yours and post the result.
In a pre-registered test on 172 real requests (evidence), an agent answering
from the stashed context plus recall did as well as with the full context on file recall
(+0.006, 95% CI −0.023 to +0.034) with 36.6% fewer tokens. It called recall for 90% of the
questions about removed content. A /compact-style summary of the same sessions got 73% of exact values
right (our reimplementation of /compact, written by Opus); full and verbatim context got 98%.
Related MCP server: longhaul
Install
pip install "local-context-compiler[tiktoken]" # the CLI is `lcc`
lcc fetch-tokenizer # once: exact token counts
lcc measure-session "$(ls -t ~/.claude/projects/*/*.jsonl | head -1)" # your latest sessionThe PyPI package is local-context-compiler. pip install lcc installs an unrelated astronomy
package that happens to own that name.
fetch-tokenizer downloads tiktoken's encoding files once; it is the only lcc command that goes
online, and without it counts are labelled approximate. The last line reads your most recent
Claude Code session, runs the rules modes offline in seconds and prints counts only. Nothing is
changed and nothing leaves the machine.
Claude Code plugin (replaces the /compact summary). Function hooks are early access, so
this needs Claude Code 2.1.274+ and the flag below:
export CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1
claude plugin marketplace add lucasmartins-ai/lcc
claude plugin install lcc@lcc --config provider=rules --config rulesMode=stashedAllow mcp__plugin_lcc_lcc__recall so the agent can get removed outputs back. When a pass
fails or removes too little, the plugin hands over to the built-in summary and says so in a
toast. Details: Claude Code guide.
MCP (Claude Code, Cursor, Claude Desktop, any stdio client):
{"mcpServers": {"lcc": {"command": "lcc", "args": ["mcp"]}}}Tools: compact, compact_transcript, recall, inspect, prepare, explain, intake
(MCP guide).
CLI, on a session file or any document:
lcc compact ~/.claude/projects/<project>/<session>.jsonl -q "finish the parser fix" \
--mode tool-calls --provider rules --rules-mode stashed -o compacted.json -r report.json
lcc recall <id> # a removed output, hash-checked
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 droppedSend us your numbers
lcc measure-session ~/.claude/projects/<project>/<session>.jsonl --markdown
# Codex CLI rollouts are auto-detected from their session_meta record:
lcc measure-session /path/to/rollout.jsonl --markdown
# or a whole project directory: per-mode median and p90 reduction over its sessions
lcc measure-session ~/.claude/projects/<project>/ --markdownIt runs every mode on one of your sessions, offline, and prints counts only: messages, tool
calls, tokens before and after, messages kept, time. No text, path or tool output. For exact
counts, install the tiktoken extra and cache its tokenizer once (lcc itself never downloads):
python -c "import tiktoken; tiktoken.get_encoding('o200k_base')". Otherwise the report says
approximate and why. Paste it in
Discussions → Results.
Add --input-map to see where the session's billed input goes instead: cache reads and
writes, and the share taken by tool results, tool-call inputs, injected instructions and the
fixed system prompt and tool schemas (counts only, from the usage records in the file).
Already compacting with lcc? lcc share-stats turns your local reports into the same kind of
counts-only summary (SHARE_STATS.md), or use the
results issue form.
Every number from someone other than me makes the claims above less mine and more true.
Why lcc
Verbatim. Kept spans are byte-identical to the source. Nothing is summarized or rewritten.
Recoverable.
stashedmoves removed outputs to a local content-addressed store (~/.cache/lcc/stash);recallre-hashes on read. The placeholder,[removed: 120 lines, 4.3 KB · lcc recall <id>], states lines and size, not tokens, so it is identical on every machine.Auditable. Every pass writes a JSON report;
lcc explaingives the reason for every drop.Local. The default judges run on your CPU in plain Python. No API key, no network.
Providers
Provider | Runs | When it is used | Report says |
| local, CPU | default ( |
|
| local, CPU |
|
|
| local, no model |
|
|
| remote (TypeSafe API) | opt-in: | semantic judgment or explicit degradation |
| local model | deprecated; runs only when named | named model and fallback state |
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. auto never picks it on its own: having a key is not
consent to send context off-machine, so plain text under auto stays on mechanical unless
you set LCC_AUTO_REMOTE=1. compact writes a relevance-compaction-1.2 report;
check provider_used and degraded before trusting the output.
Benchmarks
Real sessions (held-out, INFERIDO). In plain words: when a ranker has to drop part of a session, how often does it keep what the agent actually used next? 1.0 would be always. 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:
ranker | recall AUC | all-kept AUC |
specialist-v3 | 0.899 | 0.434 |
mechanical | 0.829 | 0.238 |
recency | 0.818 | 0.306 |
bm25 | 0.803 | 0.270 |
random | 0.689 | 0.138 |
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.
raw ranking | specialist-v3 | mechanical | bm25 | recency |
cases with every must-keep block kept at a 30 / 50 / 70% cut (of 9) | 8 / 7 / 7 | 9 / 9 / 9 | 9 / 9 / 7 | 8 / 6 / 3 |
full pass, default settings | must-keep kept | 302 blocks | 1,138 blocks | peak RSS |
| 9/9 | 181 ms | 3.4 s | 71 MB |
| 9/9 | 2 ms | 16 ms | 55 MB |
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
PASSis 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-v3was trained on Claude Code transcripts. Other agents and plain documents are out of distribution; plain text usesmechanicalunless you opt in to Jev.
Docs
Topic | Link |
What lcc is, the glossary, product vs research | |
Five-minute tour of the CLI | |
Claude Code plugin | |
MCP server | |
Tool-call compaction and rules modes | |
Aider chat history as input | |
The local ranker | |
Benchmarks | |
Python API ( | |
Architecture and decisions | |
Opt-in and deprecated providers | |
Research archive | |
Privacy |
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-benchThe 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.
Available Tools
7 toolscompactB
Drop context blocks irrelevant to an objective. Default provider mechanical is fully offline (no key, no network); laya is offline semantic (needs the [laya] extra, else honest mechanical fallback); jev needs TYPESAFE_API_KEY. Fail-safe: failures keep content.
Inputs: text (required), question (required), provider, threshold.
compact_transcriptA
Tool-call compaction for a session transcript: pairs each tool call with its result, pins the first and newest messages, and drops the pairs a semantic judge says are spent — kept messages stay verbatim, so nothing is summarized. Default 'auto' is the local specialist-v3 ranker (offline, no key); 'jev' is remote and needs TYPESAFE_API_KEY. Every failure keeps the call.
Inputs: messages (required), question (required), ledger, trigger, +20 more.
explainB
Explain a relevance-compaction report (as produced by compact): why every block was kept, trimmed, or dropped. Never re-runs, never touches the network.
Inputs: report (required), only, limit, source_text.
inspectA
Read-only diagnostic inspection of a text: tokens, structure, duplication, cleanup projection, and recommendation. Offline.
Inputs: text (required).
intakeB
Intake triage for raw prompt input: readiness with named reasons, non-blocking risk_flags, clarifying questions, a receipt of every filler removed from dictation, and a cache-stable compiled prompt. Offline.
Inputs: text (required), question, previous_turn.
prepareC
Inspect-first deterministic prompt preparation: runs inspection, then lexical selection + safe optimization only when recommended. Never summarizes or paraphrases. Offline.
Inputs: text (required), question.
recallA
Return a tool output that compact_transcript (rules_mode 'stashed') replaced with '[removed: N lines, S KB · lcc recall ]'. The bytes are re-hashed on read, so the text is exactly what was removed. Offline, local stash only.
Inputs: id (required), file, lines, ledger.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools have distinct scopes: intake handles raw prompts, inspect is read-only diagnostics, prepare does deterministic prompt preparation, compact operates on context blocks, and compact_transcript operates on session transcripts. The boundaries are mostly clear, though compact vs compact_transcript and inspect vs prepare could be confused at first glance, requiring the descriptions to disambiguate.
All names are lowercase snake_case and are mostly concise verb-style names. The set is mostly consistent, with minor deviations such as compact_transcript being a compound name while most others are single verbs, and intake reading more like a noun than a verb.
Seven tools is well-scoped for a local context compiler. Each tool appears to earn its place across intake, inspection, preparation, compaction, explanation, and recall, with no obvious filler tools.
The surface covers the main lifecycle: intake, inspect, prepare, compact, compact_transcript, explain, and recall. Minor gaps exist, such as no obvious listing or management operations for stashed outputs or generated reports, but the core workflows are covered and agents can work around these gaps.
Maintenance
Related MCP Connectors
Compress coding-agent context ~64%. Hosted Neural Keep MCP for Cursor/Claude/Codex.
Cuts coding agent token burn up to 72% continuously via contradiction-free memory & verification.
Deterministic AI agent microtools, no accounts/API keys. fetch_extract: 98% token cut. 47 tools.
Capture coding-agent sessions and resume them in any other agent: Claude Code, Codex, Cursor, more.
Related MCP Servers
- AlicenseBqualityDmaintenanceBrings Claude Code's context compaction to any MCP host, enabling agents to gauge context pressure, summarize history, re-hydrate files, and persist rules across session boundaries.19MIT
- AlicenseAqualityCmaintenanceEnables local LLM chat sessions to continue indefinitely by automatically compacting context and storing permanent memory on disk, with recall across all past sessions.41MIT
- AlicenseNot gradedqualityBmaintenanceProvides deterministic context compaction and safety gating for AI agents, preserving original messages verbatim while dropping irrelevant ones and flagging destructive commands.2MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables agents to deterministically shrink multi-turn conversation history and prompts by stripping verbose boilerplate and filler tokens while preserving critical tool parameters and named entities. This lets users cut inference costs by roughly 40-60% without losing essential context, running either as a native MCP server over JSON-RPC stdio or as an importable zero-dependency Python module.MIT