Codex Setup

AgentKeeper integrates with Codex through the official Codex hook system. The public installer uses the current hooks feature flag and wires the six documented lifecycle events that matter for...

AgentKeeper integrates with Codex through the official Codex hook system. The public installer uses the current hooks feature flag and wires the six documented lifecycle events that matter for runtime governance: SessionStart, PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, and Stop.

Codex now supports documented blocking for pre-tool, permission, prompt, and stop events. Parity still means documented hook and managed-configuration parity, not OS-level interception: post-tool hooks can replace feedback but cannot undo an already-completed command.

Use Policy outcomes for the shared Monitor, Warn, and Block model; this page lists what the Codex surface can actually support.

What gets monitored

Surface	Outcome support
Shell commands (`Bash`)	Block or Warn before execution
File writes and patches (`apply_patch`)	Block or Warn before execution
Prompts (`UserPromptSubmit`)	Block or show advisory context before the prompt is processed
Permission requests (`PermissionRequest`)	Allow, ask, or deny when Codex asks for permission
MCP tool calls (`mcp__server__tool`)	Block, Warn, allow-list, or Audit only before execution
Web fetch/search	Can block when Codex emits the tool event
Session and stop lifecycle	Session check-in, audit context, and stop-time validation

Installation

Get your API key from Settings > Access > API keys, then run the public installer:

export AGENTKEEPER_API_URL="https://www.agentkeeper.dev"
export AGENTKEEPER_API_KEY="ak_live_..."
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide codex

The installer stores the API key in ~/.agentkeeper/config, installs ~/.agentkeeper/hooks/codex/agentkeeper-hook.sh, and updates ~/.codex/config.toml.

Generated config

[features]
hooks = true

[[hooks.SessionStart]]
matcher = "startup|resume|clear"

[[hooks.SessionStart.hooks]]
type = "command"
command = "bash "/Users/YOU/.agentkeeper/hooks/codex/agentkeeper-hook.sh""
timeout = 12

[[hooks.PreToolUse]]
matcher = "*"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "bash "/Users/YOU/.agentkeeper/hooks/codex/agentkeeper-hook.sh""
timeout = 12

[[hooks.PermissionRequest]]
matcher = "*"

[[hooks.PermissionRequest.hooks]]
type = "command"
command = "bash "/Users/YOU/.agentkeeper/hooks/codex/agentkeeper-hook.sh""
timeout = 12

[[hooks.PostToolUse]]
matcher = "*"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "bash "/Users/YOU/.agentkeeper/hooks/codex/agentkeeper-hook.sh""
timeout = 12

[[hooks.UserPromptSubmit]]
matcher = "*"

[[hooks.UserPromptSubmit.hooks]]
type = "command"
command = "bash "/Users/YOU/.agentkeeper/hooks/codex/agentkeeper-hook.sh""
timeout = 12

[[hooks.Stop]]
matcher = "*"

[[hooks.Stop.hooks]]
type = "command"
command = "bash "/Users/YOU/.agentkeeper/hooks/codex/agentkeeper-hook.sh""
timeout = 12

The installer writes the command with the user's expanded home directory, for example bash "/Users/alice/.agentkeeper/hooks/codex/agentkeeper-hook.sh". Codex reads hooks from the user-level config above. For managed rollout, deploy managed hooks in requirements.toml and pin [features].hooks = true so users cannot locally disable the managed layer.

Tool name mapping

Codex tool name	AgentKeeper canonical name
`Bash`	`Bash`
`read_file`	`Read`
`write_file`	`Write`
`apply_patch`	`Edit`
`grep`, `search`	`Grep`
`glob`, `list_files`	`Glob`
`web_fetch`	`WebFetch`
`mcp__server__tool`	MCP skill policy

Verify coverage

Open the project in Codex after installing hooks.
Ask Codex to run ls.
Check Activity for a codex event.
Go to Team → Policies → Access Control to disable or re-enable org-wide Codex access.
Run explicit Bash, apply_patch, MCP, prompt-block, and stop-validation tests in the customer's Codex version and confirm the events appear in Activity before rollout.

Notes

Codex hooks are fail-open by design. If AgentKeeper is unreachable, the adapter returns allow so developers are not blocked by local network or dashboard outages. Codex hooks use the canonical hooks feature flag; codex_hooks is only a deprecated alias. Workstations register on the first Codex event that reaches AgentKeeper, and SessionStart gives setup health a lifecycle signal when Codex emits it.

For cross-IDE claims, see IDE runtime parity.

Was this page helpful?