Documentation 2026-05-22 18:42 UTC to 2026-05-23 00:54 UTC

18| `--cd, -C` | `path` | Set the working directory for the agent before it starts processing your request. |18| `--cd, -C` | `path` | Set the working directory for the agent before it starts processing your request. |

19| `--config, -c` | `key=value` | Override configuration values. Values parse as JSON if possible; otherwise the literal string is used. |19| `--config, -c` | `key=value` | Override configuration values. Values parse as JSON if possible; otherwise the literal string is used. |

20| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Run every command without approvals or sandboxing. Only use inside an externally hardened environment. |20| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Run every command without approvals or sandboxing. Only use inside an externally hardened environment. |

21| `--dangerously-bypass-hook-trust` | `boolean` | Run enabled hooks without requiring persisted hook trust for this invocation. Intended only for automation that already vets hook sources. |

21| `--disable` | `feature` | Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable. |22| `--disable` | `feature` | Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable. |

22| `--enable` | `feature` | Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable. |23| `--enable` | `feature` | Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable. |

23| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |24| `--image, -i` | `path[,path...]` | Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag. |

93 94 

94Key95Key

95 96 

97`--dangerously-bypass-hook-trust`

98 

99Type / Values

100 

101`boolean`

102 

103Details

104 

105Run enabled hooks without requiring persisted hook trust for this invocation. Intended only for automation that already vets hook sources.

106 

107Key

108 

96`--disable`109`--disable`

97 110 

98Type / Values111Type / Values

