yvgude/lean-ctx

LeanCTX is the Context Gateway for AI Systems. Select task-relevant context, apply supported controls, connect local knowledge and inspect recorded evidence. Open-source Engine: CLI, MCP, hooks and supported proxy paths.

What it solves

LeanCTX is a context gateway that sits between AI tools and the information they access. It prevents AI agents from being overwhelmed by noisy or redundant data, reducing token usage and costs while improving the focus of the input provided to the LLM.

How it works

LeanCTX operates on two planes: the read path and the wire path. On the read path, it uses an MCP server and shell hooks to select, compress, and filter information from files and CLI output before it reaches the AI tool. On the wire path, an optional proxy can route requests to the model provider to further reduce prompt and history content.

Key mechanisms include:

  • Context Compression: Uses 16 different read modes (such as map, signatures, and density) and Tree-sitter ASTs for structural understanding of 27 languages to reduce token counts.
  • Intelligent Triage: An IntentEngine and ModePredictor classify query complexity and learn optimal read modes per file type.
  • Knowledge Routing: Maintains a local knowledge graph, session memory, and property graph for cross-source context and impact analysis.
  • Usage Evidence: Tracks costs and outcomes via a local ledger and a browser dashboard, using "Cost per Accepted Outcome" (CPAO) as a primary metric.

Who it’s for

Developers using AI coding assistants (like Claude Code, Cursor, or Codex) who want to lower their token costs, maintain tighter control over what their AI can see, and keep their session memory local and portable.

Highlights

  • Token Reduction: Workload-specific compression for file reads and 85+ shell-output patterns (e.g., git, npm, docker).
  • JIT Disclosure: Provides outlines first and expands bodies on demand using signatures and lines:N-M modes.
  • Local-First Memory: Session state and knowledge graphs are stored locally and can be exported as .ctxpkg packages.
  • Shadow Mode: Simulates a baseline to estimate potential token and cost savings without altering the active workflow.
  • LSP Integration: Supports language-server-powered refactoring and navigation (rename, go-to-definition) via ctx_refactor.

Related

  • Project
    Leanmcp/gateway-skills

    An AI gateway proxy that provides full visibility into the requests, file access, and token costs of AI coding agents like Claude Code.

  • Project
    headroomlabs-ai/headroom

    Headroom is a context compression layer for AI agents and LLM applications. It compresses prompts, tool outputs, logs, RAG chunks, and conversation history locally before they reach the model, cutting token usage by 30–90% while preserving accuracy and allowing reversible retrieval of original content.

  • Project
    larsderidder/context-lens

    A local proxy that captures LLM API calls from AI coding tools to provide a detailed visual breakdown of context window composition and token costs.

  • Project
    ranxianglei/billion-context

    A context-compression proxy for AI agents that uses model-driven summaries to reduce token usage and enable month-long coding sessions within small context windows.

  • Project
    elara-labs/code-context-engine

    A local codebase indexing engine that reduces AI coding assistant costs by replacing full-file reads with targeted semantic search and retrieval.