Code review hooks for Codex and Claude Code

Hooks connect CodeGraph to a Codex or Claude Code session. They add project context to prompts, check permissions before a tool runs, and capture results afterward. Developers can use that context to understand why an operation proceeds or stops.

Choose the adapter for your client. Each adapter has its own registration file and set of events. Check that file to see which handlers the current version runs.

Choose the correct adapter

For Codex, use the hooks supplied by the installed CodeGraph plugin. Start a fresh client session after updating the plugin. For Claude Code, check the registration in .claude/settings.json and the handler paths in your checkout.

Prepare verification

Open PowerShell at the CodeGraph source repository root. You need Python and the project dependencies. Actual hook execution also requires the corresponding client, a loaded adapter, and an available CodeGraph runtime. See the MCP operator guide for connection setup.

Check registration without executing handlers:

$codexHooks = Get-Content -Raw 'plugins/codegraph/hooks/hooks.json' | ConvertFrom-Json
$claudeHooks = Get-Content -Raw '.claude/settings.json' | ConvertFrom-Json
$codexHooks.hooks.PSObject.Properties.Name
$claudeHooks.hooks.PSObject.Properties.Name
Test-Path -LiteralPath 'plugins/codegraph/bin/codegraph_codex_hook.py'

Expect eight Codex events, five Claude Code events, and True for the dispatcher file. This confirms source registration. Next, verify that the client loads the hooks using the sections below. The local .claude/settings.json uses absolute workspace paths. Verify each path before using another checkout; adapt the registration instead of copying those paths unchanged.

Codex lifecycle

The current Codex registration declares these events:

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/.

Shared hook utilities read review_pipeline.fail_open directly from config.yaml. With true, the error handler returns an empty response. With false, it returns Hook Error: BLOCK with an error code and a recommended action. An absent setting or a configuration-read failure yields false. The current repository configuration and ReviewPipelineConfig model specify true. Check the value in your checkout and the handler for the relevant event. This setting controls error handling. The tool-use policy checks authorization; the review report and its artifacts establish the review result.

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.
• A hook exit code records its execution result. Keep the review report and related artifacts for task or release acceptance.
• 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. In the client, perform an authorized action that triggers the relevant event.
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

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.