OpenAI Codex release notes: 0.148 alpha runs hooks asynchronously

OpenAI Codex 0.148.0-alpha.6 can run command hooks asynchronously. Set async = true on a hook handler, and Codex runs the script in the background instead of letting it control the operation that launched it. The alpha was published on August 10. npm's stable channel remains on 0.147.0.

A hook is a script that Codex starts at a defined event, such as after a Bash command. Asynchronous execution means the hook can work in the background while the agent's main flow continues.

OpenAI Codex release notes: asynchronous hooks in 0.148 alpha

A hook could previously be marked as asynchronous in configuration, but Codex skipped those handlers outside SessionEnd. In 0.148.0-alpha.6, they run in the background with a per-session concurrency limit. SessionEnd remains synchronous.

An asynchronous hook cannot block, stop, or rewrite the operation that launched it. This makes the mode suitable for logging, analytics, and checks that should report back without holding up the agent. Warnings and additional context arrive at safe turn boundaries. If a turn is active, Codex injects the result after model sampling; if the session is idle, Codex buffers it before the next prompt.

Sources: OpenAI Codex 0.148.0-alpha.6. OpenAI Codex PR #37533 for asynchronous command hooks.

/hooks shows Sync or Async

The hooks browser in the terminal interface now displays a Mode field with Sync or Async. The app server's hooks/list response exposes the same information as executionMode; sync is the default for compatibility with older clients.

OpenAI's stable hooks documentation still describes async as parsed but not active. That version boundary matters: the new behavior is in 0.148.0-alpha.6, not the stable 0.147.0 channel.

The alpha also cleans up hooks that exceed their timeout. Codex terminates the complete process tree on Unix and Windows. Child processes may continue when the hook completes normally.

Sources: OpenAI Codex PR #37538 for execution mode in the hooks browser. OpenAI Codex hooks documentation. OpenAI Codex PR #37527 for hook timeouts and process trees.

Human step: test an existing hook in the background

The npm registry contains 0.148.0-alpha.6, but latest points to 0.147.0 and the regular alpha tag pointed to a 0.147 hotfix when checked. Select the exact version if you want to test this feature:

npm install -g @openai/[email protected]
codex --version

Then add async = true to an existing PostToolUse hook that only logs or analyzes a Bash result:

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

[[hooks.PostToolUse.hooks]]
type = "command"
command = 'python3 "/absolute/path/to/post_tool_audit.py"'
async = true

Start Codex, type /hooks, review the hook, and confirm that the browser shows Mode: Async. Do not use asynchronous mode for a check that must stop or change the command.

Sources: OpenAI Codex npm registry. OpenAI Codex hooks documentation for configuration and /hooks. OpenAI Codex PR #37538 with async = true and Async mode.

Short example: use the new Codex feature

With an asynchronous Bash PostToolUse hook active, use a bounded read-only task:

Run `git status --short`. Report whether the working tree is clean and otherwise list the changed paths. Change nothing.

A good test should meet these checks:

• Codex runs the status check without changing the project.
• /hooks shows that the selected handler runs as Async.
• The hook does not hold the operation open to block or rewrite it.
• A warning or additional context from the hook appears at a safe turn boundary.