Installation

ContextPilot is currently a local beta. The production package flow will be npx contextpilot install. Today, install from this repository after building the packages.

System requirements

• Node.js 20 or newer.
• OS: tested on macOS during beta development.
• Disk: local SQLite database under ~/.contextpilot.
• Agents: Claude Code (native hooks) and/or OpenAI Codex CLI (session JSONL watcher). Both installations are auto-detected — see Claude Code and Codex CLI guides.

Local beta install

npm install
npm run build
node packages/cli/dist/index.js selftest
node packages/cli/dist/index.js install

What install changes

• Starts the local worker on 127.0.0.1:3848.
• Writes managed Claude Code hook wrappers under ~/.claude/hooks.
• Merges the ContextPilot MCP server into ~/.claude/mcp_servers.json.
• Starts the Codex CLI session watcher daemon. PID file at ~/.contextpilot/codex-watcher.pid; offsets persisted in ~/.contextpilot/codex-state.json.
• Backs up existing user-owned hook and MCP files before writing managed files.

Verify

node packages/cli/dist/index.js doctor
node packages/cli/dist/index.js status

Data location

The local state directory is ~/.contextpilot. The default database path is ~/.contextpilot/contextpilot.db. Set CONTEXTPILOT_DB=/path/to/db.sqlite before starting the worker if you need a different database location.

Uninstall

node packages/cli/dist/index.js uninstall
node packages/cli/dist/index.js uninstall --delete-data

Next steps

• Walk through the Quickstart.
• Review the supported CLI commands.
• Read the agent-specific guides: Claude Code · Codex CLI.
• Join the customer beta for paid license testing.