Claude Code integration

Claude Code is the deepest integration in v1. The installer writes managed hook wrappers, registers the ContextPilot MCP server, and starts the local worker — repeated file reads, edits, and commands are captured with no manual config.

What install writes

• ~/.claude/hooks/PostToolUse.js — managed wrapper that POSTs every tool event to the local worker.
• ~/.claude/hooks/Stop.js — managed wrapper that emits a session_end event when Claude Code exits.
• ~/.claude/mcp_servers.json — the ContextPilot MCP server is merged into the existing config (your other MCP servers are preserved).
• Any pre-existing user-owned files at those paths are backed up to ~/.contextpilot/backups before being replaced.

Event flow

Claude Code tool call
    ↓
~/.claude/hooks/PostToolUse.js  (50ms timeout, fire-and-forget)
    ↓
POST http://127.0.0.1:3848/api/hook
    ↓
worker extracts compact memory + dedup
    ↓
SQLite at ~/.contextpilot/contextpilot.db
    ↓
searchable via CLI and MCP

What gets captured

• Read → memory of type: "file_read"; repeated reads of the same content dedup and increment reuse_count.
• Edit / Write → memory of type: "file_edit" with a compact diff summary.
• Bash → memory of type: "command_success" or "command_failure"; test runners (vitest, jest, pytest, etc.) produce test_pass / test_fail memories instead.
• Session end → closes the session row and finalizes savings aggregation.

Install and verify

contextpilot install
contextpilot doctor

doctor reports the status of the engine, hooks, MCP server, and watcher. Look for the rows beginning with Claude PostToolUse hook installed, Claude Stop hook installed, Claude hooks executable, and Claude MCP config.

MCP tools available to Claude

• contextpilot_search — compact ranked results; the recommended first call before re-reading files.
• contextpilot_get — fetch the full memory body for an ID returned by search.
• contextpilot_remember — store a durable memory for the current project.
• contextpilot_status — savings, ingestion, and ContextPilot health.
• contextpilot_auto — when the model for a task is unclear, Claude can ask the picker which model is most cost-effective. Returns the model id, tier, estimated cost, and the exact command to run.

Model selection

Claude Code picks its model from your Anthropic API configuration or the --model flag. The hook wrappers record whichever model is in use; ContextPilot uses that ID for per-session cost reporting.

# One-off invocation with a specific model
claude --model opus "design the new billing service"

# Aliases supported by the Claude Code CLI:
#   opus    → claude-opus-4-7  (latest)
#   sonnet  → claude-sonnet-4-6
#   haiku   → claude-haiku-4-5

# Use the long form for a pinned snapshot
claude --model claude-opus-4-7 "..."

Anthropic pricing for current Claude 4.x models, sourced from platform.claude.com/docs/en/about-claude/pricing. All values are USD per million tokens. Cached read is the prompt-caching hit price (10% of input).

Auto model selection

contextpilot auto picks the cheapest model that can handle the task and prints the exact CLI command. Use --provider claude to keep the pick inside Anthropic. The CLI confirms before printing the command so nothing runs without your approval.

contextpilot auto "find why /api/session 500s on expired tokens" --provider claude

# Output (paraphrased):
# Model : Claude Sonnet 4.6  (claude-sonnet-4-6)
# Tier  : BALANCED (anthropic)
# Why   : bug fix, file reference src/server/auth.ts
# Run?  [Y/n]
#
# claude --model sonnet "find why /api/session 500s on expired tokens"

See the MCP reference for the full tool schemas.

Hook event schema

The Claude hook wrappers normalize Claude Code’s payload into the worker’s event format. If you want to test or build a custom integration, see the Hooks page for the full schema and the POST /api/hook contract.

Troubleshooting

• No events appearing — restart Claude Code after install so it reloads hook configuration, then run contextpilot doctor.
• Hooks not executable — re-run contextpilot install; the installer marks the wrapper files 0o755.
• MCP not visible — verify ~/.claude/mcp_servers.json contains a contextpilot entry, and restart Claude Code.
• Worker unreachable — contextpilot status hits /api/health; if it fails, contextpilot start brings the worker back up.

Uninstall

contextpilot uninstall stops the worker and Codex watcher; removes the managed Claude hook wrappers; and unmerges the ContextPilot MCP entry. Any user-owned files that were backed up at install stay in ~/.contextpilot/backups.