Context Pilot

An MCP server that keeps AI coding agents always up to date with your project context. Agents discover the tools natively — no system prompt instructions needed.

Install

npm install -g @archia/context-pilot
# or run directly without installing:
npx @archia/context-pilot <command>

Quick Start

cd your-project
npx @archia/context-pilot init           # interactive setup
npx @archia/context-pilot start --goal "Fix login bug"   # start a session

Then add the printed MCP config to your agent (Claude Code, Cursor, Cline, Windsurf). From that point, your agent will automatically call get_briefing at the start of each step and log_action after every action — no system prompt required.

CLI Commands

| Command | Description | |---------|-------------| | init | Interactive project setup wizard | | start --goal <text> | Start a new session | | briefing | Print the current context briefing | | end | End the active session with summary | | pause | Pause the active session | | resume | Resume a paused session | | compress | Manually compress the current snapshot | | dashboard | Open the browser dashboard | | mcp-config | Print MCP config snippet for your agent | | serve | Start the MCP server (PROJECT_ID env required) |

Session lifecycle

init ──► start ──► (briefing / agent loop) ──► end
                      │
                   pause ──► resume

Start a session, work with your agent (it reads briefing + logs actions automatically via MCP), then end the session to get a summary.

MCP Tools

Once you add Context Pilot to your agent's MCP config, the agent discovers these 4 tools natively:

| Tool | When to call | What it returns | |------|-------------|-----------------| | get_briefing | Start of every step | Current context: project info, session goal, active task, decisions, file map | | log_action | After every action | Step number, snapshot update status, tokens used | | update_task | Subtask done or blocker hit | Updated snapshot version and tokens used | | get_status | Health check / metrics | Session status, progress, last 10 log entries |

The agent calls these automatically based on its judgment — no instructions needed in your system prompt.

Dashboard

npx @archia/context-pilot dashboard
# Opens at http://localhost:3456

Four panels in a dark-theme browser UI:

• Metrics bar — token usage progress bar (green/amber/red thresholds), steps taken, files touched, snapshot version
• Active task — session goal, subtask list with Mark Done buttons, blockers, open questions
• Context breakdown — token usage per section (foundation, task, decisions, file map) with Compress button
• Activity log — last 20 entries with type badges, live auto-updates via SSE

Configuration

Context Pilot stores everything in ~/.contextpilot/{projectId}/store.json — a single JSON file you can inspect and edit directly.

Project fields

| Field | Type | Description | |-------|------|-------------| | name | string | Human-readable project name | | root_path | string | Absolute path to project root | | stack | string[] | Technology stack (e.g. node, express, postgres) | | commands.test | string | Command to run tests | | commands.run | string | Command to run the project | | commands.build | string? | Optional build command | | commands.lint | string? | Optional lint command | | key_paths | object | Named shortcuts to important directories | | off_limits | string[] | Paths the AI must never touch | | conventions | string[] | Coding conventions as plain strings |

Architecture

src/
├── types.ts          # All TypeScript types
├── store.ts          # JSON file store CRUD
├── renderer.ts       # Briefing string builder + token estimator
├── engine.ts         # Snapshot trigger logic, log processing
├── session.ts        # Session lifecycle (create, end, pause, resume)
├── mcp.ts            # MCP server with 4 tools
├── compressor.ts     # Snapshot compression
├── watcher.ts        # File system watcher safety net
├── dashboard/
│   ├── server.ts     # HTTP + SSE server (port 3456)
│   └── ui.html       # Vanilla HTML/CSS/JS dashboard
└── index.ts          # CLI entry point

The store is a single JSON file — no database, no ORM. Every session writes append-only log entries and versioned context snapshots.

Snapshot triggers

A new context snapshot is created when:

• A subtask changes to done or blocked → milestone
• Token usage crosses 50%, 70%, or 85% of budget → budget_threshold
• At 85%, compression runs automatically before the snapshot
• Manual via CLI (compress) or dashboard button → manual

License

MIT