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:
- Automatic Tracking — Every
read_filecall logs a turn-stamped event and updates the staleness matrix. - Native Read Tracking — Used your agent's built-in file reader? Call
track_file(path)to register it so the staleness model stays accurate. - 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.
- Explicit Turn Counting — Call
start_task()at the start of each new task. Staleness is measured in conversation turns, not wall-clock time. - 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 withpip install context-pilot-mcp, the binary is placed at~/.local/bin/context-pilot-mcpon Linux/macOS.
Cursor IDE
- Open Settings (Cmd/Ctrl +
,). - Go to Features › MCP Servers and click + Add new MCP server.
- Set Name to
context-pilot, Type tocommand, and Command tocontext-pilot-mcp. (On Windows, use:python -m context_pilot.adapters.mcp_server) - 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
Metadata
Release files for context-pilot-mcp 0.2.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| context_pilot_mcp-0.2.5.tar.gz | 371.7 kB | Without provenance | Details for context_pilot_mcp-0.2.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| context_pilot_mcp-0.2.5-py3-none-any.whl | Python 3 | none | any | Details for context_pilot_mcp-0.2.5-py3-none-any.whl |
Total release size: 392.9 kB
Release files / context_pilot_mcp-0.2.5.tar.gz
| Download URL | context_pilot_mcp-0.2.5.tar.gz |
|---|---|
| Size | 371.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c04a0b6c669fc88fde820c1d34fe25f50a609bb1b9cf79659376166c2711633d
|
|
BLAKE2b-256 checksum How to use checksums |
9aeed4cf71db6e07ce4d04b71af3727a4ed088c5b393cfcdc528cd747a77765a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Release files / context_pilot_mcp-0.2.5-py3-none-any.whl
| Download URL | context_pilot_mcp-0.2.5-py3-none-any.whl |
|---|---|
| Size | 21.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
792490be6f4348b4beffb22984febee113a549d2e7a86d96976b30a751ec576b
|
|
BLAKE2b-256 checksum How to use checksums |
daf992ed0ef0a92b427c746c4fc018fcabd7d4108d70fe64e2a9836a9ebf598d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Security for context-pilot-mcp 0.2.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.