264| [`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout) | Stable | Remove stored authentication credentials. |277| [`codex logout`](https://developers.openai.com/codex/cli/reference#codex-logout) | Stable | Remove stored authentication credentials. |

265| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |278| [`codex mcp`](https://developers.openai.com/codex/cli/reference#codex-mcp) | Experimental | Manage Model Context Protocol servers (list, add, remove, authenticate). |

266| [`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server) | Experimental | Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex. |279| [`codex mcp-server`](https://developers.openai.com/codex/cli/reference#codex-mcp-server) | Experimental | Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex. |

267| [`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace) | Experimental | Add, upgrade, or remove plugin marketplaces from Git or local sources. |280| [`codex plugin marketplace`](https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace) | Experimental | Add, list, upgrade, or remove plugin marketplaces from Git or local sources. |

268| [`codex remote-control`](https://developers.openai.com/codex/cli/reference#codex-remote-control) | Experimental | Ensure the local app-server daemon is running with remote-control support enabled. |281| [`codex remote-control`](https://developers.openai.com/codex/cli/reference#codex-remote-control) | Experimental | Ensure the local app-server daemon is running with remote-control support enabled. |

269| [`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume) | Stable | Continue a previous interactive session by ID or resume the most recent conversation. |282| [`codex resume`](https://developers.openai.com/codex/cli/reference#codex-resume) | Stable | Continue a previous interactive session by ID or resume the most recent conversation. |

270| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes. |283| [`codex sandbox`](https://developers.openai.com/codex/cli/reference#codex-sandbox) | Experimental | Run arbitrary commands inside Codex-provided macOS, Linux, or Windows sandboxes. |

472 485 

473Details486Details

474 487 

475Add, upgrade, or remove plugin marketplaces from Git or local sources.488Add, list, upgrade, or remove plugin marketplaces from Git or local sources.

476 489 

477Key490Key

478 491 

939| `--cd, -C` | `path` | Set the workspace root before executing the task. |952| `--cd, -C` | `path` | Set the workspace root before executing the task. |

940| `--color` | `always | never | auto` | Control ANSI color in stdout. |953| `--color` | `always | never | auto` | Control ANSI color in stdout. |

941| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner. |954| `--dangerously-bypass-approvals-and-sandbox, --yolo` | `boolean` | Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner. |

955| `--dangerously-bypass-hook-trust` | `boolean` | Run enabled hooks without requiring persisted hook trust for this invocation. Intended only for automation that already vets hook sources. |

942| `--ephemeral` | `boolean` | Run without persisting session rollout files to disk. |956| `--ephemeral` | `boolean` | Run without persisting session rollout files to disk. |

943| `--full-auto` | `boolean` | Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used. |957| `--full-auto` | `boolean` | Deprecated compatibility flag. Prefer `--sandbox workspace-write`; Codex prints a warning when this flag is used. |

944| `--ignore-rules` | `boolean` | Do not load user or project execpolicy `.rules` files for this run. |958| `--ignore-rules` | `boolean` | Do not load user or project execpolicy `.rules` files for this run. |

994 1008 

995Key1009Key

996 1010 

1011`--dangerously-bypass-hook-trust`

1012 

1013Type / Values

1014 

1015`boolean`

1016 

1017Details

1018 

1019Run enabled hooks without requiring persisted hook trust for this invocation. Intended only for automation that already vets hook sources.

1020 

1021Key

1022 

997`--ephemeral`1023`--ephemeral`

998 1024 

999Type / Values1025Type / Values

1510| Key | Type / Values | Details |1536| Key | Type / Values | Details |

1511| --- | --- | --- |1537| --- | --- | --- |

1512| `add <source>` | `[--ref REF] [--sparse PATH]` | Install a plugin marketplace from GitHub shorthand, a Git URL, an SSH URL, or a local marketplace root directory. `--sparse` is supported only for Git sources and can be repeated. |1538| `add <source>` | `[--ref REF] [--sparse PATH]` | Install a plugin marketplace from GitHub shorthand, a Git URL, an SSH URL, or a local marketplace root directory. `--sparse` is supported only for Git sources and can be repeated. |

1539| `list` | | Show plugin marketplaces Codex is currently considering and the root path for each marketplace. |

1513| `remove <marketplace-name>` | | Remove a configured plugin marketplace. |1540| `remove <marketplace-name>` | | Remove a configured plugin marketplace. |

1514| `upgrade [marketplace-name]` | | Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided. |1541| `upgrade [marketplace-name]` | | Refresh one configured Git marketplace, or all configured Git marketplaces when no name is provided. |

1515 1542 

1527 1554 

1528Key1555Key

1529 1556 

1557`list`

1558 

1559Details

1560 

1561Show plugin marketplaces Codex is currently considering and the root path for each marketplace.

1562 

1563Key

1564 

1530`remove <marketplace-name>`1565`remove <marketplace-name>`

1531 1566 

1532Details1567Details

1546root directories. Use `--ref` to pin a Git ref, and repeat `--sparse PATH` to1581root directories. Use `--ref` to pin a Git ref, and repeat `--sparse PATH` to

1547use a sparse checkout for Git-backed marketplace repositories.1582use a sparse checkout for Git-backed marketplace repositories.

1548 1583 

1584`codex plugin marketplace list` prints in-scope marketplace names and roots,

1585including implicitly discovered default marketplaces and configured marketplace

1586snapshots.

1587 

1549### `codex mcp-server`1588### `codex mcp-server`

1550 1589 

1551Run Codex as an MCP server over stdio so that other tools can connect. This command inherits global configuration overrides and exits when the downstream client closes the connection.1590Run Codex as an MCP server over stdio so that other tools can connect. This command inherits global configuration overrides and exits when the downstream client closes the connection.

169| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |169| `apps` | false | Experimental | Enable ChatGPT Apps/connectors support |

170| `codex_git_commit` | false | Experimental | Enable Codex-generated git commits and commit attribution trailers |170| `codex_git_commit` | false | Experimental | Enable Codex-generated git commits and commit attribution trailers |

171| `hooks` | true | Stable | Enable lifecycle hooks from `hooks.json` or inline `[hooks]`. See [Hooks](https://developers.openai.com/codex/hooks). |171| `hooks` | true | Stable | Enable lifecycle hooks from `hooks.json` or inline `[hooks]`. See [Hooks](https://developers.openai.com/codex/hooks). |

172| `plugin_hooks` | false | Under development | Opt into lifecycle hooks bundled with plugins. See [Hooks](https://developers.openai.com/codex/hooks#plugin-bundled-hooks). |

173| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |172| `fast_mode` | true | Stable | Enable Fast mode selection and the `service_tier = "fast"` path |

174| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |173| `memories` | false | Stable | Enable [Memories](https://developers.openai.com/codex/memories) |

175| `multi_agent` | true | Stable | Enable subagent collaboration tools |174| `multi_agent` | true | Stable | Enable subagent collaboration tools |

74| `features.network_proxy.socks_url` | `string` | SOCKS5 listener URL. Defaults to `"http://127.0.0.1:8081"`. |74| `features.network_proxy.socks_url` | `string` | SOCKS5 listener URL. Defaults to `"http://127.0.0.1:8081"`. |

75| `features.network_proxy.unix_sockets` | `map<string, allow | none>` | Unix socket policy for sandboxed networking. Unset by default; add `allow` entries for permitted sockets. |75| `features.network_proxy.unix_sockets` | `map<string, allow | none>` | Unix socket policy for sandboxed networking. Unset by default; add `allow` entries for permitted sockets. |

76| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |76| `features.personality` | `boolean` | Enable personality selection controls (stable; on by default). |

77| `features.plugin_hooks` | `boolean` | Opt into lifecycle hooks bundled with enabled plugins. Off by default in this release; set to `true` to opt in. |

78| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |77| `features.prevent_idle_sleep` | `boolean` | Prevent the machine from sleeping while a turn is actively running (experimental; off by default). |

79| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |78| `features.shell_snapshot` | `boolean` | Snapshot shell environment to speed up repeated commands (stable; on by default). |

80| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |79| `features.shell_tool` | `boolean` | Enable the default `shell` tool for running commands (stable; on by default). |

92| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |91| `history.max_bytes` | `number` | If set, caps the history file size in bytes by dropping oldest entries. |

93| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |92| `history.persistence` | `save-all | none` | Control whether Codex saves session transcripts to history.jsonl. |

94| `hooks` | `table` | Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events. |93| `hooks` | `table` | Lifecycle hooks configured inline in `config.toml`. Uses the same event schema as `hooks.json`; see the Hooks guide for examples and supported events. |

94| `hooks.<Event>` | `array<table>` | Matcher groups for hook events such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, or `Stop`. |

95| `hooks.<Event>[].hooks` | `array<table>` | Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped. |

96| `hooks.<Event>[].hooks[].commandWindows` | `string` | Windows-only command override for command hooks. The TOML alias `command_windows` is also accepted. |

95| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |97| `instructions` | `string` | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |

96| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |98| `log_dir` | `string (path)` | Directory where Codex writes log files (for example `codex-tui.log`); defaults to `$CODEX_HOME/log`. |

97| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |99| `mcp_oauth_callback_port` | `integer` | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |

962 964 

963Key965Key

964 966 

965`features.plugin_hooks`

966 

967Type / Values

968 

969`boolean`

970 

971Details

972 

973Opt into lifecycle hooks bundled with enabled plugins. Off by default in this release; set to `true` to opt in.

974 

975Key

976 

977`features.prevent_idle_sleep`967`features.prevent_idle_sleep`

978 968 

979Type / Values969Type / Values

1178 1168 

1179Key1169Key

1180 1170 

1171`hooks.<Event>`

1172 

1173Type / Values

1174 

1175`array<table>`

1176 

1177Details

1178 

1179Matcher groups for hook events such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, or `Stop`.

1180 

1181Key

1182 

1183`hooks.<Event>[].hooks`

1184 

1185Type / Values

1186 

1187`array<table>`

1188 

1189Details

1190 

1191Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped.

1192 

1193Key

1194 

1195`hooks.<Event>[].hooks[].commandWindows`

1196 

1197Type / Values

1198 

1199`string`

1200 

1201Details

1202 

1203Windows-only command override for command hooks. The TOML alias `command_windows` is also accepted.

1204 

1205Key

1206 

1181`instructions`1207`instructions`

1182 1208 

1183Type / Values1209Type / Values

3396 3422 

3397| Key | Type / Values | Details |3423| Key | Type / Values | Details |

3398| --- | --- | --- |3424| --- | --- | --- |

3425| `allow_managed_hooks_only` | `boolean` | When `true`, Codex skips user, project, session, and plugin hooks while still allowing managed hooks from `requirements.toml` and other managed config layers. |

3399| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |3426| `allowed_approval_policies` | `array<string>` | Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `granular`). |

3400| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. |3427| `allowed_approvals_reviewers` | `array<string>` | Allowed values for `approvals_reviewer`, such as `user` and `auto_review`. |

3401| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |3428| `allowed_sandbox_modes` | `array<string>` | Allowed values for `sandbox_mode`. |

3420| `features.in_app_browser` | `boolean` | Set to `false` in `requirements.toml` to disable the in-app browser pane. |3447| `features.in_app_browser` | `boolean` | Set to `false` in `requirements.toml` to disable the in-app browser pane. |

3421| `guardian_policy_config` | `string` | Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored. |3448| `guardian_policy_config` | `string` | Managed Markdown policy instructions for automatic review. This takes precedence over local `[auto_review].policy`. Blank values are ignored. |

3422| `hooks` | `table` | Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`. |3449| `hooks` | `table` | Admin-enforced managed lifecycle hooks. Requires a managed hook directory and uses the same event schema as inline `[hooks]` in `config.toml`. |

3423| `hooks.<Event>` | `array<table>` | Matcher groups for a hook event such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, or `Stop`. |3450| `hooks.<Event>` | `array<table>` | Matcher groups for a hook event such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, or `Stop`. |

3424| `hooks.<Event>[].hooks` | `array<table>` | Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped. |3451| `hooks.<Event>[].hooks` | `array<table>` | Hook handlers for a matcher group. Command hooks are currently supported; prompt and agent hook handlers are parsed but skipped. |

3452| `hooks.<Event>[].hooks[].commandWindows` | `string` | Windows-only command override for command hooks. The TOML alias `command_windows` is also accepted. |

3425| `hooks.managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks. |3453| `hooks.managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on macOS and Linux. Codex validates that it is absolute and exists before loading managed hooks. |

3426| `hooks.windows_managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks. |3454| `hooks.windows_managed_dir` | `string (absolute path)` | Directory containing managed hook scripts on Windows. Codex validates that it is absolute and exists before loading managed hooks. |

3427| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |3455| `mcp_servers` | `table` | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |

3443 3471 

3444Key3472Key

3445 3473 

3474`allow_managed_hooks_only`

3475 

3476Type / Values

3477 

3478`boolean`

3479 

3480Details

3481 

3482When `true`, Codex skips user, project, session, and plugin hooks while still allowing managed hooks from `requirements.toml` and other managed config layers.

3483 

3484Key

3485 

3446`allowed_approval_policies`3486`allowed_approval_policies`

3447 3487 

3448Type / Values3488Type / Values

3739 3779 

3740Details3780Details

3741 3781 

3742Matcher groups for a hook event such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, or `Stop`.3782Matcher groups for a hook event such as `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, or `Stop`.

3743 3783 

3744Key3784Key

3745 3785 

3755 3795 

3756Key3796Key

3757 3797 

3798`hooks.<Event>[].hooks[].commandWindows`

3799 

3800Type / Values

3801 

3802`string`

3803 

3804Details

3805 

3806Windows-only command override for command hooks. The TOML alias `command_windows` is also accepted.

3807 

3808Key

3809 

3758`hooks.managed_dir`3810`hooks.managed_dir`

3759 3811 

3760Type / Values3812Type / Values

1086107110861071

1087107210871072

1088107310881073

10891074

10901075

1091# Codex example configuration (config.toml)1089# Codex example configuration (config.toml)

1092#1090#

1093# This file lists the main keys Codex reads from config.toml, along with default1091# This file lists the main keys Codex reads from config.toml, along with default

1728 1726 

1729# hooks = false1727# hooks = false

1730 1728 

1731# plugin_hooks = false # Default off; set true to opt into plugin-bundled hooks.

1732 

1733# codex_git_commit = false1729# codex_git_commit = false

1734 1730 

1735# unified_exec = true1731# unified_exec = true

8 8 

9There are three ways to monitor Codex usage, depending on what you need:9There are three ways to monitor Codex usage, depending on what you need:

10 10 

11- **Analytics Dashboard**: quick visibility into adoption and code review impact.11- **Analytics Dashboard**: quick visibility into adoption, usage, and code review impact.

12- **Analytics API**: pull structured daily metrics into your data warehouse or BI tools.12- **Analytics API**: pull structured daily metrics into your data warehouse or BI tools.

13- **Compliance API**: exports detailed activity logs for audit, monitoring, and investigations.13- **Compliance API**: exports detailed activity logs for audit, monitoring, and investigations.

14 14 

15## Analytics Dashboard15## Analytics Dashboard

16 16 

17![Codex analytics dashboard](/images/codex/enterprise/analytics-dashboard.png)17![Codex analytics dashboard showing credit and token usage by model](/images/codex/enterprise/analytics-dashboard.png)

18 18 

19### Dashboard views19### Dashboard views

20 20 

21The [analytics dashboard](https://chatgpt.com/codex/cloud/settings/analytics#usage) allows ChatGPT workspace administrators and analytics viewers to track Codex adoption, usage, and Code Review feedback. Usage data can lag by up to 12 hours.21The [analytics dashboard](https://admin.openai.com/analytics/codex) allows ChatGPT workspace administrators and analytics viewers to track Codex adoption, usage, and Code Review feedback. Usage data can lag by up to 12 hours.

22 22 

23Codex provides date-range controls for daily and weekly views. Key charts include:23Codex provides date-range controls for daily and weekly views. Key charts include:

24 24 

25- Active users by product surface, including CLI, IDE extension, cloud, desktop, and Code Review25- Active users by product surface, including CLI, IDE extension, cloud, desktop, and Code Review

26- Workspace and personal usage breakdowns, including credit and token usage by product surface26- Workspace and personal usage breakdowns, including credit and token usage by product surface or model

27- Product activity for threads and turns by client27- Product activity for threads and turns by client

28- User ranking table, with filters for client and sort options such as credits, threads, turns, text tokens, and current streak28- User ranking table, with filters for client and sort options such as credits, threads, turns, text tokens, and current streak

29- Code Review activity, including PRs reviewed, issues by priority, comments, replies, reactions, and feedback sentiment29- Code Review activity, including PRs reviewed, issues by priority, comments, replies, reactions, and feedback sentiment

220scripts.220scripts.

221 221 

222To enforce managed hooks even for users who disabled hooks locally, pin222To enforce managed hooks even for users who disabled hooks locally, pin

223`[features].hooks = true` alongside `[hooks]`.223`[features].hooks = true` alongside `[hooks]`. To skip user, project, session,

224and plugin hooks while still allowing managed hooks, set

225`allow_managed_hooks_only = true`.

224 226 

225```227```

228allow_managed_hooks_only = true

229 

226[features]230[features]

227hooks = true231hooks = true

228 232 

236[[hooks.PreToolUse.hooks]]240[[hooks.PreToolUse.hooks]]

237type = "command"241type = "command"

238command = "python3 /enterprise/hooks/pre_tool_use_policy.py"242command = "python3 /enterprise/hooks/pre_tool_use_policy.py"

243command_windows = 'py -3 C:\enterprise\hooks\pre_tool_use_policy.py'

239timeout = 30244timeout = 30

240statusMessage = "Checking managed Bash command"245statusMessage = "Checking managed Bash command"

241```246```

247- Deliver those scripts separately with your MDM or device-management solution.252- Deliver those scripts separately with your MDM or device-management solution.

248- Managed hook commands should reference absolute script paths under the253- Managed hook commands should reference absolute script paths under the

249 configured managed directory.254 configured managed directory.

255- `allow_managed_hooks_only = true` skips hooks from user, project, session, and

256 plugin sources, but still loads hooks from `requirements.toml` and other

257 managed config layers.

250 258 

251### Enforce command rules from requirements259### Enforce command rules from requirements

252 260 

29- Multiple matching command hooks for the same event are launched concurrently,29- Multiple matching command hooks for the same event are launched concurrently,

30 so one hook cannot prevent another matching hook from starting.30 so one hook cannot prevent another matching hook from starting.

31- Non-managed command hooks must be reviewed and trusted before they run.31- Non-managed command hooks must be reviewed and trusted before they run.

32- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, and32- `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`,

33 `Stop` run at turn scope.33 `PostCompact`, `UserPromptSubmit`, `SubagentStop`, and `Stop` run at turn

34 scope. `SessionStart` and `SubagentStart` run at thread or subagent-start

35 scope.

34 36 

35## Where Codex looks for hooks37## Where Codex looks for hooks

36 38 

56If a single layer contains both `hooks.json` and inline `[hooks]`, Codex58If a single layer contains both `hooks.json` and inline `[hooks]`, Codex

57merges them and warns at startup. Prefer one representation per layer.59merges them and warns at startup. Prefer one representation per layer.

58 60 

59Plugin hooks are off by default in this release. If61Codex can also discover hooks bundled with enabled plugins. Plugin-bundled

60`[features].plugin_hooks = true`, Codex can also discover hooks bundled with62hooks load alongside other hook sources and use the same trust-review flow as

61enabled plugins. Otherwise, enabled plugins won’t run bundled hooks.63other non-managed hooks.

62 64 

63Project-local hooks load only when the project `.codex/` layer is trusted. In65Project-local hooks load only when the project `.codex/` layer is trusted. In

64untrusted projects, Codex still loads user and system hooks from their own66untrusted projects, Codex still loads user and system hooks from their own

65active config layers.67active config layers.

66 68 

67## Review and manage hooks69## Review and trust hooks

68 70 

69Codex lists configured hooks before deciding which ones can run. Use `/hooks`71Codex lists configured hooks before deciding which ones can run. Before a

70in the CLI to inspect hook sources, review new or changed hooks, trust hooks, or72non-managed command hook can run, Codex requires you to review and trust the

71disable individual non-managed hooks. If hooks need review at startup, Codex73exact hook definition. Codex records trust against the hook’s current hash, so

72prints a warning that tells you to open `/hooks`.74new or changed hooks are marked for review and skipped until trusted.

75 

76Use `/hooks` in the CLI to inspect hook sources, review new or changed hooks,

77trust hooks, or disable individual non-managed hooks. If hooks need review at

78startup, Codex prints a warning that tells you to open `/hooks`.

73 79 

74Managed hooks from system, MDM, cloud, or `requirements.toml` sources are marked80Managed hooks from system, MDM, cloud, or `requirements.toml` sources are marked

75as managed, trusted by policy, and can’t be disabled from the user hook browser.81as managed, trusted by policy, and can’t be disabled from the user hook browser.

76 82 

83For one-off automation that already vets hook sources outside Codex, pass

84`--dangerously-bypass-hook-trust` to run enabled hooks without requiring

85persisted hook trust for that invocation.

86 

77## Config shape87## Config shape

78 88 

79Hooks are organized in three levels:89Hooks are organized in three levels:

80 90 

81- A hook event such as `PreToolUse`, `PostToolUse`, or `Stop`91- A hook event such as `PreToolUse`, `PostToolUse`, `PreCompact`,

92 `SubagentStart`, or `Stop`

82- A matcher group that decides when that event matches93- A matcher group that decides when that event matches

83- One or more hook handlers that run when the matcher group matches94- One or more hook handlers that run when the matcher group matches

84 95 

163- `timeout` is in seconds.174- `timeout` is in seconds.

164- If `timeout` is omitted, Codex uses `600` seconds.175- If `timeout` is omitted, Codex uses `600` seconds.

165- `statusMessage` is optional.176- `statusMessage` is optional.

177- `commandWindows` is an optional Windows-only command override. In TOML, use

178 `command_windows` or `commandWindows`.

166- `async` is parsed, but async command hooks aren’t supported yet. Codex skips179- `async` is parsed, but async command hooks aren’t supported yet. Codex skips

167 handlers with `async: true`.180 handlers with `async: true`.

168- Only `type: "command"` handlers run today. `prompt` and `agent` handlers are181- Only `type: "command"` handlers run today. `prompt` and `agent` handlers are

200This is useful when admins want to enforce the hook configuration while213This is useful when admins want to enforce the hook configuration while

201delivering the actual scripts through MDM or another device-management system.214delivering the actual scripts through MDM or another device-management system.

202To enforce managed hooks even for users who disabled hooks locally, pin215To enforce managed hooks even for users who disabled hooks locally, pin

203`[features].hooks = true` in `requirements.toml` alongside `[hooks]`.216`[features].hooks = true` in `requirements.toml` alongside `[hooks]`. To ignore

217user, project, session, and plugin hooks while still allowing administrator

218managed hooks, set `allow_managed_hooks_only = true`.

204 219 

205```220```

221allow_managed_hooks_only = true

222 

206[features]223[features]

207hooks = true224hooks = true

208 225 

216[[hooks.PreToolUse.hooks]]233[[hooks.PreToolUse.hooks]]

217type = "command"234type = "command"

218command = "python3 /enterprise/hooks/pre_tool_use_policy.py"235command = "python3 /enterprise/hooks/pre_tool_use_policy.py"

236command_windows = 'py -3 C:\enterprise\hooks\pre_tool_use_policy.py'

219timeout = 30237timeout = 30

220statusMessage = "Checking managed Bash command"238statusMessage = "Checking managed Bash command"

221```239```

228 tooling must install and update them separately.246 tooling must install and update them separately.

229- Managed hook commands should use absolute script paths under the configured247- Managed hook commands should use absolute script paths under the configured

230 managed directory.248 managed directory.

249- `allow_managed_hooks_only = true` skips hooks from user, project, session, and

250 plugin sources, but still loads managed hooks from `requirements.toml` and

251 other managed config layers.

231 252 

232## Plugin-bundled hooks253## Plugin-bundled hooks

233 254 

234Plugin-bundled hooks are opt-in for this release. When255When a plugin is enabled, Codex can load lifecycle hooks from that plugin

235`[features].plugin_hooks = true` and a plugin is enabled, Codex can load256alongside user, project, and managed hooks.

236lifecycle hooks from that plugin alongside user, project, and managed hooks.

237 

238```

239[features]

240plugin_hooks = true

241```

242 257 

243By default, Codex looks for `hooks/hooks.json` inside the plugin root. A plugin258By default, Codex looks for `hooks/hooks.json` inside the plugin root. A plugin

244manifest can override that default with a `hooks` entry in259manifest can override that default with a `hooks` entry in

266- Codex also sets `CLAUDE_PLUGIN_ROOT` and `CLAUDE_PLUGIN_DATA` for281- Codex also sets `CLAUDE_PLUGIN_ROOT` and `CLAUDE_PLUGIN_DATA` for

267 compatibility with existing plugin hooks.282 compatibility with existing plugin hooks.

268 283 

269Plugin hooks use the same event schema as other hooks. They are non-managed284Plugin hooks use the same event schema as other hooks. Installing or enabling a

270hooks, so they require trust review before they run.285plugin doesn’t automatically trust its hooks; Codex skips plugin-bundled hooks

286until you review and trust the current hook definition.

271 287 

272## Matcher patterns288## Matcher patterns

273 289 

281| --- | --- | --- |297| --- | --- | --- |

282| `PermissionRequest` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |298| `PermissionRequest` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

283| `PostToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |299| `PostToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

300| `PostCompact` | compaction trigger | Values are `manual` or `auto` |

301| `PreCompact` | compaction trigger | Values are `manual` or `auto` |

284| `PreToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |302| `PreToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

285| `SessionStart` | start source | Current runtime values are `startup`, `resume`, and `clear` |303| `SessionStart` | start source | Values are `startup`, `resume`, `clear`, and `compact` |

304| `SubagentStart` | subagent type | Values depend on the subagent that starts |

305| `SubagentStop` | subagent type | Values depend on the subagent that stops |

286| `UserPromptSubmit` | not supported | Any configured `matcher` is ignored for this event |306| `UserPromptSubmit` | not supported | Any configured `matcher` is ignored for this event |

287| `Stop` | not supported | Any configured `matcher` is ignored for this event |307| `Stop` | not supported | Any configured `matcher` is ignored for this event |

288 308 

295- `Edit|Write`315- `Edit|Write`

296- `mcp__filesystem__read_file`316- `mcp__filesystem__read_file`

297- `mcp__filesystem__.*`317- `mcp__filesystem__.*`

298- `startup|resume|clear`318- `startup|resume|clear|compact`

319- `manual|auto`

299 320 

300## Common input fields321## Common input fields

301 322 

305 326 

306| Field | Type | Meaning |327| Field | Type | Meaning |

307| --- | --- | --- |328| --- | --- | --- |

308| `session_id` | `string` | Current session or thread id. |329| `session_id` | `string` | Current Codex session id. Subagent hooks use the parent session id. |

309| `transcript_path` | `string | null` | Path to the session transcript file, if any |330| `transcript_path` | `string | null` | Path to the session transcript file, if any |

310| `cwd` | `string` | Working directory for the session |331| `cwd` | `string` | Working directory for the session |

311| `hook_event_name` | `string` | Current hook event name |332| `hook_event_name` | `string` | Current hook event name |

315event-specific tables.336event-specific tables.

316 337 

317`SessionStart`, `PreToolUse`, `PermissionRequest`, `PostToolUse`,338`SessionStart`, `PreToolUse`, `PermissionRequest`, `PostToolUse`,

318`UserPromptSubmit`, and `Stop` also include `permission_mode`, which describes339`UserPromptSubmit`, `SubagentStart`, `SubagentStop`, and `Stop` also include

319the current permission mode as `default`, `acceptEdits`, `plan`, `dontAsk`, or340`permission_mode`, which describes the current permission mode as `default`,

320`bypassPermissions`.341`acceptEdits`, `plan`, `dontAsk`, or `bypassPermissions`.

321 342 

322`transcript_path` points to a conversation transcript for convenience, but the343`transcript_path` points to a conversation transcript for convenience, but the

323transcript format is not a stable interface for hooks and may change over time.344transcript format is not a stable interface for hooks and may change over time.

326 347 

327## Common output fields348## Common output fields

328 349 

329`SessionStart`, `UserPromptSubmit`, and `Stop` support these shared JSON350`SessionStart`, `PreCompact`, `PostCompact`, `UserPromptSubmit`,

330fields:351`SubagentStop`, and `Stop` support these shared JSON fields. `SubagentStart`

352accepts the same shape for `systemMessage` and hook-specific context, but

353`continue: false` doesn’t stop the subagent:

331 354 

332```355```

333{356{

365 388 

366| Field | Type | Meaning |389| Field | Type | Meaning |

367| --- | --- | --- |390| --- | --- | --- |

368| `source` | `string` | How the session started: `startup`, `resume`, or `clear` |391| `source` | `string` | How the session started: `startup`, `resume`, `clear`, or `compact` |

369 392 

370Plain text on `stdout` is added as extra developer context.393Plain text on `stdout` is added as extra developer context.

371 394 

383 406 

384That `additionalContext` text is added as extra developer context.407That `additionalContext` text is added as extra developer context.

385 408 

409### SubagentStart

410 

411`matcher` is applied to `agent_type` for this event.

412 

413Fields in addition to [Common input fields](#common-input-fields):

414 

415| Field | Type | Meaning |

416| --- | --- | --- |

417| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

418| `agent_id` | `string` | Identifier for the subagent |

419| `agent_type` | `string` | Subagent type or profile |

420| `permission_mode` | `string` | Current permission mode |

421 

422Plain text on `stdout` is added as extra developer context for the subagent.

423 

424JSON on `stdout` supports `systemMessage` and this hook-specific shape:

425 

426```

427{

428 "hookSpecificOutput": {

429 "hookEventName": "SubagentStart",

430 "additionalContext": "Review the repository test conventions first."

431 }

432}

433```

434 

435That `additionalContext` text is added as extra developer context for the

436subagent. `continue: false` is parsed for compatibility, but it doesn’t stop the

437subagent from starting.

438 

386### PreToolUse439### PreToolUse

387 440 

388`PreToolUse` can intercept Bash, file edits performed through `apply_patch`,441`PreToolUse` can intercept Bash, file edits performed through `apply_patch`,

587Codex marks the hook run as failed, reports the error, and continues normal640Codex marks the hook run as failed, reports the error, and continues normal

588processing of the tool result.641processing of the tool result.

589 642 

643### PreCompact

644 

645`PreCompact` runs before Codex compacts the conversation. `matcher` is applied

646to `trigger`, whose values are `manual` and `auto`.

647 

648Fields in addition to [Common input fields](#common-input-fields):

649 

650| Field | Type | Meaning |

651| --- | --- | --- |

652| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

653| `trigger` | `string` | What triggered compaction: `manual` or `auto` |

654 

655Plain text on `stdout` is ignored.

656 

657JSON on `stdout` supports [Common output fields](#common-output-fields). If a

658matching `PreCompact` hook returns `continue: false`, Codex stops before

659compacting.

660 

661### PostCompact

662 

663`PostCompact` runs after Codex compacts the conversation. `matcher` is applied

664to `trigger`, whose values are `manual` and `auto`.

665 

666Fields in addition to [Common input fields](#common-input-fields):

667 

668| Field | Type | Meaning |

669| --- | --- | --- |

670| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

671| `trigger` | `string` | What triggered compaction: `manual` or `auto` |

672 

673Plain text on `stdout` is ignored.

674 

675JSON on `stdout` supports [Common output fields](#common-output-fields). If a

676matching `PostCompact` hook returns `continue: false`, Codex stops after

677compacting.

678 

590### UserPromptSubmit679### UserPromptSubmit

591 680 

592`matcher` isn’t currently used for this event.681`matcher` isn’t currently used for this event.

625 714 

626You can also use exit code `2` and write the blocking reason to `stderr`.715You can also use exit code `2` and write the blocking reason to `stderr`.

627 716 

717### SubagentStop

718 

719`matcher` is applied to `agent_type` for this event.

720 

721Fields in addition to [Common input fields](#common-input-fields):

722 

723| Field | Type | Meaning |

724| --- | --- | --- |

725| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |

726| `agent_id` | `string` | Identifier for the subagent |

727| `agent_type` | `string` | Subagent type or profile |

728| `agent_transcript_path` | `string | null` | Path to the subagent transcript file, if any |

729| `stop_hook_active` | `boolean` | Whether this subagent was already continued |

730| `last_assistant_message` | `string | null` | Latest subagent assistant message, if available |

731 

732`SubagentStop` expects JSON on `stdout` when it exits `0`. Plain text output is

733invalid for this event.

734 

735JSON on `stdout` supports [Common output fields](#common-output-fields). To ask

736Codex to continue the subagent flow, return:

737 

738```

739{

740 "decision": "block",

741 "reason": "Run one more focused pass inside the subagent."

742}

743```

744 

745You can also use exit code `2` and write the continuation reason to `stderr`.

746 

747If any matching `SubagentStop` hook returns `continue: false`, that takes

748precedence over continuation decisions from other matching `SubagentStop`

749hooks.

750 

628### Stop751### Stop

629 752 

630`matcher` isn’t currently used for this event.753`matcher` isn’t currently used for this event.

58sparse checkout for Git-backed marketplace repos. `--sparse` is valid only for58sparse checkout for Git-backed marketplace repos. `--sparse` is valid only for

59Git marketplace sources.59Git marketplace sources.

60 60 

61To refresh or remove configured marketplaces:61To inspect, refresh, or remove configured marketplaces:

62 62 

63```63```

64codex plugin marketplace list

64codex plugin marketplace upgrade65codex plugin marketplace upgrade

65codex plugin marketplace upgrade marketplace-name66codex plugin marketplace upgrade marketplace-name

66codex plugin marketplace remove marketplace-name67codex plugin marketplace remove marketplace-name

67```68```

68 69 

70`codex plugin marketplace list` prints each marketplace Codex is considering

71and the root path it resolves from, including local default marketplaces and

72configured marketplace snapshots.

73 

69### Create a plugin manually74### Create a plugin manually

70 75 

71Start with a minimal plugin that packages one skill.76Start with a minimal plugin that packages one skill.

437 `./assets/` when possible.442 `./assets/` when possible.

438- Use `skills` for bundled skill folders, `apps` for `.app.json`,443- Use `skills` for bundled skill folders, `apps` for `.app.json`,

439 `mcpServers` for `.mcp.json`, and `hooks` for lifecycle hooks.444 `mcpServers` for `.mcp.json`, and `hooks` for lifecycle hooks.

440- Plugin hooks are off by default in this release; bundled hooks won’t run445- Enabled plugins can include lifecycle hooks alongside skills, MCP servers, and

441 unless `[features].plugin_hooks = true`.446 apps.

442- When plugin hooks are enabled, omit `hooks` to use the default447- If your plugin stores hooks at `./hooks/hooks.json`, you do not need a

443 `./hooks/hooks.json` file when present.448 `hooks` entry in `.codex-plugin/plugin.json`; Codex checks that default file

449 automatically.

444 450 

445### Bundled MCP servers and lifecycle hooks451### Bundled MCP servers and lifecycle hooks

446 452 

485approval_mode = "approve"491approval_mode = "approve"

486```492```

487 493 

488Plugin hooks are off by default in this release. When494When your plugin is enabled, Codex can load lifecycle hooks from your plugin

489`[features].plugin_hooks = true` and your plugin is enabled, Codex can load495alongside user, project, and managed hooks.

490lifecycle hooks from your plugin alongside user, project, and managed hooks.

491 496 

492```497Installing or enabling a plugin doesn’t automatically trust its hooks.

493[features]498Plugin-bundled hooks are non-managed hooks, so Codex skips them until the user

494plugin_hooks = true499reviews and trusts the current hook definition.

495```

496 500 

497The default plugin hook file is `hooks/hooks.json`:501The default plugin hook file is `hooks/hooks.json`:

498 502