context-pilot-mcp 0.2.5

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 routing file reads through the 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), Antigravity, and any MCP-compatible agent.

---

The Problem

AI coding agents 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 for dead weight that no longer helps the task.
• "Lost in the middle" degradation causes hallucination and ignored instructions.

---

How It Works (v0.2.3)

context-pilot acts as a transparent middleware layer:

1. Automatic Tracking — Every read_file call logs a turn-stamped event and updates the staleness matrix.
2. Native Read Tracking — Used your agent's built-in file reader? Call track_file(path) to register it so the staleness model stays accurate.
3. Transparent Compression — Stale files are automatically compressed (signatures only, via tree-sitter AST). When compression fires, the response is prefixed with an explicit warning banner — the agent always knows it's working from a skeleton, not the full source.
4. Explicit Turn Counting — Call start_task() at the start of each new task. Staleness is measured in conversation turns, not wall-clock time.
5. Multi-Language AST — Supports Python, JavaScript, TypeScript, and Go out of the box.

---

Benchmarks (Aider Codebase)

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 reclaimed 23,479 tokens dynamically without deleting active context.

---

Installation

pip install context-pilot-mcp

---

Connecting to Your Agent

Claude Code

# 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

Antigravity

Add the following to your Antigravity MCP config (e.g. ~/.gemini/antigravity/mcp_config.json):

{
  "mcpServers": {
    "context-pilot": {
      "command": "/home/<your-user>/.local/bin/context-pilot-mcp",
      "args": []
    }
  }
}

Tip: Replace /home/<your-user>/ with your actual home directory path. After installing with pip install context-pilot-mcp, the binary is placed at ~/.local/bin/context-pilot-mcp on Linux/macOS.

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, use: python -m context_pilot.adapters.mcp_server)
4. Save.

Generic mcp_config.json

{
  "mcpServers": {
    "context-pilot": {
      "command": "context-pilot-mcp",
      "args": []
    }
  }
}

---

MCP Tools Reference

Tool	Description
read_file(path, compress_if_stale=True)	Primary hook. Reads a file, tracks the event, and compresses if stale. Returns a visible [COMPRESSED VIEW] banner when compression fires.
track_file(path)	Register a read that happened via native agent tools. Keeps staleness scores accurate for files not read through read_file.
start_task()	Advance the turn counter. Call once per new task/subtask. Staleness is turn-based, not time-based.
optimize_context(budget, pressure)	Evaluate context pressure and get a ranked list of files to drop or compress.
drop_file(path)	Remove a file from tracking after evicting it from context.
status()	Tabular view of all tracked files — tokens, turn age, staleness score.

---

Configuration

Place a .context-pilot.toml in your project root to tune behavior:

[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 considered stale
edit_stickiness = 3         # Edited files stay in context 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 >= 60% stale

---

License: MIT