Quickstart

This is the current beta path for ContextPilot: build the local packages, run an isolated selftest, install the agent integrations, then use the CLI reports.

Prerequisites

  • Node.js 20 or newer.
  • npm from the repo root.
  • Claude Code for automatic Claude hook capture, and/or OpenAI Codex CLI for Codex session capture. You can install either, both, or neither — the worker and MCP server work standalone with manual contextpilot remember.

1. Build the packages

terminalbash
npm install
npm run build

2. Run the isolated smoke test

terminalbash
node packages/cli/dist/index.js selftest

The selftest starts a temporary worker and database, captures a sample read event, verifies dedupe, checks the savings report, and runs the project analyzer without touching your real data.

3. Install agent integrations

terminalbash
node packages/cli/dist/index.js install

This starts the worker, writes managed Claude Code hook wrappers, registers the MCP server in ~/.claude/mcp_servers.json, and launches the Codex CLI session watcher daemon. Existing user-owned hook and MCP files are backed up under ~/.contextpilot/backupsbefore ContextPilot writes managed files.

4. Verify the install

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

doctor checks build artifacts, worker health, Claude hook wrappers, MCP registration, and the Codex watcher daemon.

5. Use reports

terminalbash
node packages/cli/dist/index.js events
node packages/cli/dist/index.js savings
node packages/cli/dist/index.js analyze .

The worker runs on http://127.0.0.1:3848. The default database is ~/.contextpilot/contextpilot.db.

6. Add manual memories

terminalbash
node packages/cli/dist/index.js remember "Billing rule" "Tenant billing uses plan limits from subscriptions."
node packages/cli/dist/index.js search "billing rule"

Uninstall

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

The normal uninstall removes ContextPilot hooks, MCP registration, and local worker processes while preserving ~/.contextpilot. Use --delete-data only when you want to remove the local database too.

Next steps

  • Read the CLI reference for supported commands.
  • Read the agent-specific guides: Claude Code · Codex CLI.
  • Join the customer beta if you want paid-plan and license access.
  • Run doctor after changing Claude Code, Codex CLI, or rebuilding packages.
Next →InstallationCurrent beta install path