ctxpilot is a CLI and MCP server that keeps a living project summary in .ctxpilot/context.md. It updates that summary from your repo and gives the same starting context to Claude Code, Codex CLI, Cursor, and Windsurf.
Open a fresh Codex session and ask about a cart bug. With ctxpilot set up, Codex can answer about cart.ts line numbers cold because it already read the LCD and has the project MCP tools available.
npm install -g @ctxpilot/ctxpilotSet CK_PROVIDER and the matching API key in a project .env or ~/.ctxpilot/.env before ctx init.
One-off run:
npx @ctxpilot/ctxpilot initctx init
ctx setup
ctx watchctx init creates .ctxpilot/ and the first LCD. ctx setup wires MCP and native instruction files. ctx watch starts the background updater.
| Command | What it does | Notes |
|---|---|---|
ctx init |
Create .ctxpilot/ and build the first LCD |
Prompts for provider, goal, stack, and preferences |
ctx setup |
Write MCP config for installed clients and project instruction files | Supports Claude Code, Codex CLI, Cursor, and Windsurf |
ctx watch [--since <timeframe>] |
Start the background watcher | Runs ctx update after changes |
ctx update [--since <timeframe>] |
Run one incremental update now | --since accepts 2h, 1d, 1w, or an ISO date |
ctx build |
Rebuild the LCD from the current repo state | Archives the previous LCD |
ctx show [--raw] [--json] |
Print the current LCD | --raw prints markdown, --json prints metadata and content |
| `ctx inject --format <markdown | xml | plaintext>` |
ctx signal <text> |
Add a manual signal for the next update | Writes to .ctxpilot/signals.json |
ctx serve |
Start the MCP server for the current project | Used by MCP client configs |
ctx watchstarts a daemon and writes.ctxpilot/daemon.pid.- The daemon watches project files,
.git/refs/heads, and.ctxpilot/signals.json. - Changes are debounced for 30 seconds, then
ctx updateruns. .ctxpilot/output files are ignored so updates do not trigger themselves.
Run ctx setup inside the project you want to expose. It writes a project MCP server name like ctx-my-project.
| Client | Home config written by ctx setup |
Project file written by ctx setup |
|---|---|---|
| Claude Code | ~/.claude/claude_desktop_config.json |
CLAUDE.md |
| Codex CLI | ~/.codex/config.toml |
.agents/skills/ctxpilot/SKILL.md |
| Cursor | ~/.cursor/mcp.json |
.cursor/rules/ctxpilot.mdc |
| Windsurf | ~/.windsurf/mcp.json |
.windsurf/rules/ctxpilot.md |
If a client directory is not installed, ctx setup skips its home config. CLAUDE.md is always managed because it is a plain project file.
If ctxpilot saves you time, consider supporting development:
ctxpilot is open source and PRs are welcome. See CONTRIBUTING.md for local setup and contribution rules, and docs/MASTERPLAN.md for the full roadmap.