lean-ctx

What lean-ctx Does

lean-ctx is an MCP (Model Context Protocol) server and runtime environment designed specifically for AI coding agents working with Claude Code. It intelligently manages context windows by implementing session caching, AST-aware code compression, and 90+ pre-built shell patterns that drastically reduce token consumption. This is essential for developers and AI agents that need to maintain long coding sessions without hitting token limits or incurring excessive API costs.

The tool targets product designers and power users who leverage AI agents for code generation, refactoring, and debugging tasks. By compressing code representations while preserving semantic meaning, lean-ctx enables AI agents to operate on larger codebases and maintain richer context about project structure without the overhead of full source code transmission. It’s particularly valuable when working with Claude Code, where token efficiency directly impacts productivity and cost.

How to Install

Installation Steps

Prerequisites

• Node.js 16+ or Python 3.8+
• Git installed on your system
• Claude Code integration enabled in your development environment

Installation via npm (Recommended)

npm install -g lean-ctx

Installation from Source

1. Clone the repository:

git clone https://github.com/yvgude/lean-ctx.git
cd lean-ctx

2. Install dependencies:

npm install
# or
pip install -r requirements.txt

3. Build the project:

npm run build

4. Install globally (optional):

npm link

Configuration

1. Create a configuration file in your project root (.lean-ctx.json):

{
  "sessionCache": true,
  "compressionLevel": "aggressive",
  "astAnalysis": true,
  "shellPatterns": "default",
  "tokenLimit": 100000
}

2. Add lean-ctx to your Claude Code configuration in your IDE settings

3. Restart your Claude Code integration to activate the MCP server

Verification

Verify installation by running:

lean-ctx --version
lean-ctx --test

Use Cases

• Long-running coding sessions: Maintain context across multi-file refactoring projects that would normally exceed token limits, allowing AI agents to understand the full scope of changes needed across an entire codebase without losing context about previously analyzed files.
• Cost optimization for enterprise teams: Reduce API costs for teams running multiple AI coding agents by 40-60% through intelligent context compression, making AI-assisted development economically viable for large-scale projects and continuous integration pipelines.
• Real-time debugging large codebases: Compress repository structure and error traces while preserving AST relationships, enabling Claude Code to pinpoint bugs in complex systems faster without sending redundant source code representations.
• Rapid prototyping with full context: Maintain rich context about project architecture, dependencies, and patterns across multiple sessions, allowing designers and developers to iterate quickly without re-explaining the codebase to the AI agent each session.
• Shell script automation: Leverage 90+ pre-built shell patterns to automate common development workflows (builds, tests, deployments) while reducing token usage, making scripting suggestions from Claude Code more efficient and cost-effective.

How It Works

lean-ctx operates as an MCP server that sits between Claude Code and your development environment, intercepting code context requests and applying three core optimization strategies. When an AI agent requests file context, lean-ctx first checks its session cache to see if the file has been analyzed before. If it exists in cache with the same file hash, it returns the compressed representation directly, eliminating redundant processing. This session-level caching is crucial for multi-file operations where the same modules are referenced repeatedly.

The second optimization layer uses Abstract Syntax Tree (AST) analysis to compress code intelligently. Rather than sending raw source code, lean-ctx parses Python, JavaScript, TypeScript, and other supported languages into their AST representations, then performs semantic-aware compression. It preserves critical information like function signatures, class hierarchies, and dependency relationships while removing non-essential elements like comments, whitespace, and intermediate variable assignments. This maintains the AI agent’s understanding of code behavior while reducing token count by 50-70% for typical projects.

The third component provides 90+ pre-built shell pattern templates for common development tasks (running tests, building Docker images, deploying to cloud platforms, etc.). Instead of having the AI agent generate shell commands from scratch (which requires verbose context about the project setup), it can reference these patterns by name. For example, rather than explaining how to build a Node.js project, the agent can simply invoke the ‘node-build’ pattern, which lean-ctx expands with environment-specific parameters. This pattern-based approach reduces tokens needed to execute complex workflows by 30-40% while improving consistency and reliability.

Pros and Cons

Pros:

• Reduces token usage by 40-60% through intelligent AST-aware compression and session caching
• Transparent integration with Claude Code—no code changes required, works as MCP middleware
• 90+ pre-built shell patterns for common development tasks reduce scripting overhead significantly
• Local processing with encrypted caching means no code leaves your machine
• Supports 8+ programming languages with full AST parsing, degrades gracefully for unsupported languages
• Substantial cost savings for enterprise teams running AI coding agents at scale
• Customizable patterns and compression levels allow tuning to specific project needs

Cons:

• Initial setup and configuration required; not plug-and-play for all IDE environments
• Performance overhead on first analysis pass while AST parsing occurs (negligible on subsequent cache hits)
• Compression may sometimes lose non-semantic information that a human would find valuable (verbose error messages, detailed comments)
• Requires Node.js or Python runtime—adds dependency for some lightweight development environments
• Custom shell patterns need maintenance and updates as project build systems evolve
• Limited effectiveness on very small projects or single-file codebases where compression overhead isn’t justified

Related Skills

• Claude Code: The AI coding assistant integrated with lean-ctx; lean-ctx optimizes context delivery for Claude Code agents
• Tree-sitter: A parser library for multiple languages that lean-ctx uses for AST generation and syntax-aware code analysis
• Github Copilot: Alternative AI coding assistant; lean-ctx’s compression techniques apply similarly to other code AI tools
• Local LLMs with llama.cpp: For teams running local language models, lean-ctx’s compression strategies reduce resource requirements
• Conventional Commits: Git workflow tool that pairs well with lean-ctx’s shell patterns for automated commit and versioning workflows

Alternatives

• Custom context management scripts: Teams can write bespoke Python or Node.js scripts to compress their specific codebases, but this requires manual maintenance and loses the pre-built patterns and AST-aware optimizations lean-ctx provides.
• Manual codebase chunking: Breaking large projects into smaller submissions to Claude Code, but this fragments context and requires developers to manually track which files have been previously analyzed, losing session-level efficiency gains.
• Prompt engineering alone: Instructing Claude Code to be concise or summarize code, but this is less effective than structural compression and doesn’t reduce actual token consumption, only works within a single conversation turn.