lcc — Local Context Compiler
Shrinks coding-agent context without summarizing it away: byte-exact spans, offline judging, and a recall path for every cut.
- Source repo
- lucasmartins-ai/lcc
- Stars
- ★ 16
- Last updated
- today
- License
- MIT
- Primary language
- Python
- FA score
- 78/100 · Good
At a glance
- How it runs
- Works with
- Portable with changesClaude CodeCodex · OpenAI API · Claude API (Partial support)ChatGPT (Unsupported)
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Claude Code users whose long sessions bloat the context and who lose exact errors or paths after /compact, replacing the summary with lcc's stashed mode plus recall.
- Not a fit if
- Teams that need a general RAG or vector-store pipeline.
- Users who prefer model-written summaries over byte-exact retention.
- Teams on non-Claude-Code agents needing out-of-the-box tuning.
- Source review
- 78/100 · Good
What does this agent do, and when should you use it?
lcc (Local Context Compiler) is a context-compression tool for coding agents whose goal is fewer tokens without losing the exact details an agent needs later. Old tool outputs leave the context, but each removed chunk lands in a local content-addressed store (~/.cache/lcc/stash) and can be fetched back byte for byte with lcc recall, which re-hashes on read. Everything kept is byte-identical to the source; nothing is summarized or rewritten. It ships three surfaces: a CLI (lcc), an MCP stdio server exposing tools like compact and recall, and a Claude Code plugin that replaces the built-in /compact summary. The default judges run on local CPU in plain Python with no API key or network, while a remote jev provider exists as an explicit opt-in. Every pass writes a relevance-compaction-1.2 JSON report, and lcc explain gives the reason each block was kept or dropped.
lcc ingests Claude Code session JSONL files, Codex CLI rollout files (auto-detected via session_meta), Aider chat history, or plain documents, then decides which blocks can be dropped using a provider (rules, specialist-v3, mechanical, jev) and mode such as tool-calls. The rules provider has three levels: lossless removes only provable duplicates, recoverable also drops outputs that can be re-read, and stashed (recommended) moves removed outputs into ~/.cache/lcc/stash and leaves a placeholder of the form [removed: N lines, X KB · lcc recall <id>]. Output is a compacted file plus a relevance-compaction-1.2 JSON report recording provider_used and degraded. lcc recall <id> re-hashes the stored content on read, and lcc explain report.json --source notes.md shows why each block was kept or dropped. lcc measure-session runs every mode over a session or a whole project directory offline and prints counts only — messages, tool calls, tokens before and after, time — with --input-map breaking down billed input across cache reads/writes, tool results, tool-call inputs, injected instructions and the fixed system prompt. The MCP server exposes compact, compact_transcript, recall, inspect, prepare, explain and intake.
- Claude Code users whose long sessions bloat the context and who lose exact errors or paths after /compact, replacing the summary with lcc's stashed mode plus recall.
- Teams wiring context compaction into Cursor, Claude Desktop or any other stdio MCP client by registering lcc mcp as a server.
- Developers scripting batches of session files or Markdown documents through lcc compact with a -q objective and a chosen --provider, producing compacted output and an audit report.
- Researchers who want to run lcc measure-session on their own sessions first to quantify per-mode token reduction before adopting.
- Teams needing an audit trail, using the JSON report and lcc explain to review the justification for every dropped block.
- Privacy-sensitive users running the local rules or mechanical provider so content never leaves the machine.
How do you install or deploy this agent?
Python 3.11+ is required. Install from PyPI, adding the tiktoken extra for exact token counts:
pip install "local-context-compiler[tiktoken]"
lcc fetch-tokenizerlcc fetch-tokenizer is the only command that goes online; it downloads tiktoken's encoding files once. Without it, counts are labelled approximate.
For the Claude Code plugin (requires Claude Code 2.1.274+ and the function-hooks flag):
export CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1
claude plugin marketplace add lucasmartins-ai/lcc
claude plugin install lcc@lcc --config provider=rules --config rulesMode=stashedAfter installing, allow mcp__plugin_lcc_lcc__recall so the agent can retrieve removed outputs.
How do you use this agent?
Measure reduction on your most recent session first (offline, counts only):
lcc measure-session "$(ls -t ~/.claude/projects/*/*.jsonl | head -1)"Compact a session file or a plain document, writing both the compacted output and a JSON report:
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.jsonlcc compact notes.md -q "what is wrong with the booking flow?" \
--provider mechanical -o compacted.md -r report.jsonRetrieve a removed output with hash verification, and inspect the rationale for every block:
lcc recall <id>
lcc explain report.json --source notes.mdUse it as an MCP server from any stdio client:
{"mcpServers": {"lcc": {"command": "lcc", "args": ["mcp"]}}}The remote jev provider is opt-in: set TYPESAFE_API_KEY and pass --provider jev; LCC_DISABLE_NETWORK=1 blocks outbound network.
What are this agent's strengths and limitations?
- Kept spans are byte-identical to the source, and stashed-mode removals come back through recall with a hash check on read — unlike /compact, which rewrites the whole session into a model summary.
- Default providers run locally on CPU in plain Python with no API key; network is used only for the optional tokenizer download and the explicitly opted-in jev provider.
- Each pass produces a relevance-compaction-1.2 JSON report, and lcc explain lists the reason every block was kept or dropped, making cuts auditable.
- measure-session quantifies reduction on your own real sessions offline and prints counts only, with --input-map breaking down where billed input goes.
- The same capability ships as a CLI, an MCP server and a Claude Code plugin, backed by published benchmarks on real sessions and synthetic edge cases.
- Reduction depends heavily on how noisy a session is: the author reports a 21.8% median cut across 299 long sessions, and the plugin falls back to the built-in summary when a pass gains less than 25%.
- specialist-v3 was trained on Claude Code transcripts; other agents and plain documents are out of distribution, and the README states v3 misses the Portuguese synthetic case.
- The held-out benchmark labels come from a single maintainer's Claude Code sessions, and only aggregates are published, so independent validation is limited.
- The Claude Code plugin relies on early-access function hooks, needing Claude Code 2.1.274+ and an environment flag rather than a stable public interface.
- The README states it does not verify that a model will answer correctly, does no RAG or embeddings, and that protection rules reduce but do not eliminate lost evidence.
How does this agent compare with similar options?
The README positions lcc mainly against Claude Code's built-in /compact: /compact replaces the session with a model-written summary that drops the exact error, path or line the agent needs two turns later, whereas lcc keeps every user and assistant message and only moves old tool outputs out of context, one recall away. The benchmark section also compares rankers against recency, bm25 and random baselines using retention AUC.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| lcc — Local Context Compiler This agent | 78 · Good | CLIFree | ★ 16 | today | Python | Claude Code |
| OpenBrowser | 60 · Some gaps | CLIFreemium | ★ 279 | 1mo ago | Python | Codex · Claude Code · Claude.ai · OpenAI API · Claude API |
| Headroom: The Context Compression Layer for AI Agents | 59 · Major gaps | CLIFree + model costs | ★ 79k | today | Python | Codex · Claude Code · OpenAI API · Claude API |
| LeanCTX Context Intelligence | 75 · Good | CLIFree + model costs | ★ 3.9k | 1d ago | Rust | Codex · Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
SECURITY.md and PRIVACY_POLICY.md are unusually explicit: offline by default, network blocked, jev only on explicit naming or LCC_AUTO_REMOTE=1, LCC_DISABLE_NETWORK=1 as a global override — data_flow_transparency earns 3. least_privilege is only 2: the stash persists removed verbatim text with no expiry, and the author admits the workspace_root disk check is not a sandbox. user_confirmation is 2: remote paths require explicit naming, but plugin install and MCP wiring grant recall without per-call confirmation. sensitive_data_handling is 2: the docs state lcc does not scan or redact context and the stash can hold secrets indefinitely. dependency_security is 2: weekly pip-audit and SHA-pinned actions exist, but package.json devDependencies (fast-jev-compaction, railway) are not covered by that audit story. external_effects is 2: local writes and stash by default, but --append-to and stash gc are real writes. rollback is 2: stash+recall gives byte-level recovery, yet nothing expires and gc needs manual --apply. source_attribution is 2: LICENSE/NOTICE and Laya Apache-2.0 attribution are clear, but publisher identity is unverified and maintenance is only a LookADev link.
self_consistency is 3: tests/invariants.py centralizes seven invariants (idempotence, verbatim, recall round-trip, no corruption, stable placeholders, accounting, fail-closed) shared by unit tests, fuzz and corpus replay, and CI runs the fuzz and benchmark gates. dependency_availability is 2: core deps (typer/rich/pyyaml) are common and tiktoken/laya are optional with labelled fallbacks, but the laya extra pulls torch/transformers and the README vs SECURITY.md wording on tiktoken's first-use download (fetch-tokenizer online vs runtime block) needs reader reconciliation. failure_messages is 2: QUICKSTART asserts common errors name the next step, but no error-message inventory or snapshot test in the repo backs that, so it is only partially supported.
audience_and_scenarios is 3: README and QUICKSTART cover the Claude Code plugin, MCP, CLI, Python API, Aider history and Codex rollouts. capability_boundaries is 3: 'What it does not do' plus the provider table state semantic_guarantee: none, no answer-quality check, no RAG, and specialist-v3 out-of-distribution. trigger_precision is 2: the plugin falls back to the built-in summary below a 25% gain, but activation depends on Claude Code 2.1.274+ and an experimental function-hooks flag, so behavior is host-version dependent. environment_fit is 2: Python 3.11+, Node 20, optional tiktoken cache and laya assets; declared OS Independent without platform-specific notes.
information_architecture is 3: README has clear install, provider table, benchmarks, limitations and a docs index, with docs/ split by topic. install_notes is 3: pip, plugin marketplace, MCP JSON and dev install all give copyable commands. naming_stability is 2: README warns the PyPI package named lcc is unrelated and this one is local-context-compiler, but the CLI name lcc diverges from the package name and there are parallel Python and Node APIs (LccCompressor etc.). examples_and_faq is 3: QUICKSTART has numbered scenarios, an offline matrix and a 'Where next' Q&A table. known_limitations is 3: a dedicated section lists non-goals, stash non-expiry and injection non-removal. license is 3: full MIT text, consistent in pyproject and package.json, NOTICE covers Laya. versioning_changelog is 2: version 1.2.0 is consistent and points to CHANGELOG.md, but the changelog content is not in evidence. maintenance_responsibility is 2: author, LookADev link and a SECURITY reporting channel exist, but publisher identity is unverified and there is no governance or SLA statement.
output_usability is 3: output is byte-preserved context plus a JSON report, lcc explain gives per-block reasons, recall restores removed bytes, and placeholders state lines and size, so downstream use is direct. marginal_value is 2: README reports a 21.8% median cut across 299 long sessions and the plugin falls back below 25%, so gains are limited in some cases; the pre-registered test shows parity with full context on file recall (+0.006, CI crossing zero) — real but modest. cost_benefit is 2: local CPU with no API key keeps cost low, but specialist-v3 takes 181 ms on 302 blocks and 3.4 s on 1,138 blocks, and the author concedes the headline session is one of the best cases.
claim_traceability is 2: README tags each number with command, date and version (measure-session, 2026-10-23, PyPI 1.2.0) and points to docs/EVIDENCE.md and benchmarks/, but those evidence files are not in this evidence set, so they cannot be checked. cross_source_corroboration is 2: README, QUICKSTART and SECURITY.md agree on offline defaults and provider behavior, but benchmark numbers have a single source (the maintainer's own sessions) and the author admits the labels favor v3's training target. fact_inference_separation is 2: README marks inference as 'INFERIDO' and separates synthetic reproducible benchmarks from private-session aggregates, which is good; however PRIVACY_POLICY.md describes a hosted Railway ChatGPT plugin alongside the local-first README narrative, leaving readers to work out which applies to which deployment.
- The stash keeps removed verbatim text in ~/.cache/lcc/stash with no expiry and can retain secrets; run lcc stash gc --apply or delete the directory deliberately.
- SECURITY.md states lcc does not scan or redact context, so sensitive content flows verbatim into outputs and the stash.
- The author states the recoverable-mode workspace_root disk check is not a sandbox; do not treat it as an isolation boundary.
- PRIVACY_POLICY.md describes a hosted Railway ChatGPT plugin alongside the local-first README narrative; confirm which policy applies before using the hosted endpoint.
- The Claude Code plugin depends on experimental function hooks and version 2.1.274+, so host upgrades may change behavior.
- Publisher identity is unverified; maintenance responsibility is only a LookADev link with no governance or SLA statement.
- package.json devDependencies (fast-jev-compaction, railway) fall outside the pip-audit coverage described in the workflows.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
lcc 1.3.0 ```sh pip install -U "local-context-compiler[tiktoken]" lcc fetch-tokenizer # once: exact token counts ``` If you use the Claude Code plugin, update it from /plugin as well, so the hook and the lcc it calls are both 1.3.0. First run is fast and exact - lcc measure-session runs the two rules modes by default; auto needs --auto. On 1.2.0 the auto arm took 247 s of a 4 min 15 s run on a 10,559-message session, so the README's first command looked hung. On a ~520k-token session the default now returns in about 2 s …View on GitHub ↗ -
Release notes excerpt
Added - lcc measure-session <session.jsonl>: runs rules:lossless, rules:stashed and auto on one Claude Code session, offline, and prints counts only (messages, tool calls, tokens before/after, texts kept, time). --markdown is ready to paste into an issue, --json is lcc-session-report/1. It never writes to the real stash. - lcc compact --mode tool-calls --rules-mode <mode> (with --provider rules): the CLI can now select stashed, recoverable or lossy; before, only MCP and Python could. …View on GitHub ↗ -
Release notes excerpt
Added - Claude Code plugin: rulesMode: "stashed". The plugin accepted only lossless, recoverable and lossy, so the stashed mode could not be picked from Claude Code. Docs now recommend stashed with the recall tool, with the one measured run (INFERIDO) in docs/TOOL_CALLS.md. - rules_mode: "stashed" and lcc recall. Tool-call compaction can now remove what lossy drops or trims and what recoverable replaces without losing it: the exact bytes go to a local content-addressed stash (~/.cache/lcc/stash, 0700/0600, LCC_STASH_DIR) …View on GitHub ↗