context-pilot-mcp 0.2.1

Universal context manager for AI coding agents

context-pilot-mcp

Universal context manager for AI coding agents.

context-pilot-mcp tracks file relevance, compresses stale files via AST, and evicts dead weight to keep your AI agent's context window highly optimized.

No manual bookkeeping required. By using the provided read_file tool, the engine automatically handles event tracking, token counting, and structural compression in the background. It is natively compatible with Claude Code, Cursor, VS Code (Cline/Roo), and more.

---

The Problem

AI coding agents (like Aider or Claude Code) are great at pulling files into context, but terrible at letting them go. Over a multi-turn session, the context window fills up with files that were only relevant 10 turns ago.

• Local model users (4K-32K windows) crash or overflow early.
• Cloud users pay massive, unnecessary API costs for carrying dead weight.
• "Lost in the middle" degradation causes AI to hallucinate or ignore instructions.

The V0.2.1 Pivot: Transparent Proxy

Unlike other context managers that require the LLM to remember to "track" its own actions, context-pilot-mcp acts as a transparent middleware:

1. Automatic Tracking: Whenever the agent reads a file through the MCP, we log the event and update the staleness matrix.
2. Dynamic Compression: If a file is stale, read_file automatically returns a tree-sitter compressed version (signatures only) to save tokens without the LLM even knowing.
3. Multi-Language AST: Supports Python, JavaScript, TypeScript, and Go out of the box using tree-sitter.

---

Benchmarks (Aider Codebase)

When tested on massive Python files, the "compress-before-drop" AST engine yields massive token savings without blinding the LLM to the codebase structure:

File	Original Tokens	Compressed Tokens	Savings
base_coder.py	21,575	7,858	64%
commands.py	15,557	5,796	63%
repomap.py	6,825	2,080	70%
Total	43,957	15,734	64%

In a simulated 10-turn coding session with a 16K budget, context-pilot-mcp successfully reclaimed 23,479 tokens dynamically without deleting active context.

---

Installation

Install globally on your system:

pip install context-pilot-mcp

---

Connecting to your AI Agents

Because it utilizes the open Model Context Protocol (MCP), integration is native and takes seconds.

1. Claude Code

Register the server globally via the Claude CLI:

Mac / Linux:

claude mcp add context-pilot-mcp context-pilot-mcp

Windows:

claude mcp add context-pilot-mcp python -m context_pilot.adapters.mcp_server

2. Cursor IDE

1. Open Settings (Cmd/Ctrl + ,).
2. Go to Features > MCP Servers and click + Add new MCP server.
3. Set Name to context-pilot, Type to command, and Command to context-pilot-mcp. (On Windows, if the binary is not in PATH, use: python -m context_pilot.adapters.mcp_server)
4. Save.

---

Provided MCP Tools

Once attached, your AI agent automatically gains the following capabilities:

• read_file(path): The Primary Hook. Replaces standard file reading. Automatically tracks usage, counts tokens, and applies AST-compression if the file is stale.
• optimize_context(budget, pressure): Imperative Enforcement. Evaluates context and provides the agent with a list of files it MUST drop or compress to stay within limits.
• status(): Returns a tabular visualization of all loaded context, their tokens, turn ages, and staleness scores.
• start_task(): Explicitly advances the turn counter for a new task.
• drop_file(path): Notifies the engine that a file has been purged.

---

Configuration

You can tune the engine's behavior by placing a .context-pilot.toml file in the root of your project:

[context-pilot]
mode = "suggest"            # "suggest", "auto", or "off"
pressure_threshold = 0.8    # Trigger eviction when window is 80% full
stale_after_turns = 5       # Unreferenced turns before considering stale
edit_stickiness = 3         # Edited files stay in context for N extra turns
compress_before_drop = true # Try AST compression before full eviction
max_context_tokens = 128000 # Your model's context window size
min_staleness_to_flag = 0.6 # Only flag files that are at least 60% stale

License: MIT