Do More Than Use Codex: Hooks Are the Advanced Move

Many people use Codex mainly to write code, edit files, and run commands. That is the most visible part of Codex, but stopping there means missing one of its most useful advanced features: Hook.

The value of a Hook is not that it makes Codex better at writing code. It makes Codex follow rules more consistently. Hooks can run custom scripts at key lifecycle events, such as before a user prompt is submitted, before or after tool calls, when permissions are requested, or when a turn stops. This lets you put team policies, security checks, privacy protection, and automatic logging into the Codex workflow instead of relying on manual reminders every time.

A typical example is privacy checking. Before a prompt is sent to Codex, a Hook can scan it for API keys, tokens, private keys, phone numbers, internal addresses, or other sensitive information. If a rule matches, the Hook can block the submission or show a clear warning so the user can clean the content first.

What a Hook is

A Codex Hook is a lifecycle handler inside the Codex workflow. It fires when a configured event occurs and receives the current context as JSON on standard input. The script can return warning text, add context, or block later actions for some events.

Official documentation lists examples such as:

• sending conversations to a custom logging or analytics system;
• scanning team prompts to prevent accidental API key leaks;
• summarizing conversations to create persistent memories;
• running custom validation when a conversation turn stops;
• adding directory-specific context or rules.

So a Hook is closer to a workflow control layer and safety guardrail than a prompt trick. A prompt tells Codex what it should do; a Hook inserts checks, logging, and constraints before or after Codex acts.

Where Hooks live

Codex can load Hooks from hooks.json or from inline [hooks] tables in config.toml. The four most common locations are:

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

User-level Hooks are good for personal rules, such as “do not send suspected secrets” or “summarize at the end of each session.” Project-level Hooks are better for repository conventions, such as “do not edit generated directories,” “check front matter before committing,” or “block risky commands before execution.”

Project-local .codex/ configuration is loaded only after the project layer is trusted. User-level Hooks do not depend on project trust. This matters because project Hooks execute local scripts, so unknown repositories should not be trusted automatically.

Common trigger points

Hooks have multiple trigger points. Different events fit different jobs.

UserPromptSubmit runs before a user prompt is submitted. It is useful for privacy checks, sensitive-word checks, and prompt policy checks. For example, if the prompt appears to contain a key starting with sk-, the Hook can block the submission.

PreToolUse runs before Codex calls a tool. It is useful for blocking commands, file writes, or MCP tool calls. For example, it can detect rm -rf, writes to system directories, or attempts to read sensitive paths, then return a denial reason.

PermissionRequest runs when Codex is about to request permission. It can automatically allow or deny clearly defined requests. A team might allow fixed test commands while denying access to certain directories.

PostToolUse runs after a tool has finished. It is useful for reviewing command output, scanning generated files, or reminding Codex of next steps. It cannot undo side effects that already happened, but it can provide feedback before Codex continues.

SessionStart runs when a session starts or resumes. It can load project conventions, team rules, common context, or local notes.

Stop runs when a turn is about to stop. It is useful for final checks, such as whether tests were run, whether TODOs remain, or whether one more verification pass is needed.

Designing a privacy-check Hook

Privacy checks fit naturally in UserPromptSubmit, because this event fires before user content enters the Codex workflow. Do not try to solve every case at once. Start with the kinds of content people most often paste by mistake.

Useful first rules include:

• OpenAI, GitHub, and cloud-provider API keys;
• private key blocks such as -----BEGIN PRIVATE KEY-----;
• .env file fragments;
• access tokens, Bearer tokens, and JWTs;
• internal domains and database connection strings;
• personal information such as ID numbers, phone numbers, and email addresses.

The Hook script receives JSON, reads the prompt field, and scans it with regular expressions or a rules table. If it finds a problem, it can block the submission:

1
2
3
4

{
  "decision": "block",
  "reason": "A suspected API key was detected. Remove sensitive information before submitting."
}

