OpenAI Codex CLI integration

Codex CLI is supported through a background session watcher: a small Node daemon that tails the JSONL session logs Codex writes locally and forwards normalized events to the ContextPilot worker. No Codex config changes are required.

What install starts

• A long-running daemon at packages/hooks/dist/codex/watcher.js, launched by contextpilot install and tracked via PID file at ~/.contextpilot/codex-watcher.pid.
• Per-file read offsets persisted in ~/.contextpilot/codex-state.json so restarts resume cleanly.

Event flow

Codex CLI session
    ↓ writes JSONL
~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
    ↓ tail + parse (2s poll)
codex-watcher daemon
    ↓ normalizes call/output pairs
POST http://127.0.0.1:3848/api/hook
    ↓
worker extracts compact memory + dedup
    ↓
SQLite at ~/.contextpilot/contextpilot.db

What gets captured

Codex emits each tool call as a response_item entry, followed later by a matching output entry keyed by call_id. The watcher pairs them and emits a single tool_use event.

• exec_command (shell) → tool_use with toolName: "Bash", input { command, cwd }, output snippet, inferred exit code.
• apply_patch (file edits) → tool_use with toolName: "Edit", file path parsed from the patch header, and a compact diff snippet.
• session_meta (start of a session file) → captured as context (sessionId, projectRoot, model) and stamped on every subsequent event.
• idle > 60s → the watcher emits a session_end event for that file and stops tracking it until it grows again.

What is ignored

The watcher skips Codex internal calls that aren’t useful as memories:

• update_plan — planning state, not work product.
• view_image — image attachments.
• list_mcp_resources, list_mcp_resource_templates — directory listings.
• write_stdin — interactive stdin passthrough.
• message, reasoning, web_search_call — model output, not tool work.

File layout

~/.codex/sessions/                       # Codex writes here
  YYYY/MM/DD/rollout-*-{uuid}.jsonl      # one file per session

~/.contextpilot/codex-state.json         # watcher's per-file byte offsets
~/.contextpilot/codex-watcher.pid        # daemon PID

Install and verify

contextpilot install
contextpilot doctor

In doctor output, look for the rows Codex watcher build artifact and Codex watcher running.

Manual control

# Stop only the Codex watcher (keeps worker running)
kill $(cat ~/.contextpilot/codex-watcher.pid)

# Restart the watcher and worker the easy way
contextpilot stop
contextpilot install

Environment

• CODEX_HOME — override the Codex state directory (default ~/.codex).
• CONTEXTPILOT_WORKER_URL — override the worker URL (default http://127.0.0.1:3848).

Model selection

Codex CLI picks its model from ~/.codex/config.toml or the -m / -c model="..." flag. The watcher captures whichever model Codex writes in the session metadata; ContextPilot uses that ID when reporting per-session cost.

# One-off invocation with a specific model
codex -m gpt-5.5 "refactor the billing service"

# Persistent default in ~/.codex/config.toml
# model = "gpt-5.4"

# Inspect the active configuration
codex doctor

OpenAI pricing for models commonly used with Codex CLI, current as of the latest pricing snapshot from developers.openai.com/api/docs/pricing. All values are USD per million tokens.

Auto model selection

contextpilot auto scores the prompt and picks the cheapest OpenAI model that can handle the task. Use --provider openai to keep the pick inside OpenAI. The CLI shows the recommendation, the reasoning, and the estimated cost; nothing executes until you approve.

contextpilot auto "refactor the billing service" --provider openai

# Output (paraphrased):
# Model : GPT-5.4  (gpt-5-4)
# Tier  : BALANCED (openai)
# Why   : refactor
# Run?  [Y/n]
#
# codex -m gpt-5.4 "refactor the billing service"

From inside Codex CLI or any MCP-aware agent, the same picker is available as the contextpilot_auto tool — useful when the agent has to decide between sub-tasks of different complexity.

Privacy

The watcher only reads from your Codex JSONL files; it never modifies them. Captured memory bodies follow the same secret-scanning and ignore-list rules as Claude events — see Hooks for the engine’s redaction behavior. Nothing leaves your machine.

Troubleshooting

• No Codex events appearing — confirm ~/.codex/sessions/ exists and contains a recent .jsonl. The watcher only scans the 32 most-recent files.
• Watcher not running — contextpilot doctor reports the PID status. Run contextpilot install to relaunch it.
• Offsets desynced after manual file edits — delete ~/.contextpilot/codex-state.json and restart the watcher; it will re-tail from byte 0 of each file, dedup will handle the replay.