Codex CLI

If you have the PlanBridge Codex CLI hook installed (via contextbridge install), PlanBridge opens whenever Codex finishes a turn with a proposed plan. You review the plan in the browser, and your decision flows back through Codex’s standard Stop hook.

Install

PlanBridge’s Codex installer requires Codex CLI 0.129.0 or newer.

contextbridge install codex

This writes ~/.codex/hooks.json by default, with a Stop hook that runs contextbridge hook codex. It also asks Codex to enable the current hooks feature flag by running codex features enable hooks.

Trust the Codex hook

Codex requires new hooks to be reviewed before they can run. PlanBridge will not run in Codex until you trust the installed Stop hook.

Restart Codex after installing the hook.
When Codex reports a hook needs review, open /hooks.

⚠ 1 hook needs review before it can run. Open /hooks to review it.

In the hooks table, select the Stop row and press Enter.

⚠ 1 hook needs review before it can run. Open /hooks to review it.


  Hooks
  Lifecycle hooks from config and enabled plugins.

  Event                 Installed   Active      Review      Description
  PreToolUse            0           0           0           Before a tool executes
  PermissionRequest     0           0           0           When permission is requested
  PostToolUse           0           0           0           After a tool executes
  PreCompact            0           0           0           Before context compaction
  PostCompact           0           0           0           After context compaction
  SessionStart          0           0           0           When a new session starts
  UserPromptSubmit      0           0           0           When the user submits a prompt
  Stop                  1           0           1           Right before Codex ends its turn

  Press enter to view hooks; esc to close

Verify the command is contextbridge hook codex, then press t to trust it.

⚠ 1 hook needs review before it can run. Open /hooks to review it.


  Stop hooks
  1 hook needs review before it can run.

  [!] Hook 1 · new

  Event     Stop
  Source    User config - ~/.codex/hooks.json
  Command   contextbridge hook codex
  Timeout   345600s
  Trust     New hook - review required

  Press t to trust; esc to go back

Confirm the hook shows Trusted, then press Esc to go back.

⚠ 1 hook needs review before it can run. Open /hooks to review it.


  Stop hooks
  Turn hooks on or off. Your changes are saved automatically.

  [x] Hook 1

  Event     Stop
  Source    User config - ~/.codex/hooks.json
  Command   contextbridge hook codex
  Timeout   345600s
  Trust     Trusted

  Press space or enter to toggle; esc to go back

The snippets above show a default user-scope install. Project-scope installs show a project config path instead of ~/.codex/hooks.json.

For a project-local install, run:

contextbridge install codex --scope project

Project-local installs write <repo>/.codex/hooks.json. The hooks feature flag is still enabled through Codex’s user-level features command.

Process

Open Codex and put the agent in Plan Mode (via /plan or Shift + Tab).
Type your prompt for Codex to plan.
When Codex finishes a turn with a proposed plan, PlanBridge opens in your browser.
Comment on the plan, approve it, or request changes.
If you request changes, Codex receives your comments as the next continuation prompt and revises the plan. If you approve, PlanBridge returns control to Codex’s native Plan Mode approval flow.

After PlanBridge approval, you need to respond to Codex’s native implementation prompt:

  Implement this plan?

› 1. Yes, implement this plan          Switch to Default and start coding.
  2. Yes, clear context and implement  Fresh thread.
  3. No, stay in Plan mode             Continue planning with the model.

How It Works

Codex lifecycle hooks are enabled by Codex’s hooks feature flag and can be configured through hooks.json or inline [hooks] tables. PlanBridge uses hooks.json so it can install and remove its own entry without taking over the rest of your Codex config.

When Codex calls the Stop hook, PlanBridge looks for the latest proposed plan in the hook payload and Codex transcript, opens the local review UI, and waits for your submission. For requested changes, PlanBridge returns a decision: "block" response with your review feedback as the continuation prompt. For approval, PlanBridge returns no continuation so Codex can use its normal plan approval behavior.

Verify

contextbridge install status

You should see Codex CLI listed as installed.

Uninstall

contextbridge uninstall codex

Or contextbridge uninstall to remove PlanBridge plugin and hook entries from every harness it was installed into.

Open content manually

The Stop hook fires automatically and opens plans for review (if you’re in Codex’s plan mode).

To pull an arbitrary markdown file into the PlanBridge UI on demand, use $planbridge-open. See Precision feedback on a file.
To annotate the agent’s previous message, use $planbridge-last. See Annotate the last message.

contextbridge install codex writes both skills to ~/.agents/skills/.

Troubleshooting

PlanBridge not opening plans automatically

Our hook fires automatically when Codex stops and presents a plan from within their native Plan mode. You can enter Plan mode via “Shift + Tab”. It’ll look like this when you’re in Plan Mode:

›

  gpt-5.5 xhigh · ~/code/my-repo                    Plan mode (shift+tab to cycle)

If you don’t like Codex’s Plan mode, you can use $planbridge-open or $planbridge-last to open arbitrary content.

`[features].codex_hooks` deprecation warning

If you installed PlanBridge against an older Codex CLI (before 0.129.0), you may see this warning every time Codex starts:

⚠ `[features].codex_hooks` is deprecated. Use `[features].hooks` instead.
Enable it with `--enable hooks` or `[features].hooks` in config.toml. See
https://developers.openai.com/codex/config-basic#feature-flags for details.

That earlier PlanBridge install set codex_hooks in your Codex config. Current installs use the replacement hooks flag instead, so the old key is just leftover state — Codex prints the warning whenever it’s present (regardless of true/false).

To clear it, open ~/.codex/config.toml and delete the codex_hooks line from the [features] table. Leave the hooks line in place.

[features]
hooks = true
codex_hooks = false  # delete this line