It can also return additional context without blocking, but for high-risk content such as secrets, private keys, and tokens, blocking is usually the safer default.

hooks.json example

For a repository-level configuration, create .codex/hooks.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python .codex/hooks/privacy_check.py",
            "timeout": 10,
            "statusMessage": "Checking prompt privacy"
          }
        ]
      }
    ]
  }
}

The matching script can read JSON from standard input:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

import json
import re
import sys

payload = json.load(sys.stdin)
prompt = payload.get("prompt", "")

patterns = [
    r"sk-[A-Za-z0-9_-]{20,}",
    r"ghp_[A-Za-z0-9_]{20,}",
    r"-----BEGIN [A-Z ]*PRIVATE KEY-----",
    r"Bearer\s+[A-Za-z0-9._-]{20,}",
]

for pattern in patterns:
    if re.search(pattern, prompt):
        print(json.dumps({
            "decision": "block",
            "reason": "A suspected secret, token, or private key was detected. Remove sensitive information first."
        }, ensure_ascii=False))
        raise SystemExit(0)

This example is only a starting point. In real use, keep the rules maintainable and tune false positives. A documentation example containing Bearer is not necessarily a leak, and a project may contain deliberately fake keys for tests. Strict rules catch more but may block too much; loose rules are easier to use but may miss real risks.

Inline config.toml form

If you do not want a separate hooks.json, you can define Hooks inside config.toml. Inline TOML Hooks use the same event structure as hooks.json:

1
2
3
4
5
6
7
8

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = 'python ".codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

If the same config layer contains both hooks.json and inline [hooks], Codex loads both and warns. In practice, choose one style per layer so rules are easier to audit.

Things to watch out for

First, Hooks run local commands, so the source must be reviewed. Non-managed Hooks need review and trust before they run. When the Hook definition changes, it needs to be trusted again. Do not casually allow .codex/hooks.json from an unfamiliar repository.

Second, multiple matching Hooks may run. Do not assume one Hook blocks everything, and avoid conflicting rules. In team environments, make it clear which rules are user-level, project-level, or admin-managed.

Third, Hooks are guardrails, not a complete security boundary. For example, PreToolUse can block many tool calls, but official documentation notes that it does not intercept every shell path or every non-shell, non-MCP tool. High-risk workflows still need permissions, sandboxing, code review, and least privilege.

Fourth, Hook scripts should be fast. Privacy scans and command reviews sit in the interaction loop. If a script takes tens of seconds on every run, the user experience will suffer. Use simple rules when simple rules are enough, and avoid calling heavyweight external services on every event.

Fifth, output format matters. Different events support different return fields. UserPromptSubmit can use decision: "block" to block a prompt, while PreToolUse has its own hookSpecificOutput shape. Check the input and output contract for the event before writing the Hook.

Good first Hook scenarios

If you are just starting, do not build a complex enterprise policy system immediately. Start with three small scenarios.

The first is privacy checking. It brings real value quickly and works for individuals and teams. Accidentally pasting secrets, tokens, or .env fragments is a realistic risk in AI coding workflows.

The second is risky-command blocking. A PreToolUse Hook for Bash can block recursive deletion, writes to system directories, or uploads to unknown remotes.

The third is final validation. A Stop or PostToolUse Hook can remind Codex to check tests, builds, formatting, docs, and uncommitted changes before finishing. These Hooks do not always need to block; even a reminder can reduce unfinished work.

Conclusion

Codex Hooks are not just another feature. They connect rules to the Codex execution loop.

In basic use, you tell Codex what to do with a prompt. In advanced use, Hooks check whether Codex is following the rules at key points. Privacy checks, command review, permission policy, session summaries, and final validation can move from manual reminders into executable workflow.

If you already use Codex in real projects, Hooks are worth configuring early. They do not replace human judgment, sandboxing, or permission control, but they can turn easy-to-forget safety and process requirements into default actions that run every time.

References: OpenAI Codex Advanced Configuration - Hooks, OpenAI Codex Hooks