Skip to main content

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

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)

Source distribution for context-pilot-mcp 0.2.5
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)

Table of built distributions (wheels) for context-pilot-mcp 0.2.5
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page