lcc cut one Claude Code session 49.5% without a summary

lcc (Local Context Compiler), a Show HN project, compacts Claude Code sessions by moving old tool outputs out of the context while every user and assistant message stays unchanged. Its author’s figures, re-run on October 23, put the typical cut at about a fifth of a session. The headline result is about half. What lcc offers in return is that the exact values a summary loses stay in the session.

The project is MIT-licensed, maintained by LookADev and documented in its GitHub repository. It goes after Claude Code’s /compact, which replaces the session with a summary written by a model. The README states the complaint plainly: “Summaries drop the exact error, path or line the agent needs two turns later.”

How the stash works

Claude Code’s built-in compaction already does part of this. Anthropic’s Claude Academy course says compaction summarizes important details and removes unnecessary tool call results, and warns that the process can lose details. lcc keeps only the removal half. Old tool outputs leave the context, nothing is rewritten, and the conversation stays byte for byte as it was.

Each removed output is replaced by a one-line placeholder of the form [removed: 120 lines, 4.3 KB · lcc recall <id>]. The output itself goes to a local content-addressed store in ~/.cache/lcc/stash, where each entry is keyed by a hash of its contents, and the recall tool re-hashes it on read before returning it. When the agent needs an exact stack trace from much earlier in the session, it calls recall and gets the original bytes back, with no paraphrase in between. The placeholder states lines and size rather than tokens, so it reads the same on every machine.

For transcripts, the recommended provider is rules. It runs locally, uses no model at all and has three modes. lossless removes only provable duplicates. recoverable also removes outputs that can be re-read. stashed is the recommended mode: it removes outputs and keeps them byte-recoverable through recall. Every pass writes a JSON report, and lcc explain gives the reason each block was kept or dropped.

A small trained ranker, specialist-v3, runs on the CPU in plain Python and is the default whenever transcript blocks are present. Its report says semantic_guarantee: none, which the README describes as “a rank, not a judgment”. catnap, another fix shared on Hacker News, works on timing. At 50% context it has Claude finish its current piece and write its own handoff note. lcc changes what compaction produces, not when it fires.

The best case and the median

The headline figure comes from one real Claude Code session with 193 messages and 75 tool calls. The author measured it with lcc measure-session (PyPI 1.2.0, offline, exact o200k_base token count). The stashed rules mode took it from 57,083 tokens to 28,807, a 49.5% cut. All 43 user and assistant messages survived byte for byte, and 33 tool outputs went to the stash, each one recall away. On the main branch, where the placeholder now states lines and size, the same session comes out at 28,983 tokens, or 49.2%.

The author calls that session “one of the best cases”, and the wider run bears it out. Across 299 of the author’s long sessions, each with 100 or more messages and 36.3 million tokens in total, the median cut was only 21.8%. The middle half of sessions fell between 15% and 31%, the best reached 65%, and no messages were lost. The README sets a 25% gain as the line below which a pass is marked as not worth it. Under that line the Claude Code plugin keeps the built-in summary, and the 21.8% median sits below it.

The README says reduction depends on how much of a context is noise. The author is also open about how narrow the sample is: “These are all my sessions: run it on yours and post the result.”

Exact values versus a summary

The stronger claim is about quality, not size. In a pre-registered test on 172 real requests, an agent answering from the stashed context plus recall did as well on file recall as an agent with the full context. The difference was +0.006, with a 95% confidence interval from −0.023 to +0.034, so the result is within the margin of error. It also used 36.6% fewer tokens. The agent called recall for 90% of the questions about removed content.

Against a summary the gap is wider. A /compact-style summary of the same sessions got 73% of exact values right, while full, verbatim context got 98%. That summary came from the author’s own reimplementation of /compact, written by Opus. The comparison is against a stand-in, not Claude Code’s actual command.

For the ranker, the repository reports a one-shot final test on 193 items from 36 of the maintainer’s sessions, all started after the model’s training cutoff. The test asks how often a ranker that has to drop part of a session keeps what the agent actually used next. It is scored as an area under the curve over drop budgets of 0 to 60% of candidate tokens, where 1.0 would mean always.

• specialist-v3: 0.899 recall AUC, 0.434 all-kept AUC
• mechanical: 0.829 and 0.238
• recency: 0.818 and 0.306
• bm25: 0.803 and 0.270
• random: 0.689 and 0.138

The labels come from one maintainer’s Claude Code sessions, which the README says favours v3’s training target. The sessions are private, and only aggregates are published. A second, reproducible benchmark uses nine hand-written edge cases, among them a contradiction, a config change, prompt injection in a tool output and a large git diff. At 30, 50 and 70% cuts, specialist-v3 kept every must-keep block in 8, 7 and 7 of the nine cases. mechanical managed all nine at every level. The author says the cases are lexically easy, which helps the lexical baselines, and that v3 misses the mixed Portuguese and English case. The rules lossless mode passed all nine, taking 2 ms on 302 blocks.

The README also lists what lcc does not do. It does not check that a model will answer correctly, and “a structural PASS is not an answer quality result”. Protection rules reduce lost evidence but do not rule it out. specialist-v3 was trained on Claude Code transcripts, so other agents and plain documents are outside its distribution.

Installing it, and what stays local

The package on PyPI is local-context-compiler. A different package called lcc is unrelated. Install it with the tiktoken extra and point lcc measure-session at your latest file in ~/.claude/projects/. It runs every mode offline and prints counts only: messages, tool calls, tokens before and after, messages kept and time. Nothing is changed, and no text, path or tool output is printed. lcc never downloads a tokenizer itself, so without a cached one the report says its counts are approximate. Add --input-map to see where a session’s billed input goes instead, including cache reads and writes and the share taken by tool results, tool-call inputs and the fixed system prompt.

The plugin replaces the /compact summary and depends on function hooks that are still early access in Claude Code. It needs version 2.1.274 or later and CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1. You install it from the lucasmartins-ai/lcc marketplace with provider=rules and rulesMode=stashed. Allow mcp__plugin_lcc_lcc__recall so the agent can fetch removed outputs. When a pass fails or removes too little, the plugin falls back to the built-in summary and says so in a toast. For Cursor, Claude Desktop or any other stdio client, lcc also runs as an MCP server. It exposes compact, recall, explain and four other tools.

The default judges run on your CPU with no API key and no network. The one remote option is a provider called Jev, which sends the objective and context blocks to the TypeSafe API. It has to be named explicitly, and LCC_DISABLE_NETWORK=1 turns it off. Even with a TypeSafe key configured, auto mode keeps plain text on the local mechanical provider unless LCC_AUTO_REMOTE=1 is set. In the README’s words, “having a key is not consent to send context off-machine.”

The author asks users to run lcc measure-session with --markdown on a session, or on a whole project directory to get per-mode median and p90 reduction. The counts go into the repository’s Discussions under Results.