Reference

Changelog

lean-ctx version history — new features, improvements, and bug fixes for every release.

Every LeanCTX release, newest first. We follow semantic versioning, so patch releases are always safe drop-in updates.

3.8.8 Current (2026-06-17)

The Codex-compatibility & XDG-cleanup release. The proxy becomes a drop-in Codex replacement with a native Responses WebSocket transport and an opt-in for trusted plaintext upstreams; the ~/.lean-ctx → XDG migration is finished across every remaining writer and doctor; OpenCode finally gets its ctx_* rules and stops double-registering tools; and config init --full no longer overwrites your settings.

Added

  • Native WebSocket /responses transport for Codex (#440) — Codex CLI and the OpenAI SDK default to a persistent WebSocket connection (ws://…/responses). The proxy now speaks the Responses WebSocket protocol natively: GET /responses upgrades to a WebSocket, each turn is bridged to the configured HTTP/SSE upstream with lean-ctx's tool-output compression applied, and every upstream event is relayed back verbatim. Method routing keeps POST on the HTTP/SSE forwarder, so both transports share one upstream, auth path and compression logic. Codex works as a drop-in now without disabling WebSockets.
  • Opt-in for a trusted non-loopback HTTP upstream (#440) — clients that sit in front of the proxy can now point it at an upstream like http://host.docker.internal:2455 via LEAN_CTX_ALLOW_INSECURE_HTTP_UPSTREAM=1 or [proxy] allow_insecure_http_upstream = true. The startup banner and doctor flag the plaintext hop so it stays a conscious choice.
  • lean-ctx update <version> pins a specific release (#447) — update now takes an optional version (lean-ctx update 3.8.5) and installs that exact tagged release instead of the latest, so you can roll back or A/B an older build. It reuses the normal SHA256-verified, atomic update path, so no data, config or logs are touched — only the binary is swapped.

Changed

  • Rust crate migrated to edition 2024 (#438) — a tree-wide migration with fully documented unsafe env access and a thread-safe profile cell that removes a latent data race in the MCP server. No behavioural change. Thanks @dasTholo.
  • OpenCode plugin no longer double-registers the built-in overrides (#441) — ctx_read/ctx_search/ctx_glob/ctx_edit/ctx_shell were exposed both as static replacements and again via dynamic MCP registration, so the model saw two copies and paid for the duplicate schemas. The five overridden tools are now filtered out of the dynamic set. Thanks @omar-mohamed-khallaf.
  • Default shell allowlist now includes the C/C++ compilers (#361) — under mode=replace, gcc/cc/clang/g++/c++/clang++ are allowed alongside rustc/go/javac, so an agent can compile an ad-hoc reproducer. They are compile-only — running the produced binary stays gated — so the security boundary is unchanged.

Fixed

  • config init --full no longer resets the existing config to defaults (#443) — the command rebuilt the file from defaults and saved that over your config.toml, silently reverting custom settings on every run. It now loads the existing config and re-serializes that (falling back to defaults only when no file exists), preserving your values while still materializing the fully-commented template.
  • OpenCode (and 18 other agents) now get the ctx_* usage rules injected (#442) — rule injection was gated on a hand-maintained five-agent list, so everyone else silently skipped injection and the model never saw the "prefer ctx_* tools" guidance. Detection is now derived from the single agent catalog so every supported agent is covered, and the OpenCode hook also injects the rules into AGENTS.md when running MCP-only.
  • ctx_read exposes the same schema in Pi as in Codex / MCP (#432) — the Pi adapter hand-wrote a schema missing fresh and start_line, so cross-harness instructions like ctx_read(mode="full", fresh=true) looked invalid in Pi only. The Pi schema now matches the registry (with offset/limit kept as back-compat aliases).
  • Secret redaction stops corrupting type annotations and source files (#430) — the key/value pattern masked TypeScript type annotations and literals such as password: undefined, secret: string and token: Promise<string> when reading files through ctx_read. The redactor now skips obvious non-secret literals and recognises type expressions, two latent under-redaction bugs were fixed, and the shell and read redactors now share one implementation so they can't drift apart.
  • proxy enable now also routes Pi / forge through the proxy (#361) — Pi and forge resolve their endpoint from ~/.pi/agent/models.json, not from the *_BASE_URL env vars, so they previously bypassed the proxy. enable/disable now wire Pi's anthropic and openai providers when ~/.pi/agent exists, preserving custom endpoints unless --force.
  • The ~/.lean-ctx → XDG migration is now complete (#436, #439) — the data resolver no longer re-adopts a marker-free legacy ~/.lean-ctx, and every remaining direct writer (multi-agent knowledge, Jira OAuth, cloud cache, LaunchAgent/update logs, the A2A task store, the ctxpkg signing key, …) now routes through the typed data_dir()/state_dir() resolvers. A cross-category contract test plus a source-level legacy-path firewall lock the invariant in.
  • Impact graph self-heals after an upgrade (#398) — ctx_impact rebuilt the graph only when it was completely empty, so the v3.8.3 C#/Java same-namespace edges never applied to a graph built before they existed. The graph now records the engine generation that produced it and rebuilds once when an older engine is detected. Thanks @nigeldun.
  • doctor cleanup pass (#433, #434, #435, #437) — doctor now shows ~ instead of the absolute home path, reports the real config.toml location after an XDG split, makes its passed/total score match the checks it prints, and doctor --fix drains and removes a residual ~/.lean-ctx.
  • Dashboard "Lean" profile sticks and the settings page stops timing out (#431) — selecting Lean no longer reverts to Power (the loader self-heals the unpin sentinel), and route handlers now run on the blocking pool so a slow endpoint can't starve a trivial GET /api/settings.
  • gain dashboard shows the per-day lean-ctx version again (#307) — the "richer theme rendering" pass replaced the per-day version column with a gradient bar, so gain/gain --deep stopped attributing each day's compression rate to a release. The bar is kept and the version is re-appended.
  • macOS "access your Documents" prompt eliminated structurally (#356) — the daemon, proxy and auto-updater LaunchAgents are now wrapped in sandbox-exec with a minimal Seatbelt profile that denies access under ~/Documents, ~/Desktop and ~/Downloads, so the kernel refuses such access silently and TCC is never consulted — the prompt can no longer appear, with no "Allow" required.

3.8.7 (2026-06-15)

The macOS-privacy & dashboard-polish release. The "lean-ctx wants to access your Documents folder" prompt that kept returning after every update is fixed at the root with a stable code-signing identity; the read-only dashboard gains an in-UI Quick Settings tab, a cost-sorted live feed and a reveal-mode flag; and a batch of reliability fixes keep MCP opt-out, cache invalidation, Homebrew installs and the TUI honest.

Added

  • Dashboard: Quick Settings tab (#427) — flip the four high-impact, mid-session switches (compression level, tool profile, structure_first, terse agent) straight from the read-only dashboard. Writes go through a new /api/settings endpoint that inherits the dashboard's Bearer-token auth and CSRF-Origin check, validates every value against a fixed four-key allow-list plus the config schema, and persists to config.toml exactly like the matching CLI commands. Settings pinned by a LEAN_CTX_* env var are flagged so a toggle never silently no-ops.
  • Dashboard: sort the live call feed by cost (#426) — a Sort selector (Recent / Top saved / Largest / Slowest) ranks tool calls so you can instantly see which reads/searches/shell calls were expensive vs cheap. Read-only, reuses the existing event journal; no new routes.
  • lean-ctx dashboard --open=browser|none|vscode (#424) — an explicit reveal mode (or --no-open), resolved as flag > LEAN_CTX_DASHBOARD_OPEN > the browser default, so the dashboard no longer always hijacks the system browser when you run it inside an editor or behind a reverse proxy.

Fixed

  • macOS: the "wants to access your Documents folder" prompt no longer returns after every update (#356) — lean-ctx binaries are ad-hoc signed, so their code hash changes on every build and macOS TCC re-popped the prompt on each update (clicking "Allow" only lasted until the next build). New lean-ctx codesign-setup creates a dedicated keychain with a persistent self-signed code-signing identity and trusts it once (a single Touch ID / login-password confirmation); dev-install and the self-updater then sign every build with it, giving TCC a stable identity instead of a per-build hash. A single "Allow" now survives all future updates, and it falls back to ad-hoc signing when the identity isn't set up so the binary always runs.
  • doctor --fix now fully empties ~/.lean-ctx (#429) — the XDG split skipped any entry whose destination already existed and left the source in place, so on Windows (or after a partial run) ~30 legacy items lingered forever. Collisions are now reconciled instead of skipped: directories merge child-by-child, byte-identical files are dropped as duplicates, and a genuinely different source is moved aside as *.legacy. Nothing is overwritten or lost, so the legacy dir empties and the warning clears.
  • auto_update_mcp = false honoured on every MCP registration path (#281) — the per-agent hook writers (Claude, JetBrains, OpenClaw, Crush, OpenCode) and the editor-registry registration in setup and doctor --fix still wrote MCP server entries unconditionally. The check is now centralized, so hooks, rules and skills still install but the MCP server entry is withheld when the flag is off.
  • ctx_read map/signatures no longer serve pre-rebuild output after ctx_index build-full (#420) — the MCP tool runs in the process that owns the session cache, so a forced rebuild left map/signatures stale. It now invalidates the in-process graph cache and clears the session cache in-process, matching the CLI guarantee.
  • Dashboard auto-refreshes the active view (#425) — the poll now reloads the visible panels on a data change (preserving UI state) and catches up immediately when the tab regains focus, instead of leaving stats static until a manual reload.
  • lean-ctx watch backfills recent events on start (#560) — an idle launch showed a blank screen even when the event journal was populated; watch now seeds the last 20 events before streaming live ones.
  • Homebrew installs no longer run a stale shadowed binary (#559) — a brew-managed shim on PATH could shadow the freshly built binary so the daemon and CLI ran different builds. Installs now repoint any Cellar/linuxbrew shim at the just-installed binary and warn about any other earlier PATH entry.
  • JetBrains plugin ships under a discoverable release-asset name (#418) — the artifact is renamed to lean-ctx-jetbrains-plugin-<version>.zip so it's no longer indistinguishable from a source archive in the GitHub Release asset list.

Security

  • PathJail keeps resolving symlinks under TCC-protected dirs (#356 follow-up) — the macOS TCC choke-point is split from security canonicalization, so PathJail always resolves symlinks (no jail-escape gap) while self-initiated boot probes stay suppressed.
  • Cookbook dev-dependency upgrade — Vite 6 → 8 (#595) — the example apps build on Vite ^8 with a patched esbuild, clearing the esbuild dev-server advisory (GHSA-67mh-4wv8-2f99); npm audit reports 0 vulnerabilities.

3.8.6 (2026-06-15)

The benchmark-honesty release. Driven by an independent third-party benchmark, LeanCTX now guarantees a cold read never costs more tokens than the raw file, can bias cold reads toward structure on demand, preserves foreign build/test output verbatim at the proxy, and reconciles its savings meter to the actual provider bill (net-of-injection). CodeBuddy joins the first-class agent platforms, and a batch of capacity/robustness fixes keep the on-disk stores bounded.

Added

  • CodeBuddy AI platform support (#423, community contribution by @studyzy) — CodeBuddy joins Claude Code / Codex as a first-class agent: detection, init / setup / uninstall, MCP wiring at ~/.codebuddy/mcp.json, dedicated rules injection, and the same path-jail protection as .claude / .codex.
  • Structure-first cold reads (structure_first, #361) — an opt-in bias (off by default; env LEAN_CTX_STRUCTURE_FIRST) for auto to prefer map on a cold read of a medium-sized source file. Capability-safe: the active-diagnostic / edit-fail / small-file guards still force full.
  • lean-ctx gain reports net-of-injection bill impact (#361) — the report now shows observed proxy turns, the total injected overhead (per-turn tax × turns) and net_tokens_saved (which can go negative and says so), so the meter reconciles to the provider bill instead of a tool-local ratio.
  • Faithful benchmark arm config (#361) — bench/agent-task/r2/ ships a zero-injection, capability-safe LeanCTX arm plus the pi extension config and proxy env wiring, so an independent benchmark runs LeanCTX "installed = running as designed".

Changed

  • Suspect files are never compressed away on a fix task (#361) — when the task text explicitly names a file, auto now forces full for it ahead of any compression-favouring intent, so the agent always gets the body it needs to localise and edit the defect.
  • The proxy protects build/test fidelity and foreign tools (#361) — a generic/foreign shell result that looks like a build failure or test run is preserved verbatim at the wire (compiler errors, panics and test summaries kept intact), and vendor-prefixed tools (forge_read, pi.shell) are classified by name segment so a foreign source read is protected and a foreign shell log is compressed. Request-body compression is deterministic, keeping the provider prompt-cache prefix byte-stable.
  • The pi extension can route shell through ctx_shell (#361) — a new routeShell opt-in (env LEAN_CTX_PI_ROUTE_SHELL, implied by replace mode) suppresses the native bash builtin so build/test/log output is compressed and metered (lossless for signal).

Fixed

  • A cold read could cost more tokens than the raw file (#361) — ctx_read now enforces a hard anti-inflation invariant: a read never returns more tokens than the raw file (framing is dropped to verbatim when it would exceed the bare content), across both the MCP and the one-shot CLI paths. map also no longer repeats exports the API: section already lists with full signatures.
  • [archive] could exhaust host RAM and force a reboot (#417) — archive cleanup now enforces the age TTL and the on-disk size budget, prunes content files and the FTS index together (no more orphans), and runs at MCP start and off the hot path; lean-ctx cache prune reclaims the archive too.
  • A knowledge store could grow to 2× its fact cap on import (#417) — the bulk import path now runs the memory lifecycle as soon as it exceeds max_facts, so the eviction invariant holds on every write path.
  • Knowledge stores for deleted projects accumulated forever (#615) — doctor now reports orphaned stores and the reclaimable size, lean-ctx cache prune reclaims them, and doctor --fix prunes them; detection is conservative (a store with an existing or empty root is never touched).
  • ctx_semantic_search was hidden in the default profile (#422) — it is now a Core tool in the default ("lean") gate, and the setup/doctor tool counts are derived dynamically.
  • ctx_multi_read ignored auto mode (#421) — batch reads now honour auto per file instead of forcing every file to full.
  • ctx_read map/signatures served pre-rebuild output (#420) — graph build --force and index build-full now also flush the daemon's read cache over IPC.
  • The wake-up briefing listed dead and foreign agents (#419) — ctx_overview now prunes stale registry entries and scopes the list to the current project.
  • JetBrains plugin now ships as a downloadable GitHub Release asset (#418) — the plugin .zip is built and attached to every release; its version is single-sourced in gradle.properties and mirrors the engine release.
  • doctor reported the proxy as broken on Windows (#416) — the proxy check is now platform-aware (a warning, not a hard failure, where there is no autostart backend).
  • setup reported compression settings it never saved (#415) — success is reported only after the config is actually persisted, and doctor now reports the correct profile.
  • A data dir split across two trees could not be merged (#414) — doctor --fix now consolidates every non-canonical data tree into the canonical one (newer file wins) before the XDG split.
  • auto_update_mcp = false ignored by the hooks-layer MCP writers (#281) — the hooks integration now honours the flag on every path (the setup / onboard / init paths were fixed in 3.8.5).

3.8.5 (2026-06-14)

The JetBrains release. LeanCTX comes to IntelliJ-based IDEs: a native plugin drives PSI-accurate navigation, a refactoring engine (rename / move / inline / safe-delete) and symbolic body edits straight from the IDE — backed by a localhost-only, token-authenticated channel that re-validates every path against the project jail and falls back to headless tree-sitter edits when no IDE is reachable. Plus first-class Lua/Luau indexing, a fixed dashboard auth token for reverse-proxy setups, an on-demand XDG split so the config dir can be mounted read-only, and multilingual intent routing.

Added

  • JetBrains / IntelliJ IDE plugin (#413, community contribution by @dasTholo) — a native plugin that runs LeanCTX from inside JetBrains IDEs: PSI-backed navigation, a refactoring engine (rename / move / inline / safe-delete), symbolic body edits and an in-IDE tool window. The engine gains a matching ctx_refactor surface and an LSP layer that talks to the IDE over a localhost-only, token-authenticated channel and re-validates every plugin-reported path against the project jail (BLAKE3 conflict guard, atomic writes). It also works headless — tree-sitter range edits without a running IDE. Kotlin / Kotlin-Script (.kt / .kts) are now recognised for indexing.
  • First-class Lua / Luau graph indexing (#360) — symbols, require edges and the call graph are now extracted for Lua and Luau sources.
  • lean-ctx dashboard --auth-token (#377) — a fixed dashboard auth token via flag or env (env takes precedence) for reverse-proxy deployments, with token-aware connection reuse.
  • lean-ctx doctor --fix splits a legacy/mixed install into the XDG dirs (#408) — moves data/state/cache out of the config dir on demand. The migration is all-or-nothing, idempotent/resumable (existing files are never clobbered) and crash-safe (atomic rename with a copy+remove fallback across filesystems). Read-only lean-ctx doctor reports a pending split. New per-category overrides LEAN_CTX_CONFIG_DIR, LEAN_CTX_STATE_DIR, LEAN_CTX_CACHE_DIR.
  • Multilingual intent routing (#591) — intent detection now handles non-English queries.

Changed

  • XDG Base Directory compliance (#408) — LeanCTX now separates its files into the standard XDG categories so the config dir can be mounted read-only: config (config.toml, shell hooks) → $XDG_CONFIG_HOME/lean-ctx; data (sessions, vectors, graphs, knowledge, stats.json) → $XDG_DATA_HOME/lean-ctx (the fresh-install default flips here); state (events, journals, logs, agent_runtime_env.json) → $XDG_STATE_HOME/lean-ctx; cache (semantic cache, models) → $XDG_CACHE_HOME/lean-ctx. Existing legacy (~/.lean-ctx) and mixed installs keep working unchanged in single-dir mode, and an explicit LEAN_CTX_DATA_DIR still forces one directory.
  • pi-lean-ctx bridge tool parity (#409) — ctx_search, ctx_tree and ctx_multi_read are now exposed through the Pi bridge, guarded by a Node CI gate.

Fixed

  • Embedding index clobbered by parallel remember (#412) — embedding-index writes are now serialized under the per-project lock, fixing degraded recall when multiple remember calls raced.
  • auto_update_mcp = false ignored during setup/onboard/init (#281) — the setting is now honored across all three paths.
  • Session extra_roots not honored in path resolution (#403) — extra roots are propagated at init and respected by the resolver.
  • Verbatim reads compressed on the CLI path (#404) — verbatim reads are now exempt from terse compression on the CLI.
  • Config::load served stale config (#406, #407) — the load cache is now invalidated by content hash so live edits apply immediately.
  • pi-lean-ctx MCP bridge did not shut down cleanly (#405).

Security

  • Captured agent API keys now stored in the state dir at 0o600 (#408) — keys such as GEMINI_API_KEY no longer sit alongside config files.
  • esbuild forced to ≥0.28.1 in the cookbook (#595) — closes GHSA-gv7w-rqvm-qjhr (dev-scope: missing binary integrity verification) by deduping the whole cookbook tree onto a patched esbuild.

3.8.4 (2026-06-13)

The Stay-In-Scope Patch. When you point ctx_tree, ctx_search or ctx_glob at a path outside the project, you now get a clear "out of scope" error instead of the entire repository tree for an unrelated directory.

Fixed

  • ctx_tree/ctx_search/ctx_glob ignored an out-of-scope path (#401) — when an explicit path (or paths) argument pointed outside the project root, or was otherwise unresolvable, the tools silently fell back to the project root and returned the whole repository tree for an unrelated path. The resolution error is now surfaced (ERROR: path escapes project root …) instead of a misleading full-tree result. Non-existent paths inside the project keep their clear "does not exist" message.

3.8.3 (2026-06-13)

The Lean-Session Patch. The fixed cost your editor pays every single session drops by more than half — 13 lazy-core tools instead of 61, schemas on a diet, instructions capped — and two new commands (doctor overhead, rules dedup) show and remove what's still duplicated. ctx_impact now understands type usage, not just imports, so same-namespace C# classes stop hiding from impact analysis. macOS privacy prompts are silenced at a second root, and node_modules stays out of your overview even when there is no .git to anchor a .gitignore.

Added

  • lean-ctx doctor overhead (#572) — per-client fixed-cost report: how many tokens your editor pays every session for tool schemas, instructions and rules files, with duplicate detection across CLAUDE.md, .cursorrules and AGENTS.md.
  • lean-ctx rules dedup [--apply] (#578) — finds and removes lean-ctx-owned duplicate rule files and stale marked blocks across editors. The .cursorrules template is now a pointer to the canonical rules, and the compression block is no longer double-injected for Cursor.

Changed

  • Lean default tool surface (#575) — setup no longer pins a tool_profile; the default surface is 13 lazy-core tools instead of 61. lean-ctx tools lean/reset manage it explicitly. Together with the schema diet (#576, core schemas −36%) and the instructions cap (#579, static skeleton ≤400–500 tokens), the fixed per-session overhead drops from ~13.7K to ~6.0K tokens on a typical setup.
  • Honest metrics (#573) — dashboard, footer and ledger report observed tokens only; the modeled 2.5× grep baseline moves to the estimated series. ctx_cost splits cached vs uncached input at cache-read pricing, and the benchmark measures the real CCP resume payload.
  • Self-describing outputs (#580) — plain notation uses real language keywords (struct/trait/pub), and TDD symbol outputs carry a minimal inline legend (≤15 tokens) so agents never have to guess the notation.
  • Codex: native rewrite instead of block-and-retry (#399, community contribution) — on Codex ≥ 0.20 the PreToolUse hook returns updatedInput to rewrite shell commands through lean-ctx in place, eliminating the deny + model-retry round-trip per command. Also bumps the postgres crate family past three fresh RUSTSEC advisories.

Fixed

  • lean-ctx overview flooded the terminal with thousands of node_modules entries (#400) — the ignore crate only applies .gitignore files inside git repositories, so a monorepo whose subprojects carry their own .gitignore but whose root is not a git repo had every scanner walk node_modules wholesale (74k+ files in the report). All 15 directory walkers — graph/BM25/trigram index builders, ctx_impact, search/tree/glob, CLI scans — now share one filter that prunes unambiguous vendor directories (node_modules, __pycache__, bower_components, virtualenvs with a pyvenv.cfg) regardless of git state, and .gitignore files now apply even without a .git directory. Explicitly requested vendor paths stay reachable, and respect_gitignore=false remains the escape hatch.
  • macOS privacy prompts kept appearing while the MCP server was running (#356 follow-up) — editors spawn the user-level server with cwd == $HOME; a search/tree/glob call whose path fell back to "." then walked the entire home directory, and every stat under ~/Library, ~/Desktop, ~/Pictures fired a TCC prompt (Calendar, Reminders, Contacts, Photos) while burning 10–20 s per call. The index builders already refused broad roots; the direct walks now share the same guard. Relative paths are absolutized first, so lean-ctx grep/ls inside a real project keep working — broad or privacy-protected roots return an actionable error instead of silently scanning.
  • ctx_impact missed C# dependencies without using directives (#398) — C# resolves same-namespace types without any import, and DI-style code never news its dependencies, so a class consumed only as a type (constructor parameter, field, property, base class, generic argument) produced zero graph edges and a false "no files depend on X". The builder now extracts type usages from the AST for C# and Java and links consumer files to defining files with type_ref edges that impact analysis traverses. Names defined in more than 3 files are skipped as too generic to attribute.
  • DI-consumed classes were flagged as dead_code — same root cause, second symptom: the smell query already exempted type_ref targets, but nothing ever created those edges. Symbol-level type references now clear genuinely used classes while unreferenced ones still get flagged.

3.8.2 (2026-06-12)

The Quiet-Upgrade Patch. Five field reports closed for good: the macOS "access your Documents folder" prompt that came back on every upgrade is gone at the root (the launchd daemon no longer touches protected folders at boot), Linux projects under /c/… paths work again (the MSYS drive mapping is now Windows-only), OpenCode's ChatGPT subscription works behind the proxy again, lean-ctx doctor stops demanding a rules file that setup intentionally retired, and Pi's search tools can no longer wander into the wrong directory. Plus a faster, honest dashboard feed.

Fixed

  • Linux: ctx_* tools broke for projects under /c/… and other single-letter roots (#397) — the MSYS2/Git-Bash drive mapping (/c/Users/… → C:/Users/…) ran unconditionally in the MCP path normalizer; on Linux/macOS /c/… is a literal directory, so every file tool failed on a nonexistent C:/… path. The mapping is now applied on Windows hosts only — everywhere else the path passes through untouched.
  • macOS prompted "lean-ctx would like to access files in your Documents folder" on every upgrade (#356) — the prompt came from the launchd daemon's boot path: it walked every stored session (stat + canonicalize on paths under ~/Documents) and ran realpath over every context-ledger entry. Since the daemon is its own TCC identity and every update swaps the binary (new code hash → grant invalidated), each release re-prompted. Traced with a deny-sandbox + crash-stack bisection; broad roots now bail out before any scan, ledger dedupe keys are lexical-only, and launchd-owned processes never probe ~/Documents/Desktop/Downloads in heuristics. Editor and CLI sessions inherit their host's grant and keep full behavior.
  • OpenCode × ChatGPT-OAuth broke behind the proxy (#366) — proxy enable exported OPENAI_BASE_URL without the /v1 suffix, so OpenCode's OAuth plugin failed to recognize Responses-API routes and subscription traffic leaked to the platform API ("Missing scopes: api.responses.write"). The proxy now advertises http://127.0.0.1:<port>/v1, migrates stale Codex config.toml entries, and collapses accidental /v1/v1 prefixes. Verified end-to-end against OpenCode 1.2.15.
  • lean-ctx doctor reported "no rules file found" right after setup (#396) — 3.8 replaced the always-loaded ~/.claude/rules/lean-ctx.md with a CLAUDE.md block + on-demand skill, and setup removes the legacy file — but the doctor check still demanded it, so a clean install could never reach a full pass. Both doctor views now share one layout detector that accepts every state setup can produce.
  • Pi: ctx_grep/ctx_find/ctx_ls silently searched the wrong directory (#395) — path was optional and fell back to the extension's cwd; it is now required, and the three tools reuse Pi's native call renderers so every invocation shows its pattern and directory in the transcript.
  • Dashboard: token race, masked errors, "No session" while agents were active — the auth token is saved only after a successful port bind (no more silent 401s after racing starts), a failed events poll shows the actual error instead of "No events recorded yet", and the status bar falls back to the most recently updated real-project session.

Performance

  • /api/events no longer re-parses the event log on every poll — the file-backed event load is cached on (path, mtime, length); the 3-second dashboard poll now costs a stat() instead of parsing up to 10k JSONL lines.

3.8.1 (2026-06-12)

The Field-Report Patch. Five issues straight from users' terminals, fixed the same week 3.8.0 shipped: --help that executed instead of explaining, allow_paths that matched ~ and $VAR literally, and three closed ctx_shell hardening gaps from a community security report — plus service file paths where you need them and a new daemon restart.

Added

  • lean-ctx daemon restart (#394) — bounces the daemon through whichever channel is active: the supervised service (LaunchAgent / systemd) and/or a manually started process.
  • Service file paths are printed where you need them (#394) — daemon enable/disable print the exact LaunchAgent plist / systemd user unit path, and daemon status + lean-ctx doctor show the unit name, file path and supervision state — no more hunting for the right launchctl/systemctl --user target.
  • lean-ctx doctor path-jail diagnostics (#392) — doctor now reports the effective jail state (active, path_jail = false, or a compile-time no-jail build) and flags allow_paths entries that can never match: unset $VARs and directories that don't exist.

Fixed

  • daemon enable --help executed instead of showing help (#393) — --help/-h anywhere in lean-ctx daemon, lean-ctx proxy or lean-ctx allow now prints usage and never executes the verb. Previously an agent in read-only plan mode installed the systemd service by asking for documentation.
  • allow_paths with ~ or $VAR never matched (#392) — config files see no shell, so "$HOME/code" was compared literally and PathJail kept rejecting paths you had explicitly allowed. Entries in allow_paths/extra_roots (and the corresponding env vars) are now tilde- and variable-expanded; unset variables warn instead of silently never matching.

Security

  • ctx_shell hardening (#391) — three gaps from a community security report are closed: download-to-file flags (curl -o, wget's file-download mode, dd of=) are now treated as file writes and blocked like > redirects; xargs/nohup delegation can no longer smuggle inline code past the interpreter block; and shell_strict_mode = true now actually blocks command substitution and pipe-to-bare-interpreter — both previously logged "Blocked" while letting the command run. SECURITY.md now states the threat model explicitly: defense in depth against agent mistakes, not an OS sandbox.

3.8.0 (2026-06-12)

The Governance & Proof release. Agents become accountable identities, context gets enforceable policy, and savings become auditable evidence: agent registry, deterministic evidence bundles with an offline verifier, EU AI Act / ISO 42001 / SOC 2 coverage reports, org SSO and audit log, and a FinOps surface that exports the signed ledger to Datadog, CloudZero, Vantage and FOCUS. The platform opens up — SDKs, personas, plugins, WASM — while the dashboard reorganizes around the four jobs. Every local feature stays free.

Added

  • Adaptive Learning — the engine now tunes itself from outcomes — seven research-driven layers: per-file-type compression thresholds learned from bounces and edit failures (clamped, daily decay), lost-in-the-middle placement calibrated against your client's measured recalls, a stigmergic scent field for parallel agents (ctx_agent claim/release, foreign-claim warnings in ctx_read), delta playbooks that survive checkpoints without context collapse, query-conditioned compression, theta-gamma chunked wakeups, and semantic redundancy filtering. Inspect with lean-ctx learning, share team-wide with learning export/import (secret-free, idempotent merges), and verify impact in the Learning Efficacy section of ctx_metrics or the dashboard's Trends page. See Adaptive Learning.
  • Self-activating embeddings — the first semantic need downloads the local ONNX model in the background (SHA-256 pinned) and warms the engine; no hot path blocks. Air-gapped machines opt out with [embedding] auto_download = false and semantic layers stay off gracefully.
  • ctx_git_read — read a remote repo via a cached shallow clone — point it at a public GitHub/GitLab/Bitbucket URL and browse the file tree, read a file, or grep across the repo. Unlike scraping a blob page (which returns navigation chrome), the --depth 1 clone is cached and reused, so reads return the real source within a token budget. SSRF-guarded (public https only).
  • ctx_checkpoint — a shadow git history of the agent's changes — snapshot, log, diff, and restore the LLM's own edits through a history kept entirely separate from your project's .git. Capture the working tree before and after a change to see exactly what was modified, then roll back if needed — without ever touching your real commits or branches.
  • ctx_url_read: RSS/Atom feeds, tables, and GitHub raw — feeds are parsed into a dated list of items (title, link, summary) instead of raw XML; HTML tables now render as GitHub-Flavored Markdown so tabular data survives the trip into context; and GitHub blob/raw URLs auto-resolve to the underlying file. See Web & Research.
  • Session continuity — ctx_summary, ctx_package & ctx_skillify — carry context across sessions and agents: ctx_summary records and recalls compact digests of what was done (task, files, decisions, next steps); ctx_package saves or resumes a portable JSON bundle of session state, summaries and knowledge for a clean hand-off; and ctx_skillify distils recurring patterns from the project's session diary into versioned, git-committable .cursor/rules/ files. Brings the granular tool surface to 76.
  • Open Door — SDKs & a versioned /v1 API — run lean-ctx serve (default :8080) and drive the same compression, memory and tools from your own loop via first-party Python (leanctx), TypeScript (@leanctx/sdk) and Rust (lean-ctx-client) clients. Discover the surface with GET /v1/capabilities and GET /v1/openapi.json; framework adapters ship for OpenAI, LangChain, LlamaIndex and CrewAI. See the API Reference.
  • Context Personas — set LEAN_CTX_PERSONA to reshape the whole session: tool surface, default read modes, compressors and a sensitivity floor. Built-ins cover coding, research, support, data-analysis and lead-gen; drop a TOML file in the personas directory to define your own.
  • Universal Intake — ctx_index format extractors — index a mixed local corpus beyond source code: PDF, HTML, CSV/TSV, EML and JSON/NDJSON are extracted and chunked locally, so non-code documents become searchable agent context.
  • Open Core — plugins & WASM extensions — extend LeanCTX without forking: a plugin.toml manifest with lifecycle hooks (lean-ctx plugin init|list|enable) and WebAssembly compressors/chunkers loaded from LEAN_CTX_WASM_DIR. Verify the contract with lean-ctx conformance.
  • Pro — your Personal Cloud (optional, additive) — lean-ctx cloud upgrade opens a self-serve checkout for the hosted Personal Cloud: cross-device sync and backup of your own learned context — knowledge, memory, learned shell patterns, CEP score history and gotchas — for one account at $9/month or $90/year. Every local feature stays free and ungated; see Pricing.
  • Team plane (optional, additive) — lean-ctx team serve with RBAC tokens (--role viewer|member|admin|owner), lean-ctx billing plans|usage and lean-ctx savings roi over a signed savings ledger. Local single-user features stay free and ungated — the Local-Free Invariant.
  • Graph & dashboard hardening — the dependency and call graph now resolve C# using against the namespace each file declares (real edges, not just folder names), scope callee resolution to a caller's own file and imports to cut false positives, and detect staleness by content hash so graph build — and the new graph build --force — reflect the current source without needless rescans. The dashboard memoizes expensive analyses behind a bounded cache, caps betweenness centrality on large graphs with a "sampled" disclosure, and renders an honest per-language capability legend (symbols / imports / call graph, with real per-project counts) instead of a generic "build index" hint.
  • pack verify — standalone conformance verification — verify any .ctxpkg file without installing it: structure, both integrity hashes and the ed25519 signature, reported per check with CI-friendly exit codes. The same checks run against the official conformance vectors, and import is hardened to match: signed packages whose signature does not verify are rejected, and integrity hashing now follows spec §8 exactly (document-text based, so packages survive cross-language round-trips). Tokens and publishing live on ctxpkg.com.
  • Framework compliance reports — policy coverage --framework — machine-readable control mappings for the EU AI Act, ISO/IEC 42001 and SOC 2 ship in-repo, each control tied to the mechanism that addresses it. The report verifies your resolved policy pack live and renders every control as enforced, engine guarantee, not-enforced (exit 1, CI-gateable) or a documented gap — never a vague "compliant". Three framework template packs (eu-ai-act-deployer, iso42001-aligned, soc2-context) turn the mappings into enforceable defaults. See Compliance & Evidence.
  • Evidence bundles — lean-ctx audit evidence + standalone leanctx-verify — export a deterministic, Ed25519-signed ZIP (open contract evidence-bundle-v1) containing the tamper-evident audit-chain segment, the resolved policy pack and the coverage reports for a reporting period. Auditors verify it offline with leanctx-verify, a separate minimal-dependency binary that independently re-implements the contract — replaying the hash chain and checking every signature without trusting the generator. Identical inputs produce byte-identical bundles.
  • First-class agent identities — lean-ctx agent — register agents with a stable id, a role and a mandatory human owner; suspend, resume and decommission them with every transition written to the tamper-evident audit trail. agent offboard-owner suspends all of a departing owner's agents in one locked transaction (SCIM-ready), heartbeats re-attest the binary and role config to surface drift, and each identity carries a SPIFFE-compatible workload id. See Agent Governance.
  • Open Context Protocol v0.1-draft — the governance layer is now specified outside the product: Context-IR, capability vocabulary, policy packs, evidence chain and event vocabulary as an open spec with JSON Schemas. LeanCTX is the reference implementation and validates its own exports against the published schemas in CI. See the protocol page.
  • Closed-loop context intelligence — every signal feeds back — six new signal loops sharpen what gets read and how: a persistent per-path bounce memory steers mode=auto away from modes that made the agent re-read; git churn and recency lift hot files in ranking, preload and triage; build diagnostics are extracted structurally and prioritised; the editor's active file (VS Code) boosts what you're actually working on; output-echo detection notices when the agent merely repeats tool output and feeds that into CEP scoring; and a quality loop penalises compression modes that preceded failed edits. Watch them work in the dashboard's Live Signals panel with bounce-rate and output-echo trend sparklines.
  • Teams & orgs in the cloud plane — a minimal org model (organisations, memberships, owner role), self-serve OIDC SSO without a sales call, org-wide audit log with configurable retention, and team-server GET /v1/storage + GET /v1/usage endpoints. Hosted-index SLOs are now public: leanctx.com/status renders a 30-day fleet aggregate from real probe data — proof, not promise.
  • Zero-knowledge Personal Cloud sync — knowledge sync is encrypted client-side before upload; the server stores ciphertext it cannot read. Your learned context stays yours even on our infrastructure.
  • GDPR self-service — one-click data export (Art. 20) and irreversible account deletion (Art. 17) directly from the account page, no support ticket required.
  • FinOps integration — the signed ledger reaches your cost stack — lean-ctx finops export emits FOCUS 1.0 (the FinOps Foundation's open billing format), CloudZero AnyCost and Vantage CSV from the Ed25519-signed savings ledger, and lean-ctx datadog setup pushes the same series to Datadog (agent or agentless) with a ready-made dashboard template. Provenance is explicit: every export marks rows as measured (signed ledger) or estimated.
  • Dashboard: the four-jobs redesign — the cockpit now tells the same story as the product: Context (decides what agents read), Memory (remembers what agents learn), Proof (proves what you save) and Project Map (understands your codebase). Slim Home with a verified-receipt hero, Simple mode = the 5-second answer, and a Methodology card that separates verified (signed ledger) from estimated savings.
  • Custom embedding models — point [embedding] model = "hf:org/repo" at any HuggingFace repo with an ONNX export: revision pinning, SHA-256 lockfiles against silent upstream swaps, automatic dimension probing — plus model2vec static embeddings (~500× faster inference at ~30 MB) for big-repo indexing on weak hardware.
  • LoCoMo memory benchmark — a model-free, deterministic retrieval-recall harness over LoCoMo-style long conversations, with committed reference numbers (100% answer containment@5 at 29.4% token reduction) and a CI smoke test. Memory claims are now benchmarked, not asserted.

Security

  • P0 hardening series — the CLI shell allowlist is now enforced for agents (not just warned), cloud credentials are written 0o600 atomically, relative tool paths never resolve against the daemon's CWD, the proxy can no longer start unauthenticated, ctx_edit rejects symlinks (TOCTOU), cloud/infra CLIs (terraform, kubectl, aws, …) left the default allowlist, and home-level IDE config dirs (~/.cursor, ~/.claude) are jail-opt-in.
  • Dashboard output encoding is attribute-safe — every HTML escape helper now also encodes quotes, so untrusted strings (file paths, knowledge keys, agent names) can no longer break out of HTML attributes. Resolves all open CodeQL XSS findings.

Fixed

  • MCP failures finally say so (#389) — failed shell commands and tool errors now set the MCP isError flag with structured exit-code metadata, so agents stop treating a failed build as a successful read.
  • MCP token footprint cut (#385) — tool schemas and server instructions were re-measured and trimmed; the per-session fixed cost drops measurably without losing capability.
  • Claude Code instruction footprint: ~12k → <500 tokens — the injected rules block for Claude is now a compact pointer instead of the full ruleset, and a PreCompact hook preserves session continuity across Claude's context compaction.
  • Proxy history pruning is now prompt-cache-safe — the rolling-window pruner trimmed history in a way that shifted earlier messages and invalidated Anthropic/OpenAI prompt caches on every turn; pruning now preserves stable prefixes so provider-side caching keeps paying off.
  • Proxy no longer breaks Claude Pro/Max subscriptions — proxy enable detects when no Anthropic API key is available and skips the Claude redirect (OAuth subscription tokens are rejected by custom base URLs), repairing stale redirects from earlier versions; doctor flags the misconfiguration with the exact fix.
  • Windows: proxy survives MCP process recycling — clients that recycle their MCP child process (OpenCode, Codex) no longer kill the proxy (job-object isolation), and tool schemas pass strict JSON-Schema validators (#390).
  • Shell parser understands >| and here-strings (#387) — clobber redirects and <<< no longer confuse the allowlist parser into misclassifying commands.
  • No more crashes on multibyte text (#379, #386) — every truncation site snaps to UTF-8 character boundaries, and deep ASTs no longer overflow the indexer stack (#378); panics now land in ~/.lean-ctx/logs/crash.log instead of vanishing with the daemon.
  • Uninstall leaves zero leftovers — lean-ctx uninstall now guarantees a perfect clean across all agent integrations: configs, rules, hooks, LaunchAgents and caches.
  • Update notice no longer freezes — the dashboard refreshes its version cache instead of pinning the first-seen release, and the terminal hint matches the actually available version.
  • ctx_edit evidence diffs are exact — terse post-processing no longer corrupts the evidence diff attached to edit results.
  • Audit chain is now fork-proof under concurrent writers — multiple LeanCTX processes appending audit entries at once could previously chain onto the same predecessor hash, forking the tamper-evidence chain. Appends now take a cross-process file lock and read the true last hash from disk under that lock. Found by our own leanctx-verify during evidence-bundle development — the verifier caught a real bug before any auditor did.
  • Signed artifacts always embed the key that actually signed them — handoff transfer bundles, evidence bundles and wrapped publish previously resolved the signing keypair twice (once to sign, once to read the public key); a concurrent key regeneration between the two reads could produce an artifact whose embedded key never verifies its own signature. New atomic signing APIs resolve the keypair exactly once.
  • Scorecard determinism restored — benchmark entropy numbers fed the reproducibility digest through the regular compression path, where the opportunistic semantic filter activates as soon as the embedding engine finishes loading — two runs could disagree. Benchmarks now pin the filter off, keeping the digest machine-independent.

3.7.5 (2026-06-06)

The Web & Research release. LeanCTX reaches beyond the codebase: agents can now pull the web, PDFs and YouTube into context as compressed, citation-backed text — plus three field-reported fixes (cloud-placeholder scans, OpenAI-compatible proxy keys, the Pi session cache).

Added

  • Web & Research layer — ctx_url_read — fetch a public web page, PDF, or YouTube video and get back compressed, citation-backed context: HTML/PDF to clean text, YouTube to transcript. The facts and quotes modes return discrete claims, each with a confidence score and source URL, so web research is auditable. Relevance-ranked research-compression distils a whole page down to a token budget, and fetching is SSRF-guarded (http/https only, private and loopback blocked). Brought the granular tool surface to 68. See Web & Research.

Fixed

  • Background scans never hydrate cloud placeholders (#363) — directory walks now skip OneDrive "Files On-Demand" / iCloud "dataless" placeholders by reading file attributes only, so starting an agent in or above a cloud-synced folder no longer triggers a redownload or OneDrive sync warnings. The search index also no longer auto-indexes your home directory.
  • Proxy accepts OpenAI-compatible provider keys (#362) — the loopback auth gate now accepts any non-empty provider credential (not just sk-/gsk_), so OpenCode pointed at an OpenAI-compatible upstream is no longer rejected with a 401.
  • Pi: the embedded MCP bridge is on by default (#361) — the persistent session cache now engages out of the box, and every ctx_read (including line-range reads) routes through it, so unchanged re-reads cost ~13 tokens instead of re-sending the file.

3.7.4 (2026-06-05)

The Superintelligence Context release. Six cross-disciplinary North-Star bets shipped — active-context prefetch that learns which providers help, task-conditioned compression, self-managing memory, a context immune system (signed audit + prompt-injection detection), stigmergic swarm credit, and a physically-grounded energy and carbon ledger — plus a heavy performance pass (int8 embeddings, SIMD search, shared content cache, lazy startup, JSON compaction), IDE permission inheritance, opt-out instruction-file injection, and three new --json CLI commands. Everything new is free OSS.

Added

  • Active-context prefetch that learns — ctx_preload's provider bandit (Thompson sampling) is now persisted per project, so lean-ctx learns which data sources actually pay off for a given kind of task and prefetches those, instead of starting from zero on every call.
  • Task-conditioned compression — the entropy read-mode now keeps low-entropy lines that are relevant to the active task (an Information-Bottleneck proxy): it compresses away only what is both uninformative and off-task, and falls back to pure entropy when no task intent is active.
  • Context immune system — audit-trail entries are now Ed25519-signed for cryptographic provenance, and a conservative prompt-injection detector scans tool output for role-override / token-smuggling patterns, emitting a security audit event on a hit.
  • Stigmergic swarm credit — the access heatmap now records per-agent traces and computes Shapley-inspired "context credit": when several agents use the same file, each contributor is credited for the shared context that helped.
  • Self-managing memory — the background cognition loop (consolidate / synthesize / decay / compact) now actually runs on its own, time-gated and single-flight, and a fact's thumbs-up/down feedback steers how fast it decays.
  • Energy and carbon ledger — ctx_gain now reports estimated grid energy and CO₂e avoided (configurable grid intensity via LEAN_CTX_GRID_CO2_G_PER_KWH), so the savings ledger's environmental dividend is auditable, not just cosmetic.
  • IDE permission inheritance — a new permission_inheritance option (off by default) makes lean-ctx mirror your IDE's permission rules onto its own tools, so a deny/ask on bash in OpenCode also guards ctx_shell. Read-only and runtime-only — lean-ctx never writes your permission config.
  • Opt out of touching shared instruction files (#343) — the new rules_injection = dedicated mode never edits your CLAUDE.md / AGENTS.md / GEMINI.md; it uses each agent's own config-driven, fully-removable auto-load path instead. Default shared keeps today's behavior.
  • Three new --json CLI commands — lean-ctx semantic-search (fixes the editor search path), lean-ctx repomap, and lean-ctx knowledge recall all gain structured output for editor and script use.
  • Dashboard subpath mounting (#355) — dashboard --base-path serves the web dashboard under a subpath behind a reverse proxy.

Performance

  • Shared file-content cache removes the search double-read (#148) — the index build, ctx_search, and BM25 now share a single in-memory copy per file (LRU, invalidated by mtime+size) instead of reading the corpus from disk two or three times.
  • Lazy, demand-driven startup (#152) — a session that only reads/greps/lists pays zero startup indexing cost; the graph/BM25 index warms once, in the background, on the first tool that actually needs it.
  • int8-quantized embeddings + SIMD dense search — embedding vectors are int8-quantized (~4× smaller resident index) with a SIMD cosine kernel and a threshold-gated HNSW cache, so small projects stay light and large ones get sublinear search.
  • Lossless JSON/JSONL compaction — large structured tool output is compacted losslessly before counting, costing fewer tokens without changing a single value.
  • Read-mostly session cache (#147, #149) — the common ctx_read flow serves session state from a read-mostly cache and moves telemetry off the hot path.
  • Bounded cold BM25 build (#150) and a proxy that parses each request body once and protects multi-file reads from lossy compression.

Changed

  • Tool registry is the single schema source (#141) — per-tool schemas are generated from one registry instead of maintained in parallel, retiring a recurring drift source (guarded by a regression test).
  • Unified path resolution (#145) and tool descriptions that steer agents toward the ctx_* tools (#168).
  • Guarded dispatch refactor (#144) — the ~1000-line post-processing path is split into unit-tested, composable stages with identical behavior.

Fixed

  • Full profile surface for dynamic-tools clients (#358) — clients using dynamic tool categories now see the complete tools/list and the always-on ctx_call gateway, so no tool is unreachable.
  • Proxy accepts bare provider endpoints for the OpenCode Responses API (#353) — a base URL without the full path suffix is normalized and routed instead of failing.
  • macOS install/update no longer touches ~/Documents (#356) — avoids spurious permission prompts and stray files.
  • Dashboard tooltips never clip (#357) — info-tips are portaled to <body> so they render above surrounding cards.
  • Runtime robustness — bounded write-ahead log, dead-owner lock reclaim, corrected knowledge-fact eviction, and tuned lean-ctx doctor thresholds.
  • Pi: explicit LEAN_CTX_PI_ENABLE_MCP=1 now always starts the embedded MCP bridge (#361) — a lean-ctx entry in ~/.pi/agent/mcp.json no longer silently disables the embedded bridge. Pi has no native MCP support, so that entry alone never served the tools, and the session cache (with its ~13-token re-reads) never engaged. The explicit flag now wins.
  • Dashboard graph/code-map shows a clear language message instead of an endless loading state (#360) — for projects in languages the code-map does not index (e.g. Lua/Luau), the Dependencies, Symbols and Roads views now explain that the graph supports specific languages and that BM25 search/compression still work, instead of suggesting an index rebuild that can never populate the graph.
  • Deterministic HNSW index construction — the approximate-nearest-neighbor index seeds each node's level from its insertion index (splitmix64) instead of OS entropy, so the same corpus always builds the same graph and returns the same results. Semantic-search results are now reproducible.

3.7.3 (2026-06-04)

Compression where the agent actually is — and fidelity where it matters. A shell MCP tool so the Codex Desktop/Cloud app compresses even without lifecycle hooks, an additive self-diagnosing shell allowlist, navigation output with line ranges, already-compact (TOON) passthrough, OpenAI Responses API support, and a proxy that protects file reads mid-refactor.

Added

  • OpenAI Responses API support in the proxy (#346, thanks @Lctrs) — clients on OpenAI's new Responses API (POST /v1/responses) were forwarded untouched because the proxy only understood Chat Completions. The proxy now compresses each function_call_output.output through the same pattern pipeline, while leaving the input array structurally intact so a function_call is never split from its matching output. /status now reports an accurate token breakdown for Responses requests.
  • A shell MCP tool for the Codex Desktop/Cloud app (#337) — the app loads the MCP server but its agent reaches for a native shell/Bash tool, so hook-driven compression never triggered. lean-ctx now exposes a shell tool (familiar name, model-optimized description) that transparently delegates to the same 95+-pattern pipeline as ctx_shell. Registered for all MCP clients.
  • lean-ctx allow <cmd> (#341) — permit a binary on the shell allowlist additively via the new shell_allowlist_extra field, so allowing e.g. acli keeps git/cargo/npm intact instead of replacing the whole list. --list shows the effective allowlist plus the exact config path; --remove reverts. Picked up on the next command — no restart.
  • Line ranges in map / signatures output (#340, thanks @iohansson) — every entity in the navigation views now carries a compact @Lstart[-end] suffix (e.g. fn build() → Config @L42-58), so an agent jumps straight to a symbol instead of issuing a follow-up search. Mode-aware: compression-first paths stay byte-identical.
  • Format-aware passthrough for already-compact output (#342, thanks @pomazanbohdan) — ctx_shell / lean-ctx -c no longer recompress output that is already in a compact format. TOON is detected by its structural markers and returned verbatim. Controlled by the new preserve_compact_formats config (default ["toon"]).
  • Pi-native configuration (#344, thanks @michaelmior) — an optional ~/.pi/agent/extensions/pi-lean-ctx/config.json lets Pi-only users keep mode, MCP toggle, binary path, and engine env overrides in their Pi config instead of juggling LEAN_CTX_PI_* env vars. Explicit env vars still win; a malformed file falls back cleanly.
  • VS Code / Cursor extension, now publishable — the editor extension is consolidated into a single, marketplace-ready package and shipped to the VS Code Marketplace and Open VSX (Cursor, VSCodium, Windsurf), with binary auto-detection, one-click workspace MCP wiring, and setup / doctor / gain commands.

Changed

  • Identifier α-substitution (§MAP) is now opt-in (#351) — aggressive reads used to replace long identifiers with short α-codes above 50 source files. External testing found this obscured package/symbol names exactly when editing. It is now off by default; set symbol_map_auto = true (or LEAN_CTX_SYMBOL_MAP=1) to opt back in.
  • Editing intents always read the full file (#351) — when the task classifies as refactor, fix-bug, or generate, auto-mode reads resolve to full regardless of model tier. You cannot safely edit a file you can only partially see. Exploration/review intents still compress.
  • Per-model cost breakdown in the proxy (#351) — /status reports a per_model array (requests, estimated tokens saved, USD saved priced from the shared model table) instead of one flat number, and discloses that savings are request-side estimates.

Fixed

  • Proxy no longer mangles file/source reads (#351) — the request-compressing proxy treated every tool result as shell output, so a large source-file read was run through command-output truncation on the next turn, gutting the file the model was mid-refactor on and forcing an uncounted re-read. The proxy now resolves each result's originating tool and never lossy-compresses a file read or source-like content, across all four providers (Anthropic, OpenAI Chat, OpenAI Responses, Gemini). History pruning emits an honest "re-read the file" stub instead of a misleading excerpt.
  • Proxy stopped failing large-refactor and long-generation calls (#351) — the 10 MiB request-body ceiling is now 64 MiB (LEAN_CTX_PROXY_MAX_BODY_MB), and the single 2-minute total timeout is replaced by connect + read-idle timeouts (defaults 15s / 300s), so a slow-but-alive stream is never cut while a genuinely dead upstream still fails.
  • Codex instructions no longer claim Desktop "can't" run hooks (#350, thanks @iohansson) — the injected AGENTS.md / LEAN-CTX.md block asserted as fact that Codex Desktop/Cloud lifecycle hooks do not run, which is false (they do, trust-gated via /hooks). The docs now make no surface-specific hook claim and frame the MCP/CLI tools as the path that compresses reliably on every surface; lean-ctx doctor's Codex note is corrected to match.
  • MCP stdio stays protocol-clean (#348, thanks @gai095481) — confirmed and regression-guarded that all tracing diagnostics route to stderr, never the stdout JSON-RPC transport, so a log line can never be interleaved into an MCP client's message stream and break parsing.
  • shell_allowlist edits silently ignored in MCP/editor mode (#341) — allowlist changes looked like no-ops because a malformed config fell back to defaults with the warning only on stderr (invisible over stdio), setting shell_allowlist replaced the whole default list (now solved by additive shell_allowlist_extra), and the block message didn't name the config path the runtime actually reads. lean-ctx doctor gains a "Shell allowlist" check.

3.7.1 (2026-06-03)

Wrapped Viral-Loop — the honest Wrapped recap is now shareable end-to-end: a first-run "aha", one-click sharing, an opt-in hosted permalink, and an opt-in public leaderboard — privacy-safe and anonymous-first.

Added

  • First-run "aha" (lean-ctx discover) — the first run surfaces a concrete, projected token saving for the current project (one-time marker in ~/.lean-ctx); discover --card exports a shareable "Ghost Tokens" SVG. Non-UTF-8 shell histories (zsh metafied format) are now read lossily so the projection never silently sees empty history.
  • One-click share (gain --copy / --open / --svg / --share) — copy a ready-to-post share line, or open the generated SVG/HTML card — cross-platform (pbcopy/clip/wl-copy/xclip/xsel, open/start/xdg-open).
  • Hosted Wrapped permalink (gain --publish / --unpublish) — anonymously publish a whitelisted, privacy-safe slice of the recap and get a shareable leanctx.com/w/<id> URL (copied to clipboard). Whitelist-only, one-time edit token stored locally for later removal, optional account claim. Server-rendered page carries per-card Open Graph / Twitter meta; og:image is a resvg-rasterized 1200×630 PNG.
  • Opt-in public leaderboard (gain --publish --leaderboard) — off by default; when set, the card is listed on leanctx.com/metrics (top 50 by realized tokens saved). Only the user-chosen display name is person-facing; everything else is an aggregate.
  • Per-day version in lean-ctx gain (#307) — each row in "Recent Days" now shows the lean-ctx version active that day, so compression changes can be attributed to a specific release. "Past 30 days" USD savings line added.

Fixed

  • 2>&1 misread as a command (#334) — the shell-allowlist parser split & as a background separator even inside a redirect (2>&1, >&, &>). A & adjacent to > is now correctly treated as part of the redirect operator, not a command separator.
  • Auto-update ignored config.toml (#335) — scheduled runs now obey config: auto_update = false skips the update and removes the orphaned scheduler (self-heal), and notify_only = true downgrades to a check without installing.
  • ctx_search and index build could hang on special files (#336) — a regular-file guard now skips non-regular paths (FIFOs, sockets, devices) before any blocking read. ctx_search additionally enforces a wall-clock deadline (LEAN_CTX_SEARCH_DEADLINE_MS, default 10s) and returns partial results instead of hanging.
  • No compression in the Codex Desktop / Cloud app (#337) — lean-ctx's transparent compression for Codex is hook-driven, but the Codex Desktop and Cloud app run in app-server mode where lifecycle hooks do not fire, so identical commands compressed in the Codex CLI but not in the app. The Codex instructions (~/.codex/AGENTS.md + LEAN-CTX.md) now state this explicitly and direct the agent to route work through the MCP tools (ctx_shell/ctx_read/ctx_search) or lean-ctx -c in the app, and lean-ctx doctor adds a Codex note. Hooks remain the automatic path in the Codex CLI once trusted via /hooks.
  • macOS bash login shells missed the hook and PATH — bash login shells (Terminal.app, IDE terminals, bash -l) read ~/.bash_profile/~/.profile, never ~/.bashrc — yet the hook and the installer's PATH export land in ~/.bashrc. lean-ctx setup now ensures the login profile sources ~/.bashrc (idempotent), so both take effect in login shells. zsh is unaffected.
  • Event feed flooded with false "denied" policy violations — auto-preload candidates from the project graph are repo-relative; the path jail resolved them against the daemon's CWD instead of the project root, so every candidate failed with "no existing ancestor" and was logged as a policy violation. Relative candidates now resolve against the jail root, and a genuinely missing file is no longer mislabeled as a denial.

3.7.0 (2026-06-01)

Shadow Mode + Meaningful Instructions — Rules injected into agents are now actionable (concrete tool names, examples, workflow), and a new shadow_mode transparently intercepts native Read/Grep/Shell calls.

Added

  • Shadow Mode (lean-ctx config set shadow_mode true) — Transparently intercepts native Read/Grep/Shell via hooks, strengthens MCP instructions to MUST-level, activates immediate bypass hints on first native tool use, logs all intercepts to ~/.lean-ctx/shadow.log. Visible in lean-ctx doctor and lean-ctx status.
  • 6-step workflow in all injected rules — Orient → Locate → Read → Edit → Verify → Record. Agents can follow blindly without memorizing tool names.
  • Tool Mapping table in rules — Every injected rule file now includes a MANDATORY table with exact tool names, parameters, and runnable examples.
  • Proactive section in RULES_DEDICATED — ctx_overview at session start, ctx_compress at phase boundaries, ctx_knowledge(action="wakeup") for prior findings.
  • Compression Bypass ladder — lines:N-M → full → raw=true documented escape hatch when compression hides detail.
  • Risk Gate guidance — Before editing exported symbols, auth, DB schemas, or 3+ files: run ctx_impact + ctx_callgraph.
  • Registry-driven hook refresh + doctor staleness check — lean-ctx doctor detects stale hooks and IDE path misconfiguration.
  • Reference appendices generated from code — docs-gen renders MCP tool reference, CLI reference, and journey golden outputs directly from source with CI drift-gate.
  • Complete user-journey reference (14 journeys) — Install-to-first-save through performance tuning, with IDE quickstarts.
  • Semantic-index observability (#249) — lean-ctx index status and lean-ctx doctor surface BM25 state, build duration, and failure notes.

Changed

  • Rules version v10 → v11 — All templates rewritten with actionable structure. Existing installations auto-upgrade on next lean-ctx setup or lean-ctx update.
  • MCP instructions include workflow hint — "Orient(ctx_overview) → Locate(ctx_search) → Read(ctx_read) → Edit → Verify → Record".
  • bypass_hint.rs respects shadow_mode — When active, hints trigger on first native use (not after 5 calls) with stronger "intercepted" wording.
  • Hook redirect messaging — In shadow_mode, redirected outputs include a header explaining the interception.

Fixed

  • Config.toml overwritten on update (#330) — All config writes now use toml_edit-based format-preserving merge with atomic backup. User comments and unknown keys survive.
  • WSL cache hit rate near 0% (#329) — mtime=None on DrvFS no longer causes spurious invalidation; path normalization uses canonicalize for consistent cache keys.
  • Semantic index stuck "warming up" (#249) — Disk persist ceiling decoupled from RAM profile; observable state reporting; honest ctx_compose deferred messages.
  • Test-runner output compressed/truncated — Test-runner commands are now kept verbatim; test-outcome markers survive truncation.
  • Knowledge store split on Windows (#325) — Forward-slash/casing-normalized project hash converges CLI and MCP on a single store.
  • Parallel knowledge writes clobbered each other (#326) — Read-modify-write serialized with in-process + cross-process file locks; atomic saves.
  • Windows \\?\ prefix from canonicalize — normalize_tool_path now strips extended-length prefix.
  • IDE hook integrations check — Doctor correctly parses hook binary path from minified JSON.
  • Docs-drift gate line-ending agnostic — Windows CI no longer fails due to CRLF vs LF.
  • Benchmark system info detection on Windows — RAM + CPU detection now works on all platforms.

Security

  • Shell-command injection in Node SDK (CodeQL js/shell-command-constructed-from-input) — Switched to execFileSync, no shell interpretation.
  • XSS in VS Code sidebar webview (CodeQL js/xss, 3× high) — All dynamic values escaped.
  • Missing origin check on webview message handler (CodeQL js/missing-origin-check) — Rejects untrusted origins.

3.6.26 (2026-05-30)

EPIC 6 — Perfect-First: cross-project session correctness, bounded disk footprint, and a useful cold-start overview.

Fixed

  • Project root never resolves to HOME / / / agent sandbox dirs (#2361) — Root detection now rejects broad/unsafe directories even when a client reports one, eliminating cross-project context bleed (the "HOME mega-session").
  • Cross-project session leakage (#2362) — Session loads are strictly project-scoped: load_latest() no longer falls back to a global pointer and returns nothing for an unsafe working directory, so a new session in a project only ever recalls that project's knowledge.
  • Noise auto-findings suppressed (#2363) — Findings from VCS/dependency/build/cache dirs, virtualenvs, vendored code, home dotfiles (~/.ssh/config …) and binary/log files are dropped, and unidentified ? search patterns no longer create junk findings. Knowledge recall now boosts exact key matches.
  • Useful cold-start ctx_overview (#2365) — While the knowledge graph indexes, the overview now returns detected project markers, a depth-2 tree and known facts instead of only "try again in a minute".

Added

  • lean-ctx sessions doctor [--apply] (#2362) — Detects sessions rooted at a broad/unsafe path and non-destructively quarantines them.
  • Archive FTS disk-cap enforcement (#2364) — The archive index now enforces an on-disk size cap (default 500 MB, override via LEAN_CTX_ARCHIVE_DB_MAX_MB) by pruning the oldest entries, a daemon-safe startup pass prunes accumulated quarantined BM25 indexes, and lean-ctx doctor reports the archive footprint.

Changed

  • Self-healing rules refresh (#2365) — When an outdated rules file is detected, LeanCTX auto-refreshes it on disk instead of only nudging you to run lean-ctx setup.

3.6.25 (2026-05-30)

Jira Cloud OAuth 2.0, context-pressure triage in the cockpit, offline-first dashboard with ⌘K palette, and a concurrent-edit fix.

Added

  • Jira Cloud OAuth 2.0 (3LO) (#318) — Authenticate built-in and custom Jira data sources via the standard 3-legged OAuth flow instead of Basic auth + API token. lean-ctx provider auth jira runs the interactive flow (loopback redirect, browser consent, cloudId discovery), persists tokens to ~/.lean-ctx/credentials/jira-oauth.json (0600) and auto-refreshes with refresh-token rotation. provider list / provider logout round out the surface. Secret-free: you register your own Atlassian OAuth app and supply the client id/secret via env. Basic auth keeps working; OAuth is selected automatically when a credential exists or JIRA_AUTH=oauth is set.
  • Context-pressure triage in the Context Cockpit (#249) — The Context Manager moves from observation to triage. The Files in Context table gains sortable Used (re-read count), Last (recency) and Evict columns — the Evict score combines high token cost + long idle + rarely re-read, so the best eviction candidate is one click away. A triage banner maps the live pressure band to a concrete next action (Healthy / Elevated → prefer map+signatures / High → compress or evict / Critical → evict or handoff pack).
  • Offline-first Context Cockpit — Chart.js, D3 and the UI fonts are now self-hosted (no external CDN), so the dashboard renders identically offline and on large sessions. A dashboard-wide ⌘K / Ctrl+K command palette adds fuzzy search across every view, quick actions (refresh, theme toggle) and full keyboard navigation.

Fixed

  • ctx_edit concurrent-edit timeout under multi-agent load (#320) — The global cache write-lock was held across the entire disk I/O of an edit, so a second agent editing a different file could time out. Edits now serialize per file via a shared lock registry, do disk I/O with no global lock, and take the global cache lock only briefly. Concurrent edits to different files now run in parallel; same-file edits stay correctly serialized.
  • Cross-platform CI hardening — Fixed a path-separator bug in the eval harness (recall/MRR collapsed to 0 on Windows), made the ctx_tree savings test deterministic, and de-flaked a timing-sensitive lock test on slow runners.

3.6.24 (2026-05-30)

Knowledge Intelligence, RAM guardian fix, ctx_compose, Jira Cloud migration, friendlier defaults.

Added

  • Knowledge Intelligence — Revision Tracking — KnowledgeFact gains a revision_count field. Confirmations increment it, supersedes carry it forward. Output distinguishes "Remembered (revision 1)" vs "Confirmed (revision N)" vs "Updated → revision N". Recall shows rev N for multi-revision facts.
  • Knowledge Intelligence — Cross-Key Conflict Surfacing — find_cross_key_similar() detects semantically similar facts across different keys using Jaccard similarity. When remember stores a fact, similar facts are surfaced with similarity percentages. New judge action lets agents resolve pairs as supersedes/compatible/unrelated.
  • Knowledge Intelligence — Activity-weighted Nudges — Replaces the fixed 30-call counter with weighted activity scoring. Edits +4, shell test/build +3, new file read +1, knowledge calls reset. Contextual nudge text based on dominant tool type.
  • ctx_compose — multi-source context composer — New MCP tool that combines BM25 ranking, semantic search, and associative retrieval into a single rich response. Uses submodular maximization for optimal symbol selection within token budget.
  • Hebbian co-access graph — Persistent, decaying file co-access associations inspired by neurobiology (LTP, pruning). Contributes to associative retrieval across sessions.
  • Spreading activation ranker — ACT-R-style associative ranker that spreads relevance across structural + learned co-access graphs.
  • Bloom filter tier for large monorepos — Memory-efficient search index tier for repositories with 50k+ files. Zero false negatives.
  • bunx in default shell allowlist (#310).

Changed

  • Default compression_level → "lite" — New installs now default to "lite" (abbreviations only) instead of "off". Existing configs are not changed.
  • Friendlier --help and quickstart output — Bare lean-ctx invocation now shows a concise quickstart guide. --help is reorganized by usage frequency.
  • Reverted thinking-mode guard (#313) — The defensive check in PreToolUse hooks was removed — the upstream bug it worked around has been fixed.
  • Codebase quality — Split 5 large files (2000+ lines each) into focused modules. Added 38 CLI characterization tests.

Fixed

  • RAM Guardian measures daemon RSS (#317) — lean-ctx doctor was showing the CLI's ~14 MB instead of the daemon's actual memory. Added get_rss_bytes_for_pid(pid) for Linux and macOS. Doctor now reports real daemon RSS.
  • Orphan MCP processes no longer accumulate RAM (#317) — Added parent-process watchdog (exits when IDE closes) and startup orphan cleanup. Prevents MCP server processes from surviving after IDE restarts.
  • lean-ctx restart no longer kills active MCP servers (#317) — find_killable_pids() excludes MCP server processes from force-kill during restart.
  • Jira Cloud 410 Gone error (#315) — Migrated from deprecated GET /rest/api/3/search to POST /rest/api/3/search/jql with nextPageToken pagination.
  • Provider discovery ignores project root (#316) — handle_discover() now passes project_root for project-local provider config discovery.
  • JSONC parser tolerates trailing commas (#311, #312) — Prevents parse failures in MCP config files with trailing commas.
  • Token-cap truncation performance — Rewrote from O(n) to O(log n) binary search.
  • Silent save() failures now logged — Failures produce tracing::warn! instead of being swallowed.

3.6.23 (2026-05-28)

Shell hook only installed for available shells, generic config set for all keys, gain dashboard improvements.

Fixed

  • lean-ctx update creates .zshenv without zsh (#309) — Shell hooks were written for both zsh and bash regardless of whether the shell was installed. Now checks for the shell binary (/bin/zsh, /usr/bin/zsh, etc.) before installing. Bash-only systems no longer get a spurious .zshenv.
  • lean-ctx config set rejects valid keys (#308) — The command only supported ~12 hardcoded keys while the schema defines 80+. A new generic schema-based setter validates any key, parses by type (bool, integer, float, string, enum, string[]), and round-trips through TOML with full validation. Keys like proxy_enabled, profile, compression_level now work.

Added

  • lean-ctx gain: 30-day USD savings (#307) — The dashboard now shows a "past 30 days" line with estimated dollar savings, in addition to the all-time total — useful for choosing a monthly LLM subscription tier.
  • lean-ctx gain: version in Recent Days header (#307) — The "Recent Days" section now displays the current lean-ctx version for easier troubleshooting from screenshots.
  • Enum validation in config set — Setting an enum key with an invalid value now lists the allowed values instead of a generic error.

3.6.22 (2026-05-28)

Security Hardening V2 (8 phases), hook reliability, adaptive exec limits, index rebuild improvements.

Security

  • Security Hardening V2 (8 phases) — Comprehensive security audit and hardening: shell substitution blocking (eval, exec, source), role system hardening, PathJail bypass removal, secret detection unification, dangerous flag detection (--checkpoint-action, GIT_SSH=), HTTP/audit hardening, and Unicode normalization (U+2028/U+2029 line separators).

Fixed

  • preToolUse hook DENY loop (#306) — AI agents entered infinite retry loops when hooks returned DENY. Eliminated all DENY paths — hooks now always return valid ALLOW JSON, even for disabled mode or invalid payloads.
  • Graph index disappears after upgrade — CLI index build-full and Dashboard used different project root hashes. Unified detect_project_root() to always promote to git root.
  • index build-full incomplete rebuild — Now also clears call_graph.json.zst, graph.db, and graph.meta.json, then rebuilds the SQLite property graph. Timeout increased to 5 minutes.
  • Knowledge overflow from finding-auto duplicates — Auto-consolidated findings without a file reference received identical keys, creating hundreds of duplicate facts and contradict event spam. Keys are now generated from the finding summary.
  • cargo build output truncated — Heavy build commands hit the 8MB/120s output limit. Added adaptive exec limits: build tools get 32MB/10min.

Added

  • ctx_tree / lean-ctx ls gitignore toggle — New respect_gitignore parameter (MCP) / --no-gitignore flag (CLI) to show files regardless of .gitignore rules.
  • LEAN_CTX_SHELL_ALLOWLIST_OVERRIDE env var — Completely replaces the config-based allowlist (unlike LEAN_CTX_SHELL_ALLOWLIST which merges).
  • Adaptive exec limits — 37 heavy-command prefixes (cargo build, npm install, docker build, etc.) automatically get 32MB/10min instead of 8MB/2min.

3.6.21 (2026-05-27)

RAM Guardian now performs real cache eviction under memory pressure.

Fixed

  • RAM Guardian performs real cache eviction (#300) — Previously, the memory_guard eviction callback only called jemalloc_purge(), which returns already-freed pages to the OS but never evicts actual data. Now a new EvictionOrchestrator bridges the RSS-based memory guardian to the HomeostasisController, enabling 5-stage graduated eviction: trim compressed outputs → evict probationary entries → unload BM25 index → evict protected entries → emergency full cache clear.
  • jemalloc_purge() error handling — Previously swallowed errors silently. Now logs failures via tracing::debug.
  • is_under_pressure() optimized — Was calling MemorySnapshot::capture() (with Config::load() + syscalls) on every invocation in BM25/graph index builders. Now reads a cached AtomicU8 flag — O(1), zero allocations.

Added

  • EvictionOrchestrator — New module connecting memory_guard to HomeostasisController with non-blocking cache access.
  • SessionCache eviction methods — trim_compressed_outputs(), evict_probationary(), evict_to_budget(), approximate_bytes(), trim_shared_blocks().
  • BM25 cache management — unload() drops cached index, memory_usage() reports heap size.
  • Doctor pressure hints — Shows active pressure level and recommends config changes when under pressure.

3.6.20 (2026-05-27)

Critical hotfix: fixes OnceLock reentrancy deadlock that caused all commands to hang on v3.6.19.

Fixed

  • OnceLock reentrancy deadlock (#301) — All shell hook commands (ls, cat, etc.), lean-ctx setup, and lean-ctx update hung indefinitely on v3.6.19. Root cause: active_profile_name() called Config::load(), creating a circular dependency through OnceLock::get_or_init(). Fixed by reading config.toml directly without Config::load(), and preventing normalize_loaded_session() from calling active_profile() during config initialization.

3.6.19 (2026-05-26)

Added

  • Built-in passthrough profile — No output modification: always full content, zero compression. Use via LEAN_CTX_PROFILE=passthrough or lean-ctx config set profile passthrough. Includes default_mode=full, crp_mode=off, degradation.enforce=false.
  • Persistent profile selection via config.toml — New profile field provides a fallback when LEAN_CTX_PROFILE env var is not set. Resolution order: env var → config.toml → "coder" default.
  • Profile config schema entry — lean-ctx config show now displays the profile key.

Fixed

  • LEAN_CTX_FULL_TOOLS=0 incorrectly treated as ON — Setting the variable to 0 or false is now correctly interpreted as disabled.
  • mode=full returning stubs/deltas in passthrough mode — Cache stubs and auto-deltas are now skipped when no_degrade=true or when the active profile has default_mode=full + crp_mode=off.
  • MCP schema claimed default mode was full — The ctx_read tool description now correctly states default: auto, matching actual behavior.
  • Silent fallback to coder profile — When a requested profile doesn't exist, LeanCTX now logs a warning with creation instructions instead of silently falling back.

3.6.18 (2026-05-26)

Structured read modes for non-code files, unified AutoModeResolver, GraphProvider facade, token efficiency optimizations, UTF-8 locale fix.

Added

  • Structured read modes for non-code files — ctx_read mode map now produces token-efficient semantic summaries for Markdown (heading outline), JSON (key structure with types), YAML (key hierarchy), TOML (section headers), and lock files (workspace dependency summaries). Up to 95% token savings on large config/doc files (#299).
  • Unified AutoModeResolver — Centralized auto-mode selection logic in auto_mode_resolver.rs. Single resolve() entry point with deterministic mode decisions and full trace logging. Config files like Cargo.toml get full mode while structured formats (JSON, YAML, TOML, lock) are routed to map (#297).
  • GraphProvider unified facade — GraphProvider wraps both PropertyGraph (SQLite, symbol-level) and ProjectIndex (JSON, file-level) behind a single API. New methods: file_catalog(), file_info(), files_in_dir(), index_dir(). All consumer modules migrated (#298).
  • Template instructions SSoT — rules_canonical.rs provides canonical_hybrid_instructions() as single source of truth for all template instruction generation. CLAUDE.md, lean-ctx.mdc, and daemon LITM injection all derive from the same canonical table (#296).
  • UTF-8 locale enforcement — apply_utf8_locale() sets LC_CTYPE=C.UTF-8 fallback on all 5 shell spawn paths. Fixes Cyrillic/CJK/emoji M-notation mangling on Linux.

Fixed

  • mode=full silently downgraded (#295) — Explicit mode=full now bypasses all pressure degradation, bounce tracking, and overlay-based downgrades.
  • Shell allowlist blocking Cursor commands (#294) — $() substitution relaxed, argument-position backticks allowed, gh data commands now compressible. Prevents agent retry loops.
  • Bypass hint false positives (#292) — Reduced false warnings when agents legitimately use native Read/Grep.
  • ctx_prefetch crash without graph — Graceful fallback to direct prefetching of changed_files when no graph is available.
  • PropertyGraph race condition on Windows — open_best_effort now requires file_catalog_count > 0 before considering a PropertyGraph as populated.

Changed

  • Token efficiency optimizations — BM25 index cache uses Arc instead of clone, stats adjusted after post-processing, compression floor lowered (50→30 tokens), INSTRUCTION_CAP switched to token-based (1200), graph index shares content cache with edge builder, SessionCache eviction upgraded to RRF scoring.
  • Dead code removal — Removed unused migrate_index_to_property_graph and remove_file_catalog after graph consolidation.

3.6.17 (2026-05-25)

Antigravity CLI 2.0, CLI graph queries, daemon diagnostics, uninstall hardening, Windows path fixes.

Added

  • CLI graph query commands — lean-ctx graph related <file>, graph impact <file>, graph symbol <spec>, graph context <query>, and graph status expose project graph analysis directly from the CLI, without requiring MCP (#281).
  • Antigravity CLI 2.0 as separate init target — lean-ctx init --agent antigravity-cli writes MCP config to ~/.gemini/antigravity-cli/mcp_config.json, distinct from the IDE target. lean-ctx init --agent gemini auto-configures both Antigravity IDE and CLI paths (#284).
  • Doctor: daemon diagnostics — Shows systemctl --user is-active state on Linux, warns when loginctl enable-linger is not set, and displays crash-loop log restart count (#288, #289).

Fixed

  • Uninstall completeness (#274) — .bak files, ~/.config/lean-ctx, project-local .lean-ctx/, and Claude CLI MCP entries now cleaned up. --keep-config flag preserves MCP configs for reinstall.
  • Linux daemon autostart (#288, #289) — Actionable error messages for systemctl --user enable failures. is_installed() checks systemctl is-enabled. Linger hint displayed.
  • Windows paths with spaces — Shell hook rewrites use shell_tokenize() instead of split_whitespace(). shell_quote() properly handles special characters.
  • Windows drive-letter grep parsing — C: drive prefix no longer misinterpreted as path separator.
  • Panic loop-undo (#277) — catch_unwind handler calls record_error_outcome() on the loop detector, so panicking tools are throttled instead of retried infinitely.
  • Index scoping — Project index restricted to project root via is_safe_scan_root(). index status shows real values.
  • Workflow agent-scoped — Workflow state is per-agent (workflow-{agent_id}.json) instead of a global singleton. Stale workflows auto-cleaned after TTL.
  • JSONC UTF-8 safety — floor_char_boundary prevents panics on multi-byte characters in comments.
  • ls -lah size passthrough — Human-readable sizes (4.0K, 1.2M) preserved instead of being converted to 0B.

Changed

  • Antigravity IDE renamed — Existing Antigravity target now labeled "Antigravity IDE" in display names and doctor output, distinct from "Antigravity CLI".

3.6.16 (2026-05-22)

OpenClaw agent support, .ctxpkg v2 graph-native architecture, ctx_session em-dash panic fix (#272).

Added

  • OpenClaw agent support — lean-ctx init --agent openclaw writes MCP config to ~/.openclaw/openclaw.json under mcp.servers.lean-ctx, installs rules and SKILL.md. lean-ctx doctor detects OpenClaw. lean-ctx setup auto-configures when ~/.openclaw/ exists.
  • .ctxpkg v2 graph-native architecture — New ContextGraph data model with ContextNode/ContextEdge, activation weights, and temporal metadata. Graph-merge composition with conflict detection and contradiction resolution. Ed25519 package signing. Manifest schema v2 with scoped names (@scope/name) and conformance levels (Basic, Graph, Cognitive).
  • LeanCTX Custom GPT docs — Knowledge base and system prompt prepared for ChatGPT Custom GPT (gitignored).

Fixed

  • ctx_session finding panic on em-dash (#272) — parse_finding_value crashed on multi-byte separators like " — " (U+2014, 5 bytes) because of hardcoded 3-byte assumption. Now uses dynamic separator length. 6 regression tests added.
  • Panic handler isError: false — MCP server catch_unwind returned panics as successful tool results. Now correctly returns CallToolResult::error with isError: true.

3.6.15 (2026-05-22)

MCP crash vector elimination, dashboard cleanup, configurable proxy timeout.

Fixed

  • MCP crash: "Cannot read properties of undefined" — 4 crash vectors fixed (#271): 5 Mutex::lock().unwrap() calls replaced with graceful fallbacks, memory_guard hard exit replaced with 3-attempt eviction, nested block_in_place eliminated, CSPRNG expect() replaced with time-based fallback.
  • parse().unwrap() for SocketAddr in dashboard routes replaced with direct construction.
  • tempfile().expect() in ctx_execute replaced with graceful error return.

Changed

  • Dashboard modular route architecture — Monolithic context.rs and graph.rs split into focused sub-modules.
  • Dashboard API consolidation — 3 new aggregated endpoints reduce parallel fetches from 18 to 11.
  • Shared frontend utilities — Extracted gauges, formatters, API layer with TTL cache.
  • Removed legacy dashboard.html (3057 lines) and CockpitContextLayer.

Added

  • Context Commander — New dashboard component with context pressure visualization and risk analysis.
  • Configurable proxy timeout — LEAN_CTX_PROXY_TIMEOUT_MS env var / proxy_timeout_ms in config.toml (default: 200ms). (#270)
  • Dynamic tool categories — LCTX_DEFAULT_CATEGORIES env var to control active categories.
  • Global degradation disable — LCTX_NO_DEGRADE=1 env var to disable all read mode degradation.

3.6.14 (2026-05-22)

UTF-8 safety hardening, Augment agent support, context package (.ctxpkg) overhaul, degradation warnings, multi_read output cap.

Added

  • Augment AI agent support — lean-ctx init --agent augment wires up Auggie CLI and VS Code extension surfaces. Rules injected at ~/.augment/rules/lean-ctx.md. Doctor reports drift and "disabled": true detection. Cross-platform. (Contributed by @parker-brown-family, #264, #267)
  • Context packages renamed to .ctxpkg — Package format, CLI, transport, and docs all use .ctxpkg extension. Legacy .lctxpkg files remain importable.
  • ctx_multi_read output cap — Server-side 512KB cap (configurable via LCTX_MAX_MULTI_READ_BYTES) prevents MCP client truncation. Skipped files reported with warning. (#263)
  • Degradation policy warning — mode=full downgrade to mode=map under context pressure now emits an explicit ⚠ Context pressure warning with bypass hint. (#262)
  • 28 regression tests — UTF-8 boundary tests (Cyrillic, CJK, emoji), degradation verdict tests, multi_read cap tests.

Fixed

  • UTF-8 character boundary panics — 13 string truncation sites hardened with floor_char_boundary()/ceil_char_boundary(). Prevents crashes on Cyrillic, CJK, emoji content. (Report by @cburgess, #265)
  • Context package hardening — Fixed receive --apply, Graph edge import, Session/Patterns/Insights import, auto-load caching, HMAC signing, CLI flag parsing, memory leaks.
  • lean-ctx update proxy race condition — Proxy now fully healthy before ANTHROPIC_BASE_URL is written. (#234)

Changed

  • Removed dead PackageLayer::Artifacts enum variant
  • Expanded manifest validation (hex hash format, byte_size, duplicate layers)
  • Import hardened with extension + size limit checks

3.6.13 (2026-05-21)

Plan mode for VS Code/Claude Code, production-wired provider pipeline, GitLab provider, shell hook fixes, 50+ new integration tests.

Added

  • Plan mode support — lean-ctx tools now work in IDE plan/read-only modes. VS Code planAgent.additionalTools and Claude Code permissions.allow are auto-configured via lean-ctx setup. 12 curated read-only tools available in plan mode.
  • MCP readOnlyHint annotations — All read-only tools declare readOnlyHint: true, enabling IDE plan agents to use them without user approval.
  • Dynamic tool filtering — Plan-mode clients see only read-only tools; full-mode clients see all 63 tools.
  • GitLab provider — Built-in data source for GitLab issues, merge requests, and pipelines. Activates with GITLAB_TOKEN.
  • Provider consolidation pipeline (production-wired) — Provider data now flows into BM25, Graph, Knowledge, and Session Cache via background threads. External data is fully searchable, generates cross-source hints in ctx_read, and contributes knowledge facts.
  • MCP Bridge stdio transport — MCP bridges now support stdio-based servers via command + args config, in addition to HTTP.
  • External result attribution in ctx_semantic_search — Results from providers show type labels: [Issue], [PR], [Ticket], [Schema], [Wiki].
  • lean-ctx doctor enhancements — New MCP bridge diagnostics and plan mode status checks.
  • 50+ new integration tests — Wiring proofs, E2E pipeline, plan mode, power user worksession, lock contention hardening scenarios.

Fixed

  • PowerShell @args splatting — _lc now resolves native commands via Get-Command before invocation.
  • Fish/Bash/Zsh lean-ctx-off — Now exports LEAN_CTX_ENABLED=0 instead of unsetting the variable.
  • Provider init ignores project root — ctx_provider and ctx_preload now pass the real project root to provider discovery.
  • Windows CI: dead code warning — Removed unused is_running_in_powershell() function.

Changed

  • providers.auto_index default is now true — New installations automatically index provider data into all stores.

Removed

  • Dead code cleanup: providers_mcp_bridges(), hints_from_index(), is_running_in_powershell().

3.6.12 (2026-05-21)

Context Engine, config-based data source providers, output sanitizer, stale proxy fix, 3 new docs pages.

Added

  • Context Engine — Multi-source intelligence layer connecting code, issues, and external APIs. BM25 indexing, cross-source edge detection, saliency ranking, and active inference prefetching. Read more.
  • Config-based data source providers — Connect any REST API by dropping a .toml or .json file into ~/.config/lean-ctx/providers/. Supports 6 auth methods, dot-notation response extraction. Read more.
  • Built-in GitHub, Jira, PostgreSQL providers — Activate with environment variables. Query issues, tickets, and database schemas through ctx_provider.
  • ctx_call meta-tool — Invoke any of 62 registered tools by name through a single dispatch interface.
  • Cross-source hints in ctx_read — The Context Engine appends related context from providers when reading files (e.g., relevant GitHub issues).
  • Provider Bandit (Thompson sampling) — Automatically deprioritizes noisy providers and promotes relevant ones.
  • Active inference in ctx_preload — Predicts what context you'll need next based on recent tool call patterns.
  • Output sanitizer — Last-pass filter that detects and removes degenerate CJK runs, symbol floods, and garbled artifacts from tool output.
  • lean-ctx proxy cleanup — Removes stale ANTHROPIC_BASE_URL entries from Claude Code/Codex settings when the proxy is disabled.
  • lean-ctx doctor stale proxy check — Detects when ANTHROPIC_BASE_URL points to local proxy but proxy is not enabled.
  • Self-healing I/O protection — safe_canonicalize_bounded() with timeouts on all platforms; 12 tools use bounded_lock helpers with adaptive timeouts.
  • New docs pages — Context Control & Overlays, Budgets & SLOs, Observatory.

Fixed

  • Garbled Chinese characters in Cursor Thought panel (#257) — Unicode-heavy compression symbols confused Cursor's Thought summarizer. Three-layer fix: output sanitizer, Cursor-aware ASCII-safe symbols in prompts, ASCII-only TDD shortcuts.
  • Stale ANTHROPIC_BASE_URL after proxy disable (#256) — Users who disabled the proxy were left with stale URL causing 401 errors. doctor --fix and proxy cleanup auto-detect and remove stale URLs.
  • _lc: command not found in non-interactive subshells (#255) — Passthrough stubs defined in .zshenv/.bashenv before the exec guard.
  • Windows update hangs with locked binary (#254) — Pre-update process stop, blocking PID visibility, 60s timeout with progress indicators.
  • Random freezes on WSL2/NFS/FUSE — Auto-detects slow environments; 3+ freezes in 60s triggers degraded mode.
  • Proxy auto-starts without explicit enable — Now checks proxy_enabled == Some(true) before spawning.
  • Multi-user port conflict — Deterministic per-user port via UID-based assignment.

Changed

  • MCP tool count 61 → 62 — Added ctx_provider.
  • Compression symbols → ASCII-safe — TDD shortcuts use -> instead of →, ok instead of ✓ for downstream model compatibility.
  • Cursor-specific rules injection — .cursorrules and .cursor/rules/ receive ASCII-safe compression prompts.

Security

  • MCP config credential protection — .vscode/mcp.json and .github/mcp.json added to .gitignore.
  • GitHub provider hardened — Parses GITHUB_REPOSITORY=owner/repo correctly.

3.6.11 (2026-05-20)

Critical Linux restart loop fix, Windows hang prevention, manifest SSOT, performance hardening.

Fixed

  • Linux proxy restart loop (11258+ restarts) — When the binary is replaced during runtime, Linux marks /proc/self/exe with (deleted) suffix. The systemd unit generator wrote this corrupted path into ExecStart, causing (deleted) to appear as a CLI argument on every restart. Now uses resolve_portable_binary() which strips the suffix. CLI dispatch also defensively removes (deleted) from args for existing units.
  • Windows ctx_read hangs — Session lock acquire and path canonicalization now have bounded timeouts (5s for RwLock, 2s for canonicalize()) preventing indefinite hangs on Windows reparse points and network paths.
  • Manifest generator uses stale tool_defs — gen_mcp_manifest now reads from ToolRegistry (61 tools) instead of static granular_tool_defs() (56 tools).

Changed

  • Context budget auto-escalation — pressure_downgrade() applies more aggressive mode downgrades based on ContextPressure.
  • Cache-stable LITM output — Dynamic session statistics moved from output prefix to suffix for LLM prefix-caching compatibility.
  • ToolRegistry as SSOT for list_tools — Eliminates schema drift between exposed schemas and handler implementations.
  • OnceLock for project root — find_project_root() cached via std::sync::OnceLock, eliminating repeated git rev-parse calls.
  • Compaction sync tail-seek — Reads only the last 4KB of context_radar.jsonl instead of the entire file.

Removed

  • Dead code cleanup: removed unused functions, #[allow(dead_code)] attributes replaced with _ prefixes across 8 files.

3.6.10 (2026-05-20)

Critical performance fix for knowledge recall, start_line no-op, git write-command safety.

Fixed

  • Knowledge recall blocks all agents for 58s — Embedding engine loading no longer blocks recall. Non-blocking try_shared_engine() used for auto/hybrid mode; retrieval signal persistence moved to background thread.
  • start_line=1 forces unnecessary disk re-reads (#253) — Clients that always send start_line=1 no longer trigger mode override. Now correctly treated as a no-op.
  • Git write-commands incorrectly compressed — git commit, git push, git pull, git merge, git rebase, git cherry-pick, git tag, git reset are now classified as verbatim (zero compression).
  • PowerShell command wrapping — Single full-command strings no longer incorrectly wrapped in & '...' quotes on PowerShell.
  • Terse dictionary safety — Removed git subcommand abbreviations (commit→cmt, branch→br, etc.) from the GIT dictionary to prevent output corruption.

3.6.9 (2026-05-19)

Workflow staleness auto-clear, cache message fix, Context IR hot-path, plugin-ready traits, pytest compression.

Added

  • Context IR hot-path lineage — Every tool call now records source kind, tokens, duration, and content excerpt into the Context Intermediate Representation for full lineage tracking.
  • Plugin-ready traits — Extracted CompressionPattern trait and ContextProvider trait for future plugin extensibility.
  • Pytest verbose compression — Dedicated pattern for pytest -v output: consolidates per-test lines, strips fixtures/collection/metadata, preserves tracebacks and test identifiers.
  • Active Context Gate — Pressure-based auto-downgrade: when context utilization exceeds 75%, reads are automatically downgraded (full→map, map→signatures).

Fixed

  • Workflow persistence blocking reads after crash — Workflows inactive >30 minutes are now auto-expired. Read-only tools (ctx_read, ctx_multi_read, ctx_smart_read, ctx_search, ctx_tree) always pass through the workflow gate regardless of state.
  • Misleading cache-hit message — Changed "Already in your context window" to neutral [unchanged, use cached context] with hint about fresh=true for forced re-read.
  • Unable to clear context pressure (#244) — ctx_ledger(action=reset) now correctly clears all ledger state.
  • Flaky CI tests — Serialized environment-variable tests, fixed anomaly persistence debounce race, relaxed stress thresholds for shared runners.

3.6.8 (2026-05-18)

Post-RRF reranking pipeline, BM25 path enrichment, find_related search, workflow done-state fix.

Added

  • Post-RRF Reranking Pipeline — 5 scientifically-grounded signals: Query-Type Classifier, Definition Boost, File Coherence Boost, Noise Penalties, MMR Diversity.
  • BM25 Path-Enrichment — File stem and parent directory doubled into BM25 content for path-aware queries.
  • find_related action in ctx_semantic_search — Chunk-based similarity search given a file path + line.

Fixed

  • Workflow "done" state blocks all tools permanently — handle_complete now clears the workflow file. Gate auto-clears stale "done" workflows.
  • ctx_read lines:N-M mode hangs on large files — Line-range reads no longer trigger expensive hint computations.

3.6.7 (2026-05-18)

Model registry, PathJail container bypass, ctx_shell env forwarding, Copilot CLI support, benchmark honesty fixes.

Added

  • 3-Layer Model Registry — Data-driven model context window registry replaces hardcoded substring matching. Supports bundled defaults, auto-updated local registry, and user overrides via [model_context_windows] in config.toml. Covers 40+ models including GPT-5.5, GPT-4.1, Gemini, Claude.
  • ctx_shell env parameter — New optional object parameter lets agents explicitly pass environment variables to shell commands. Auto-forwards CODEX_*, CLAUDE_*, OPENCODE_*, HERMES_* from the MCP server process.
  • PathJail container bypass — Auto-disables in Docker/Podman containers. Manual opt-out via path_jail = false in config.toml or LEAN_CTX_NO_JAIL=1.
  • Copilot CLI support — Separate CopilotCli config type writes to ~/.copilot/mcp-config.json with correct format (mcpServers, "type": "local", "tools": ["*"]).

Fixed

  • Benchmark honesty — Structural modes (map, signatures) excluded from "best mode" for non-code files. Previous reports showed misleading 100% savings for JSON; corrected to accurate values.
  • Copilot CLI config path — Now writes to ~/.copilot/mcp-config.json instead of VS Code's Application Support path.
  • PathJail CWD fallback — Guarded fallback with unsafe-root protection and differentiated error messages.
  • Invalid JSON config handling — Text-based injection preserves invalid files instead of destructive overwrite.

Changed

  • VS Code / Copilot split — Two separate targets: "VS Code" and "Copilot CLI" with distinct config paths and formats.

3.6.6 (2026-05-17)

ABC-inspired agent hardening, bypass detection, strict enforcement mode, knowledge export, and git compression fix.

Added

  • Bypass Hints — Detects when agents use native Read/Grep instead of lean-ctx tools and emits a reminder. Configurable via bypass_hints config or LEAN_CTX_BYPASS_HINTS env (modes: gentle, firm, off).
  • Tool Description Enhancement — All core tool descriptions now explicitly state "replaces native X" to guide AI agents directly from the MCP schema.
  • Rules Deduplication — Removed redundant tool mapping tables from injected rules. Tool descriptions carry the mapping; rules focus on mode selection and anti-patterns.
  • lean-ctx harden — Activates strict enforcement mode (LEAN_CTX_HARDEN=1 in MCP configs). Optionally denies Bash in Claude Code's permissions.deny.
  • lean-ctx export-rules — Exports high-confidence knowledge facts as editor-native rules (MDC for Cursor, AGENTS.md, CLAUDE.md).

Fixed

  • git status --porcelain truncation — Shell compression no longer truncates git status output when it doesn't match section parsing. Developers always see full status.
  • init --agent rules injection — Global rules and skill file now correctly injected. Fixed data dir split causing empty gain field. (#238, #239)

3.6.5 (2026-05-17)

Bug fixes for CLAUDE_CONFIG_DIR, OpenCode rules location, Linux CI warnings, and MCP resource notifications.

Fixed

  • CLAUDE_CONFIG_DIR support — MCP instructions and rules file paths now respect CLAUDE_CONFIG_DIR env var instead of hardcoding ~/.claude. (#235)
  • OpenCode rules location — Rules written to ~/.config/opencode/AGENTS.md instead of path OpenCode never loads. (#237)
  • Linux CI warnings — Fixed unreachable_pub, borrow_as_ptr, unnecessary_wraps, and unused_variables for platform-gated items.
  • MCP Resource Notifications — notifications/resources/updated sent to subscribed clients after ledger changes.
  • ctx_load_tools — New tool for explicit category management with notifications/tools/list_changed support.

3.6.4 (2026-05-17)

Hebbian knowledge enhancement, auto-update UX, agent runtime hardening, multi-agent production features, governance & compliance, and full OWASP Agentic Top 10 alignment.

Agent Runtime Hardening

  • Capability-based tool access control — Fine-grained permissions per agent with declarative capability ACLs. Agents can only invoke tools they are explicitly granted access to.
  • OS-level sandboxing — macOS Seatbelt and Linux Landlock integration at sandbox_level=1. Agent file system and network access is restricted at the kernel level.
  • SHA-256 chained audit trail — Append-only JSONL audit log with hash-chained entries. Every tool call, policy decision, and agent action is cryptographically linked.
  • Secret detection — 8+ regex patterns detect secrets (API keys, tokens, passwords) in tool inputs/outputs with optional redaction.
  • Shell allowlist mode — ctx_shell can be restricted to a configurable set of allowed commands, blocking all others.
  • Auto-reroot protection — allow_auto_reroot=false by default prevents agents from escaping their project root.

Multi-Agent Production

  • Per-agent context ledger isolation — Each agent gets its own isolated context ledger, preventing cross-agent data leakage in multi-agent setups.
  • Agent token budgets — Configurable per-agent token limits with enforcement. Budget overruns are logged and can trigger policy actions.
  • Remote Agent Bus — HTTP-based agent registration with heartbeat monitoring and SSE event streaming for distributed multi-agent orchestration.
  • Signed handoff bundles — Agent-to-agent handoffs are signed with Ed25519, ensuring bundle integrity and provenance.

Governance & Compliance

  • Enhanced policy engine — Declarative rules with agent, content, and time-based conditions. Policies can allow, deny, or require approval for specific operations.
  • Compliance reports via lean-ctx audit — Generate compliance reports from the audit trail. Supports filtering by time range, agent, and event type.
  • OWASP Agentic Top 10 alignment — 8 out of 10 categories have full coverage: Prompt Injection, Tool Misuse, Excessive Agency, Insecure Output, SSRF, Over-Reliance, Data Exfiltration, and Insufficient Logging.

Security Hardening

  • PathJail expanded — 16 path-typed argument keys are now validated and jailed, preventing path traversal in all tool parameters.
  • TOCTOU fix — O_NOFOLLOW on Unix prevents symlink race conditions during file operations.
  • Atomic writes for all JSON stores — Crash-safe writes for config, sessions, knowledge base, and audit trail.
  • Timing-safe authentication — All token and password comparisons use constant-time algorithms.
  • Proxy header allowlist — Only explicitly allowed headers are forwarded through the LLM proxy.
  • FILE_LOCKS LRU eviction — Prevents unbounded memory growth from accumulated file locks.
  • Tool execution timeout — 120-second hard timeout for all tool executions, preventing runaway operations.
  • TaskStore advisory file locks — Concurrent access to task stores is serialized via advisory locks.

MCP Alignment

  • MCP Server Card — .well-known/mcp-server.json discovery endpoint for standardized server metadata.
  • Reference results for large outputs — Tool responses exceeding size thresholds return references instead of inline data.
  • Context gateway metrics — New metrics endpoint for monitoring context gateway throughput and latency.
  • Dashboard audit events endpoint — /api/audit exposes audit trail events for the web dashboard.

Hebbian Knowledge Enhancement

  • Cognition Loop — 8-step background knowledge reorganization: seed promote, structural repair, fidelity check, lateral synthesis, contradiction resolution, Hebbian strengthening, decay, and compaction.
  • Knowledge Archetypes — 10 typed node categories (Architecture, Decision, Gotcha, Convention, Dependency, Pattern, Workflow, Preference, Observation, Fact) with salience-based ranking.
  • Fidelity Scoring — Two-tier quality metric (structural + semantic) influencing recall ranking.
  • Hebbian Edge Strengthening — Co-retrieved facts strengthen edges via saturating formula; exponential decay + pruning keep the graph lean.
  • Cross-Agent Knowledge Bridge — Controlled sharing of high-confidence facts between agents with provenance tracking and trust penalties.

Auto-Update UX

  • lean-ctx update --schedule — OS-native schedulers (macOS LaunchAgent, Linux systemd/cron, Windows Task Scheduler). Default OFF, explicit opt-in required.
  • Setup opt-in — Interactive setup asks about auto-updates (Step 9/11). Always changeable via CLI or config.
  • --quiet flag — Suppress output when already current (for background schedulers).
  • Session notifications — One-shot per-session update hint when a newer version is available.
  • [updates] config — New config section with auto_update, check_interval_hours, notify_only with env var overrides.

3.5.25 (May 2026)

CPU hotspot fixes, canonical rules policy, full registry migration.

Added

  • Process concurrency guard — Limits concurrent LeanCTX processes to 4 via flock slot locks, preventing CPU saturation when multiple agents trigger simultaneous operations.
  • Terse pipeline input cap & timeout — Skips inputs >64KB and enforces a 500ms deadline, preventing runaway CPU on large outputs (#210).
  • Canonical rules policy — New rules_canonical.rs module provides a single source of truth for all rule generation (MUST USE / NEVER USE tables) across Hybrid and MCP modes.
  • Contract tests for rules consistency — 11 cross-IDE contract tests verify generated rules contain correct MUST/NEVER language with no contradictions.
  • Property-based compression tests — proptest invariant tests for safeguard_ratio, entropy_compress, and compress_output.
  • MCP JSON instructions field — Editor MCP configs now include tool policy instructions where clients support it.

Changed

  • Rules language strengthened — All rule templates now use CRITICAL: ALWAYS, MUST USE, and NEVER USE instead of PREFER.
  • Background index throttled — Index builds run with nice -n 19 and ionice -c 3 to prevent CPU contention during setup.
  • Dictionary and quality gate optimized — Case-insensitive early-exit in apply_dictionaries, HashSet lookup in quality gate, identifier cap at 200.
  • Entropy compression safeguard — Falls back to original content when compression would inflate token count.

Fixed

  • 100% CPU on terse with large inputs (#210) — Combination of input cap, timeout budget, trigram cap, and process guard eliminates all known CPU hotspot scenarios.
  • env.sh self-heal loop — Container self-heal now includes 60-second cooldown and PID-lock check (max 4 concurrent).

3.5.24 (May 2026)

Unified Hybrid mode, CliRedirect elimination, LEAN_CTX_QUIET production mode.

Changed

  • Eliminate CliRedirect hook mode — All agents now use Hybrid (MCP for reads/search + shell hooks for command compression) or Mcp only. Cursor, Gemini CLI, and 18 more agents get automatic MCP installation with cached reads.
  • All agents default to Hybrid — recommend_hook_mode() returns Hybrid for all agents with shell access. MCP reads + shell compression = best of both worlds.
  • Cursor: automatic MCP installation — lean-ctx init --agent cursor and lean-ctx setup now install the MCP server config automatically.
  • Hybrid rules template v2 — Updated rule templates to clearly instruct ctx_read + ctx_search (MCP) for reads/search, lean-ctx -c (CLI) for shell.

Added

  • LEAN_CTX_QUIET=1 production mode — Suppresses all informational output: savings footers, session-start messages, tee-log hints. Shell compression still runs — only annotations are hidden.
  • Redirect subprocess timeout increased — Hook redirect timeout increased from 3s to 10s for reliable operation on slow filesystems.

Removed

  • HookMode::CliRedirect — Enum variant, CLI_REDIRECT_RULES constant, build_cli_redirect_instructions(), and the lean-ctx-cli-redirect.mdc template.
  • DedicatedCliRedirect / CursorMdcCliRedirect — Rules injection variants removed.

Fixed

  • Cursor reads/search not using MCP — CliRedirect mode prevented MCP installation. Now all rule files consistently instruct Hybrid mode.
  • Inconsistent rule files — .cursorrules, AGENTS.md, and .mdc templates now all instruct Hybrid mode.
  • macOS CI: rustup-init in PATH — Added explicit rustup default stable step to ensure toolchain is active.

3.5.23 (May 2026)

RAM Guardian with jemalloc, zstd cache compression, configurable savings footer suppression.

Added

  • RAM Guardian — adaptive memory management — RSS-based memory monitoring with adaptive tiered eviction. Uses jemalloc as global allocator on Unix for aggressive memory return. Configurable via max_ram_percent (default 5%). New /api/memory dashboard endpoint and lean-ctx doctor diagnostics.
  • zstd-compressed session cache — Cache entries now stored as zstd-compressed data, reducing in-memory footprint by ~60–80%.
  • Configurable savings footer suppression — New savings_footer config option (auto / always / never) and LEAN_CTX_SAVINGS_FOOTER env var. In auto mode (default), token savings footers are shown in CLI but suppressed in MCP/agent context.
  • Memory estimation and unload for indexes — BM25 and embedding indexes expose memory usage and can be unloaded by the RAM Guardian under pressure.

Fixed

  • CLI savings footer bypass — CLI footer formatting now delegates to the central format_savings() function, respecting the savings_footer configuration.
  • Daemon-delegated output footer leakage — Client-side filtering ensures footers are stripped when LEAN_CTX_SAVINGS_FOOTER=never, even when output comes from the daemon.
  • Shared session store cap — Reduced from 64 to 8 cached sessions to prevent unbounded memory growth.

3.5.22 (May 2026)

Native Windows daemon, IPC abstraction, overlay/FUSE read fix, CPU hotfix, dashboard improvements.

Fixed

  • Read: overlay/FUSE stat() race — read_file_lossy now opens the file first and uses fstat() on the file descriptor instead of a separate stat() syscall. Fixes sporadic "No such file or directory" errors in Docker overlay/FUSE filesystems (e.g. Codex sandboxes). Adds a single retry with 50ms backoff on NotFound.
  • 100% CPU after lean-ctx setup on Ubuntu — Two root causes: (1) env.sh self-heal script could recursively spawn lean-ctx init via BASH_ENV. Now guarded with container detection, recursion guard, and LEAN_CTX_ACTIVE propagation. (2) Graph index scanning could scan entire $HOME. Now guarded with is_safe_scan_root(), cross-process lock, 50k entry limit, and 2-minute timeout. LEAN_CTX_NO_INDEX env var skips indexing entirely. (#210)
  • Daemon modules now platform-independent — Removed all #[cfg(unix)] gates from daemon modules. daemon_client.rs auto-start works on all platforms.
  • Dashboard call graph timeout — Increased from 15s/30s to 60s for larger projects during initial build.

Added

  • Native Windows daemon support — IPC abstraction layer — New ipc/ module provides platform-independent daemon transport. Unix uses UDS (unchanged), Windows uses Named Pipes (\\.\pipe\lean-ctx-{hash}). All OS-specific code isolated in ipc/unix.rs and ipc/windows.rs. (#209)
  • HTTP-based daemon shutdown — New POST /v1/shutdown endpoint for cross-platform graceful shutdown. Falls back to SIGTERM/TerminateProcess, then force kill.
  • Parallel call graph build with progress tracking — CallGraph::build_parallel() uses rayon for concurrent file analysis with live progress. Dashboard polls via /api/call-graph/status.
  • Dashboard: call graph progress bar — Live progress bar during call graph builds with auto-polling every 2s.
  • Dashboard: project file browser in Compression Lab — Two tabs: "Recent" and "Project" (all indexed files). Includes search, file count, and token count per file.

Changed

  • serve_uds() replaced by serve_ipc() — Takes a DaemonAddr enum instead of a PathBuf.
  • daemon_socket_path() removed — Replaced by daemon::daemon_addr() returning a DaemonAddr enum.

3.5.21 (May 2026)

Graph data directory fix, graph index UX, config schema validation, dashboard expandable events.

Fixed

  • graph.db and graph.meta.json now honor LEAN_CTX_DATA_DIR — Property graph files stored in $DATA_DIR/graphs/<project_hash>/. Transparent migration moves existing files from <project>/.lean-ctx/ on first access. (#205)
  • Graph index UX: correct labels and configurable cap — lean-ctx gain shows "files" instead of "nodes". New config key graph_index_max_files (default: 5000). (#206)
  • Config documentation accuracy — Removed phantom sections and corrected wrong defaults across website docs. (#208)

Added

  • Dashboard expandable event details — Event cards in the Live Observatory are now clickable with accordion pattern and lazy-loaded full metrics. (#207)
  • lean-ctx config schema — Outputs complete JSON schema of all configuration keys.
  • lean-ctx config validate — Validates config.toml against the schema with "did you mean?" suggestions.

3.5.20 (May 2026)

Codex installer fixes, Windows path normalization, and CLI flag validation.

Fixed

  • Codex installer respects CODEX_HOME — lean-ctx init --agent codex now reads the CODEX_HOME environment variable. All Codex config files are written to $CODEX_HOME instead of always using ~/.codex. (#202)
  • Codex feature flag migrated to hooks — The installer now writes hooks = true instead of the deprecated codex_hooks = true. Existing entries are auto-migrated. (#203)
  • lean-ctx ls rejects unsupported flags — Flags like -la, -l, -R now return a clear error with usage hints. Supported: --all/-a, --depth N. The shell hook continues passing ls flags to the system ls. (#201)
  • Windows path format for inline rewrites — handle_rewrite_inline() returns native OS paths on Windows instead of MSYS format (/c/Users/...). New from_bash_to_native_path() function provides symmetrical conversion. (#204)

Added

  • Path normalization tests — 11 new normalize_tool_path() tests, 6 new from_bash_to_native_path() tests including Windows/Unix roundtrips.

3.5.19 (May 2026)

Shell hook drop-in install, output policy classification, dashboard audit, and agent-aware non-interactive tracking.

Added

  • Shell hook drop-in install — Users with .d/-style dotfiles (chezmoi, yadm, stow, oh-my-zsh custom/) now get hook fragments installed as numbered drop-in files (e.g. ~/.zshenv.d/00-lean-ctx.zsh) instead of inline fenced blocks. Detection is automatic (Style::Auto); override with --style=inline or --style=dropin. Transparent migration between styles preserves hand-edits via timestamped backups.
  • Output policy classification — New OutputPolicy enum (Passthrough, Verbatim, Compressible) provides centralized command classification for the compression pipeline. Commands like gh api, az login, docker ps, kubectl get pods are now correctly classified and never compressed.

Fixed

  • Dashboard: 7 frontend data mismatch bugs — Complete attribute-by-attribute audit of all 17 dashboard pages. Fixed field name mismatches, falsy checks hiding zero values, incorrect API field mapping in Overview, Health, Agents, Memory, Live, Compression Lab, and Graph components.
  • Token Pressure accuracy — Context field temperature now uses pressure.utilization (weighted decay) instead of raw ratio for consistency with the Token Pressure card.
  • Truncation bug (#199) — Removed aggressive 8000-byte fallback truncation that caused AI models to retry commands. Large outputs now flow through the safety-aware compress_if_beneficial pipeline.
  • Shell hook: ls and find added — Both commands are now included in the generated shell hook alias list, so directory listings are tracked and compressed. (#200)
  • Shell hook: agent-aware TTY bypass — The TTY guard ([ ! -t 1 ]) now checks for agent environment variables (LEAN_CTX_AGENT, CODEX_CLI_SESSION, CLAUDECODE, GEMINI_SESSION). Non-interactive agent commands in Docker/Codex are now tracked. (#200)

3.5.18 (May 2026)

Fixed

  • gh api output no longer compressed — Commands like gh api repos/.../actions/jobs/.../logs are now passthrough (no compression, no truncation). Previously, large API responses were silently truncated by the generic 8000-byte fallback.

3.5.17 (May 2026)

Security

  • [Critical] LLM Proxy bearer token auth — The proxy server now supports optional bearer token authentication via LEAN_CTX_PROXY_TOKEN.
  • [Critical] Symlink hijack protection — write_atomic() and context package atomic_write() now reject writes through symlinks.
  • [High] Claude binary path validation — claude mcp add-json validates that the resolved claude binary comes from a trusted directory.
  • [High] TOCTOU mitigation — New write_atomic_with_backup_checked() validates file mtime between read and write.
  • [High] Auto-approve transparency — lean-ctx setup now displays a banner listing all auto-approved MCP tools. New --no-auto-approve flag.
  • [High] Full integrity verification — verify_integrity() now validates content_hash, sha256, and byte_size.

3.5.16 (May 2026)

Major security hardening, structural output protection, and context runtime research modules.

Security (32 fixes)

  • [Critical] Path traversal fixes - tee show and dashboard compression-demo no longer accept path separators or ..
  • [Critical] Injection prevention - ctx_execute intent parameter sanitized to alphanumeric only; CSPRNG failures now panic
  • [Critical] MCP stdio overflow guard - Content-Length headers validated with checked_add and size cap
  • [High] Dashboard auth hardened - loopback token exposure fixed, nonce-based CSP replaces unsafe-inline
  • [High] Data isolation - ctx_share scoped per project hash, ctx_execute output redacted, panic payloads no longer leaked
  • [High] Resource exhaustion - SSE subscriber cap enforced (64/channel), Rust sandbox environment isolated
  • [Medium] Crypto upgrade - Argon2id password hashing, SQLite busy_timeout, ReDoS mitigation for filter rules
  • [Medium] Error sanitization - A2A handoff, cloud server, and context summary errors no longer leak OS details

Fixed

  • Structural output protection - git diff, git show, git blame, git log -p, git stash show, diff, colordiff, icdiff, and delta output is no longer mangled by compression. Dedicated fast path preserves all +/- lines, hunk headers, and blame annotations verbatim.
  • Zsh completion fix — compinit sourcing in the shell hook no longer blocks interactive shells when completion dirs are missing. #193

Changed

  • Security hardening test strengthened — the security_resolve_path_guard test suite now covers additional traversal vectors (encoded slashes, null bytes, overlong UTF-8) and asserts stricter deny semantics for symlink-to-outside-project scenarios.

Added

  • 13 context runtime research modules - adaptive chunking (Rabin-Karp), attention placement, cognitive load estimation (Halstead), cyclomatic complexity, gamma cover sets, graph features, information bottleneck (Blahut-Arimoto), MDL selector, memory consolidation, progressive compression, SPLADE retrieval, structural diff, structural tokenizer (18 languages)
  • Louvain community detection O(m) - rewrote from O(n²) to edge-list-based with modularity optimization
  • Enhanced PageRank - configurable damping, convergence detection, seed biasing
  • SPLADE-enhanced BM25 - sparse expansion terms for improved recall
  • memory_cleanup config option - aggressive (default, 5 min TTL) or shared (30 min TTL) for multi-IDE setups
  • Shell activation mode — new shell_activation config option with three modes: always (default, all shells), agents-only (only when AI agent env vars detected), off (manual activation via lean-ctx-on). Override via LEAN_CTX_SHELL_ACTIVATION env var.
  • Explicit project identity (.lean-ctx-id) — new highest-priority identity marker file for Docker environments. Place a .lean-ctx-id file in your project root with a unique project name to prevent hash collisions when different projects share the same /workspace mount path.
  • Docker project isolation fix — graph index, semantic cache, bandit, and embedding index now use a composite project hash (path + identity) instead of path-only hash. Existing data is automatically migrated from old hash directories. No user action required.

3.5.15 (May 2026)

Critical bug fixes for dashboard auth and large file handling.

Fixed

  • Dashboard "unauthorized" on localhost - auto-injects auth token for loopback connections so the dashboard works without manual token setup
  • Large file crash / MCP hang - reading multi-GB files no longer causes unbounded memory allocation; 4-layer protection: binary detection, metadata check, stat guard, MCP error semantics

Added

  • Binary file detection - 100+ binary file extensions recognized with human-readable labels
  • Live Observatory help - every dashboard event now has an inline explanation with actionable guidance
  • memory_cleanup setting - aggressive (5 min idle TTL) or shared (30 min TTL) via config or LEAN_CTX_MEMORY_CLEANUP

3.5.14 (May 2026)

Performance overhaul and new analysis tools.

Performance

  • BLAKE3 hashing - 3x faster content hashing across all file operations
  • Tree-sitter query cache - repeated structural queries skip re-parsing
  • SQLite Property Graph optimization - faster graph traversal for architecture and impact analysis
  • Token cache upgrade - capacity increased from 256 to 2048 entries
  • Parallel indexing with rayon - multi-threaded project indexing
  • Compact JSON serialization - reduced wire size for MCP responses

Improved

  • Rules mode selection decision tree - improved heuristics for auto-selecting read modes (community contribution)
  • Flaky test fixes - stabilized intermittent CI failures

Added

  • core::hasher module - BLAKE3-based content hashing abstraction
  • core::community - Louvain clustering for dependency graph analysis
  • core::pagerank - PageRank scoring for file importance
  • core::smells - code smell detection engine
  • ctx_smells tool - code smell detection with graph-enriched scoring
  • 58 MCP tools (up from 57)

3.5.13 (May 2026)

Instruction file handling fix and formal verification expansion.

Fixed

  • Instruction files always delivered in full mode - SKILL.md, AGENTS.md, and RULES.md are no longer compressed, ensuring agent instructions are never mangled
  • Markdown files exempt from aggressive compression - prevents loss of formatting in documentation files
  • Windows Claude Code PowerShell compatibility - resolved shell detection issues when running under Claude Code on Windows

Added

  • is_instruction_file() API - programmatic check for instruction file detection
  • Lean4 formal proofs - Theorems 12-13 added to the formal verification suite
  • 7 regression tests - covering instruction file handling and compression exemptions

3.4.2 (April 2026)

Bug fixes for Unicode paths and Windows shell detection.

Fixed

  • Unicode SIGABRT in ctx_overview - directory path truncation used byte-index slicing which panicked on multi-byte UTF-8 characters (Chinese, Japanese, Korean, emoji paths). Replaced with char-boundary-safe truncation. #154
  • Windows shell detection in Git Bash / MSYS2 - find_real_shell() now checks MSYSTEM/MINGW_PREFIX env vars before PSModulePath, preventing incorrect PowerShell detection when running inside Git Bash. #156

Added

  • Shell hint in MCP instructions (Windows) - on Windows, instructions now include the detected shell type with explicit guidance, helping LLMs generate correct commands for the active shell environment
  • Shell mismatch hint in ctx_shell responses (Windows) - when a command fails and contains PowerShell cmdlets while the detected shell is POSIX, a correction hint is appended

3.4.1 (April 2026)

Performance & token optimization release.

Highlights

  • Up to 64% lower per-session token overhead - best-case overhead reduced from ~6,600 to ~2,400 tokens through lazy tools + minimal_overhead mode
  • Async I/O on hot paths - session saves and cost attribution no longer block tool responses, reducing latency for every tool call
  • New minimal_overhead mode - set minimal_overhead = true or LEAN_CTX_MINIMAL=1 to suppress auto-checkpoints, meta-strings, and session blocks in instructions. Ideal for Codex and cost-sensitive environments

Performance

  • Session.save() split into prepare_save() (CPU under lock) + write_to_disk() (background thread) - serialization stays fast, disk I/O no longer blocks responses
  • CostStore writes deferred to background via tokio::task::spawn_blocking
  • mcp-live.json writes debounced to every 5th tool call (80% fewer disk writes)
  • count_tokens called once per tool response instead of up to 4 times - cached result reused for hints, cost attribution, and logging
  • compress_output skipped entirely for Normal density (no string copy)
  • md5_hex_fast - 8x faster fingerprinting for large outputs (>16 KB) by hashing prefix + suffix + length

Token Savings

  • Auto-checkpoint injection disabled under minimal_overhead - eliminates the largest per-call token overhead source
  • Meta-strings (stale_note, savings_note, shell efficiency hints, archive hints) suppressed under minimal_overhead
  • Session/knowledge/gotcha blocks removed from MCP instructions under minimal_overhead

Bug Fixes

  • Fixed integer overflow crash in shell_efficiency_hint when output tokens exceeded input tokens (e.g. shell commands that expand output) - now uses saturating_sub
  • Synchronous save() restores retry counter on disk write failure, preserving auto-save retry behavior

3.4.0 (April 2026)

Highlights

  • Lazy tools now the default - only 9 core tools exposed by default instead of 46, reducing per-turn input overhead by ~80%. Use LEAN_CTX_FULL_TOOLS=1 to opt back in. ctx_discover_tools lets agents load additional tools on demand
  • XDG Base Directory compliance - new installs use $XDG_CONFIG_HOME/lean-ctx. Existing ~/.lean-ctx directories auto-detected
  • JSONC comment support - config writers now parse JSON with // and /* */ comments
  • Shell hook disable - --no-shell-hook flag, shell_hook_disabled = true config, LEAN_CTX_NO_HOOK=1 env var

3.3.3 (April 2026)

Highlights

  • Official release tag: LeanCTX 3.3.3 was marked as the stable build at time of release
  • Stability improvements across all MCP tools
  • Refined CEP v1 (Context Efficiency Protocol) instruction codes

Improvements

  • Improved CRP mode density - budget enforcement at ≤150 tokens per response
  • Enhanced ctx_knowledge with rooms, search, and wakeup actions
  • Better session resume flow with ctx_session resume action
  • Polished Observatory TUI dashboard layout

Bug Fixes

  • Fixed edge case where ctx_dedup could skip entries with identical hashes but different paths
  • Corrected cache-hit stub token count reporting in ctx_gain
  • Fixed ctx_tree depth parameter not respecting symlink boundaries

3.3.2 (March 2026)

Highlights

  • Composite project hash: New project_hash combines content hash, structure hash, and config hash into a single deterministic fingerprint for change detection
  • Codex hooks integration: Native hook support for OpenAI Codex CLI - PreToolCall, PostToolCall, and SessionStart events

New Features

  • project_hash - composite hash for CI caching and drift detection across branches
  • Codex hook scripts auto-installed via lean-ctx install --codex
  • ctx_knowledge action="timeline" - chronological view of knowledge base entries

Improvements

  • Faster ctx_preload with parallel file reads (up to 4x speedup on large projects)
  • Reduced memory footprint for sessions with 50+ cached files

Bug Fixes

  • Fixed project_hash inconsistency when .gitignore patterns changed between runs
  • Resolved Codex hook permission errors on Windows WSL environments

3.3.1 (February 2026)

Highlights

  • 85+ new passthrough entries: Massive expansion of the shell passthrough table - commands that are passed through uncompressed when compression would lose critical information

New Features

  • 85+ new passthrough patterns for debugging tools (strace, ltrace, perf), database CLIs (psql, mysql, redis-cli), and cloud CLIs (aws, gcloud, az)
  • ctx_shell raw=true - explicit bypass for any command, returning uncompressed output

Improvements

  • Better error messages when passthrough entries conflict with custom compression patterns
  • Shell pattern matching now supports glob wildcards in command prefixes

Bug Fixes

  • Fixed passthrough not triggering for commands with leading whitespace
  • Resolved ctx_shell timeout not resetting between chained commands

3.3.0 (January 2026)

Major release - expanded tool surface and protocol overhaul.

Highlights

  • 46 MCP tools: Expanded from 38 to 46 tools, adding analysis, graph, and workflow categories
  • CEP v1 protocol: New Context Efficiency Protocol with 5-rule framework and instruction codes
  • 18 tree-sitter grammars: Full language coverage for structural analysis

New Tools

ToolCategoryDescription
ctx_architectureAnalysisProject architecture overview with dependency graph
ctx_graphAnalysisBuild and query code dependency graphs
ctx_heatmapAnalysisFile complexity and change-frequency heatmaps
ctx_impactAnalysisChange impact analysis - what breaks if you modify X
ctx_workflowWorkflowMulti-step workflow orchestration
ctx_executeWorkflowExecute workflow steps with rollback

Improvements

  • Rewritten instruction system with ACT1, BRIEF, FULL, DELTA, NOREPEAT, STRUCT, 1LINE codes
  • Auto-checkpoint every 15 tool calls (configurable)
  • Tree-sitter grammars now cover TypeScript, Python, Rust, Go, Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, Scala, Lua, Zig, Elixir, Haskell, OCaml

Breaking Changes

  • CRP mode output format changed - agents using hard-coded parsers should update
  • ctx_agent action="handoff" renamed to ctx_handoff (old form still accepted with deprecation warning)

3.2.9 (December 2025)

Highlights

  • LEAN_CTX_SHELL_TIMEOUT_MS: New environment variable to control shell command timeout globally - prevents runaway processes from blocking sessions

New Features

  • LEAN_CTX_SHELL_TIMEOUT_MS - configurable shell timeout (default: 30000ms), applied to all ctx_shell invocations
  • ctx_shell now reports timeout kills with exit code and partial output

Improvements

  • Graceful SIGTERM → SIGKILL escalation for timed-out processes (500ms grace period)
  • Timeout duration shown in ctx_metrics per-command breakdown

Bug Fixes

  • Fixed zombie process accumulation when timeout killed a process group
  • Resolved ctx_shell not cleaning up temp files after timeout

3.2.8 (November 2025)

Highlights

  • Gemini path change: Gemini CLI MCP configuration moved from ~/.gemini/config.json to VS Code settings.json - LeanCTX auto-detects the new path

New Features

  • Auto-detection of Gemini MCP config in settings.json during lean-ctx install --gemini
  • lean-ctx doctor now checks both legacy and new Gemini config locations

Improvements

  • Installer shows migration instructions when legacy Gemini config is detected
  • Updated Getting Started guide with new Gemini setup steps

Bug Fixes

  • Fixed installer creating duplicate MCP entries when both config locations existed
  • Resolved Gemini config validation failing on Windows backslash paths

3.2.6 (October 2025)

Highlights

  • rules_scope: New config option to control which rule files LeanCTX injects - filter by project, user, or global scope

New Features

  • rules_scope config option - restrict injected rules to specific scopes ("project", "user", "global", or combinations)
  • ctx_read mode="reference" - compact reference-only output for documentation files

Improvements

  • Rule injection now respects .cursorignore patterns
  • Faster startup when many rule files are present (lazy loading)

Bug Fixes

  • Fixed rules_scope="project" accidentally including workspace-level rules
  • Resolved rules not reloading after config change without server restart

3.2.0 (August 2025)

Major feature release - HTTP server mode.

Highlights

  • lean-ctx serve: HTTP server mode for running LeanCTX as a standalone service - enables remote agents, web integrations, and custom toolchains to use LeanCTX over HTTP

New Features

  • lean-ctx serve - starts an HTTP server with REST API endpoints mirroring all MCP tools
  • lean-ctx serve --stdio - stdio mode for container and pipe-based integrations
  • lean-ctx serve --port 9315 - configurable port (default: 9315)
  • Health check endpoint at /health with session and cache stats

Improvements

  • All 38 tools (at the time) accessible via POST /tool/:name with JSON body
  • Session management via X-Session-ID header - enables multi-tenant usage
  • CORS support for browser-based integrations

Bug Fixes

  • Fixed stdio mode not flushing output buffers on slow connections
  • Resolved session cleanup not triggering for HTTP sessions after idle timeout

3.0.1 (June 2025)

First stable release of the v3 series.

Highlights

  • lean-ctx watch (Observatory TUI): Real-time terminal dashboard showing active sessions, tool calls, token savings, cache status, and agent activity

New Features

  • lean-ctx watch - interactive terminal UI with live session monitoring
  • Dashboard panels: active agents, recent tool calls, token savings graph, cache hit rate, file reference table
  • Keyboard shortcuts: q quit, r refresh, t toggle tool detail, f filter by agent

Improvements

  • Complete rewrite from Node.js to Rust - 10x faster startup, 5x lower memory
  • Single binary distribution - no runtime dependencies
  • Tree-sitter integration for structural code analysis (initial 12 grammars)

Bug Fixes

  • Fixed file watcher not detecting changes on NFS-mounted directories
  • Resolved TUI rendering artifacts on terminals with non-standard color support
  • Fixed ctx_read returning stale content when file was replaced (not modified in-place)