Metadata-Version: 2.4
Name: context-pilot-mcp
Version: 0.2.5
Summary: Universal context manager for AI coding agents
Author-email: Samito <sanyam.ahuja.alwar@gmail.com>
License: MIT
Keywords: ai,claude,context,llm,mcp
Requires-Python: >=3.11
Requires-Dist: mcp>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tree-sitter-go
Requires-Dist: tree-sitter-javascript
Requires-Dist: tree-sitter-python
Requires-Dist: tree-sitter-typescript
Requires-Dist: tree-sitter>=0.21.0
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# 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

```bash
pip install context-pilot-mcp
```

---

## Connecting to Your Agent

### Claude Code
```bash
# 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`):

```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`
```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:

```toml
[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
