Skip to main content

Code review hooks for Codex and Claude Code

Configure and verify the distributed CodeGraph hook runtimes for Codex and Claude Code, including lifecycle events and blocking boundaries.

User Guides

CodeGraph supplies separate hook adapters for Codex and Claude Code. Both can enrich a session and inspect tool activity, but their registration files and supported events are different. Treat the checked-in registration file as the contract; do not infer support from a similarly named Python module.

Choose the correct adapter

Choose the correct adapter
Client Authoritative registration Runtime implementation When to use it
Codex plugins/codegraph/hooks/hooks.json plugins/codegraph/hooks/runtime/ through plugins/codegraph/bin/codegraph_codex_hook.py The CodeGraph Codex plugin is installed and the client loads its native plugin hooks.
Claude Code .claude/settings.json .claude/hooks/ The repository is opened in Claude Code and repository-local hooks are allowed.

The adapters are not interchangeable. A .claude/hooks/ file does not register a Codex event, and a Codex plugin cache must not be edited as if it were repository source.

Codex lifecycle

The current Codex registration declares these events:

Codex lifecycle
Event Purpose Typical boundary
SessionStart Resolve project and session context before normal work. Bounded diagnostic or context enrichment.
UserPromptSubmit Add current CodeGraph context to the submitted task. Context may degrade with an explicit diagnostic.
PreToolUse Evaluate tool-use and governed financial policies before execution. Policy and authorization decisions are fail-closed.
PostToolUse Capture Bash outcomes and bounded telemetry after execution. Reporting is normally fail-open; it cannot retroactively authorize a command.
SubagentStart / SubagentStop Bind and finalize delegated execution context. Evidence collection follows the active carrier.
PreCompact Capture bounded memory before context compaction. The configured compact barrier decides whether a failure blocks.
Stop Emit diagnostics, memory, and completion-guard evidence. Stop itself is intentionally non-blocking; authoritative SDLC gates decide closure.

The registration also defines per-event timeouts. A timeout records an operational limit; the associated product task is evaluated by the review and acceptance evidence.

Claude Code lifecycle

The repository-local .claude/settings.json registers SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, and Stop handlers from .claude/hooks/.

The shared review-pipeline policy defaults to fail-closed for a hook error that could hide a required check. An operator may enable review_pipeline.fail_open only as an explicit configuration decision. That exception keeps work recoverable and remains visible in diagnostics; missing review evidence stays in its own status.

Failure model

  • Use fail-closed for authorization, destructive tool-use policy, required approval, and completion/financial gates.
  • Use fail-open only for bounded enrichment or telemetry where losing the optional context is safer than blocking the whole client.
  • Never interpret hook exit success as acceptance evidence for a Story, task, or release.
  • Never place secrets, raw provider tokens, or unrestricted source payloads in hook diagnostics.
  • Keep timeouts bounded and return an actionable recovery message naming the failed stage.

Verify Codex hooks

  1. Open plugins/codegraph/hooks/hooks.json and confirm that the event you need is registered.
  2. Confirm that the command points to ${PLUGIN_ROOT}/bin/codegraph_codex_hook.py (or its Windows form) and that the runtime file exists.
  3. Start a fresh client session after installing or updating the plugin. A source checkout change alone does not update an already installed plugin cache.
  4. Trigger the smallest relevant event and inspect its structured diagnostic. Use the hook check to verify wiring and the product acceptance test to verify the product task.
  5. If a governed operation is denied, fix the named scope, permission, approval, or carrier issue instead of bypassing PreToolUse.

Verify Claude Code hooks

  1. Confirm that .claude/settings.json registers the event and points to an existing file under .claude/hooks/.
  2. Run the hook with a minimal JSON fixture through standard input.
  3. Check that invalid or missing project context produces an actionable diagnostic.
  4. Review review_pipeline.fail_open before diagnosing different behavior across workstations.

Troubleshooting

Troubleshooting
Symptom Check Recovery
Event never runs Registration file, installed plugin version, client restart Reinstall/update the adapter and start a new session.
Wrong project is selected Project detector and session cache Clear only the adapter’s documented cache and retry discovery.
PreToolUse denies a command Permission, approval, carrier, and destructive-command policy Correct the governing input; do not convert the denial to fail-open.
Enrichment times out MCP/runtime health and event timeout Continue with the emitted degraded-state diagnostic or restore the service.
Hook ran but review is missing Review command and acceptance evidence Run the canonical review workflow and record its result.

Source references

  • plugins/codegraph/hooks/hooks.json
  • plugins/codegraph/hooks/runtime/
  • plugins/codegraph/bin/codegraph_codex_hook.py
  • .claude/settings.json
  • .claude/hooks/

For the review workflow itself, see Code Review and Scenario 09.

Report a documentation issue