Hooks

Hooks are how ContextPilot captures local coding-agent activity. Two agents are wired automatically in v1: Claude Code via native hook wrappers, and OpenAI Codex CLI via a session-log watcher daemon. Both produce the same normalized event shape on the local worker at http://127.0.0.1:3848.

Pipelines

claude

Claude Code tool event
    ↓
managed wrapper in ~/.claude/hooks
    ↓
POST /api/hook or /api/hooks/batch
    ↓
worker extracts compact memory
    ↓
SQLite write + dedupe + ingest audit
    ↓
searchable by CLI and MCP

codex

Codex writes JSONL to ~/.codex/sessions/...
    ↓
codex-watcher daemon tails new lines
    ↓
pairs function_call + function_call_output by call_id
    ↓
POST /api/hook
    ↓
worker extracts compact memory
    ↓
same SQLite + dedupe path as Claude

What the beta captures

File reads: path, content hash, and estimated token weight without storing the full source body.
File edits: compact edit summary when the hook event includes enough diff context.
Commands: command metadata, exit code, and compact output summaries.
Session end: session lifecycle and savings aggregation metadata.
Manual notes: memories created by contextpilot remember or MCP.

Install and verify

terminalbash

contextpilot install
contextpilot doctor
contextpilot events

doctor checks that the hook build artifacts exist, the managed wrappers are installed and executable, and Claude MCP registration points at the built server.

Hook event schema

The worker accepts one event at POST /api/hook or many at POST /api/hooks/batch.

kind·"tool_use" | "session_start" | "session_end" | "manual"required

The event type. This chooses the extractor path.

agent·"claude" | "codex" | "manual" | "unknown"required

The agent name. Claude Code hooks emit "claude"; the Codex watcher emits "codex". Custom integrations may use "manual".

projectRoot·stringrequired

Absolute path to the project root.

timestamp·numberrequired

Unix epoch milliseconds.

sessionId·string

Optional ID used to group events into a session.

toolName·string

For tool events, the tool name from the agent.

input·unknown

Tool input as JSON. File paths and command strings are extracted from here.

output·string

Optional tool output. The worker stores compact summaries, not raw source dumps.

Custom events

If you are testing another agent, post matching events directly:

custom-hook.shbash

curl -s -X POST http://127.0.0.1:3848/api/hook \
  -H 'content-type: application/json' \
  -d '{
    "kind": "manual",
    "agent": "custom",
    "projectRoot": "'$PWD'",
    "title": "Important project rule",
    "content": "Keep tenant billing checks server-side.",
    "timestamp": 1716422400000
  }'

Debugging

terminalbash

contextpilot doctor
contextpilot events --limit 20
contextpilot savings

If Claude Code events stay empty, restart Claude Code so it reloads hook configuration, then run doctor again. If Codex events are missing, confirm the Codex watcher daemon is running in doctor output. Agent-specific troubleshooting lives in the integration pages linked above.

← PreviousConfigurationConfig file and env vars Next →MCPFour tools your agent can call