ctxpilot

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.

Demo story

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.

Install

npm install -g @ctxpilot/ctxpilot

One-off run:

npx @ctxpilot/ctxpilot init

Quickstart

ctx init
ctx setup
ctx watch

ctx init creates .ctxpilot/ and the first LCD. ctx setup wires MCP and native instruction files. ctx watch starts the background updater.

Provider setup

ctxpilot supports three providers. During ctx init you choose between free (local) and BYO API key.

Free (local) — Ollama

Data never leaves your machine. Requires Ollama.

# Install Ollama
brew install ollama        # macOS
# or: curl -fsSL https://ollama.com/install.sh | sh   # Linux

# Pull a model
ollama pull gemma3:4b

# Initialize ctxpilot and choose "Free (local)"
ctx init

Or configure manually in .env:

CK_PROVIDER=local
CK_MODEL=gemma3:4b
CK_LOCAL_URL=http://localhost:11434   # optional, this is the default

Anthropic or OpenAI — BYO API key

Set CK_PROVIDER and the matching API key in a project .env or ~/.ctxpilot/.env before ctx init.

CK_PROVIDER=anthropic
CK_API_KEY=your_key_here

CK_PROVIDER=openai
CK_OPENAI_API_KEY=your_key_here

Command reference

| 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> | Output the current LCD for prompts | Default format is markdown | | 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 |

How auto-update works

• ctx watch starts 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 update runs.
• .ctxpilot/ output files are ignored so updates do not trigger themselves.

MCP setup

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.

Support

If ctxpilot saves you time, consider supporting development:

• Ko-fi
• GitHub Sponsors

Contributing

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.