Changelog

Complete version history for lean-ctx. Each release includes new features, improvements, and bug fixes. lean-ctx follows semantic versioning.

3.5.14 (May 2026)

Current stable release - 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: lean-ctx 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

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 - lean-ctx 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 Editor Integrations 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 lean-ctx 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 lean-ctx as a standalone service - enables remote agents, web integrations, and custom toolchains to use lean-ctx 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)