2137At other intelligence levels, ask for subagents explicitly when you want work2137At other intelligence levels, ask for subagents explicitly when you want work
2138delegated in parallel.2138delegated in parallel.
2139 2139
2140If you don't pin a model or `model_reasoning_effort`, Codex can choose a setup2140If you don't configure a subagent model or `model_reasoning_effort`, the
2141that balances intelligence, speed, and price for the task. It may favor `gpt-5.6-terra` for fast scans or a higher-effort `gpt-5.6` configuration for more demanding reasoning. When you want finer control, steer that choice in your prompt or set `model` and `model_reasoning_effort` directly in the agent file.2141subagent inherits the parent agent's model and reasoning effort. If an explicit
2142spawn request or an `[agents]` default selects a model without an
2143explicit or configured reasoning effort, the subagent uses that model's default
2144reasoning effort. To balance intelligence, speed, and price for each task,
2145request a specific model or reasoning effort in your prompt,
2146configure `[agents]` defaults in `config.toml`, or set `model` and
2147`model_reasoning_effort` directly in the custom agent file.
2148For example, use `gpt-5.6-terra` for fast scans or a higher-effort `gpt-5.6` configuration for more demanding reasoning.
2142 2149
2143For most tasks in Codex, start with2150For most tasks in Codex, start with
2144`gpt-5.6`. Use2151`gpt-5.6`. Use
2265- `developer_instructions`2272- `developer_instructions`
2266 2273
2267If a custom agent file sets `model` or `model_reasoning_effort`, the value in2274If a custom agent file sets `model` or `model_reasoning_effort`, the value in
2268the file takes precedence. Otherwise, Codex resolves each setting independently:2275the file takes precedence. Before applying the file, Codex resolves each setting
2269an explicit spawn value, then the corresponding `[agents]` default, then the2276from an explicit spawn value, then the corresponding `[agents]` default, then
2270parent's value. If a spawn selects a different model and neither an explicit nor2277the parent's value. If an explicit spawn request or an `[agents]` default
2271configured effort is present, Codex uses that model's default effort. Other2278selects a model and neither supplies a reasoning effort, Codex uses
2272session settings, such as `sandbox_mode`, `mcp_servers`, and `skills.config`,2279that model's default effort. A custom agent file that sets only `model`
2273inherit from the parent when the custom agent file omits them.2280preserves this previously resolved effort. Set `model_reasoning_effort` in the
2281file too if the selected model doesn't support that effort or you want a
2282different one. Other session settings, such as `sandbox_mode`, `mcp_servers`,
2283and `skills.config`, inherit from the parent when the custom agent file omits
2284them.
2274 2285
2275#### Global settings2286#### Global settings
2276 2287
4001npx @openai/codex-security info --json4012npx @openai/codex-security info --json
4002```4013```
4003 4014
4015See the [CLI and SDK releases](https://github.com/openai/codex-security/releases)
4016for package changes.
4017
4004List the available commands:4018List the available commands:
4005 4019
4006```bash4020```bash
4097plain progress lines instead. CI and terminals without an interactive session4111plain progress lines instead. CI and terminals without an interactive session
4098use plain progress automatically.4112use plain progress automatically.
4099 4113
4114The dashboard also shows live session details. These can contain source code
4115or credentials, so review them before sharing.
4116
4100By default, the CLI writes scan progress and its completion summary to stderr.4117By default, the CLI writes scan progress and its completion summary to stderr.
4101It doesn't print the full scan result to stdout. A completed scan prints a4118It doesn't print the full scan result to stdout. A completed scan prints a
4102summary like this:4119summary like this:
4132 --effort high4149 --effort high
4133```4150```
4134 4151
4135Supported effort levels are `minimal`, `low`, `medium`, `high`, and `xhigh`.4152Supported effort levels are `minimal`, `low`, `medium`, `high`, `xhigh`, and
4153`max`.
4136 4154
4137#### Review the results4155#### Review the results
4138 4156
4162The [CLI reference](https://learn.chatgpt.com/docs/security/cli/reference#scan-artifacts) describes4180The [CLI reference](https://learn.chatgpt.com/docs/security/cli/reference#scan-artifacts) describes
4163the full artifact and output contract.4181the full artifact and output contract.
4164 4182
4183#### Review and patch findings
4184
4185After a complete interactive scan with findings, the CLI offers a finding
4186browser. Review the evidence and choose which findings to fix. You can find
4187the saved tasks in the Codex desktop app.
4188
4189To patch high and critical findings without the browser:
4190
4191```bash
4192npx @openai/codex-security scan "$REPOSITORY" \
4193 --patch --patch-severity high --json
4194```
4195
4196Add `--create-pr` to commit verified patches and open a GitHub pull request.
4197
4198You can also patch saved findings or import Linear issues. See the
4199[`validate` and `patch` reference](https://learn.chatgpt.com/docs/security/cli/reference#codex-security-validate-and-codex-security-patch).
4200
4165#### Choose the next scan4201#### Choose the next scan
4166 4202
4167Use a path scan when a repository contains separate services or packages:4203Use a path scan when a repository contains separate services or packages:
4514 [--subagents N] [--stop-after-no-new N]4550 [--subagents N] [--stop-after-no-new N]
4515 [--max-discovery-runs N] [--max-time-hours HOURS]4551 [--max-discovery-runs N] [--max-time-hours HOURS]
4516 [--model MODEL]4552 [--model MODEL]
4517 [--effort {minimal,low,medium,high,xhigh}]4553 [--effort {minimal,low,medium,high,xhigh,max}]
4518 [--output-dir DIR]4554 [--output-dir DIR]
4519 [--archive-existing]4555 [--archive-existing]
4520 [--plugin-path PATH] [--python PATH]4556 [--plugin-path PATH] [--python PATH]
4521 [--codex KEY=VALUE] [--fail-on-severity LEVEL]4557 [--codex KEY=VALUE] [--fail-on-severity LEVEL]
4558 [--patch] [--patch-severity {critical,high,medium,low}]
4559 [--create-pr]
4522 [--max-cost USD] [--dry-run] [--headless] [--verbose]4560 [--max-cost USD] [--dry-run] [--headless] [--verbose]
4523 [--json] [--format {toon,json,yaml,jsonl}]4561 [--json] [--format {toon,json,yaml,jsonl}]
4524 [--full-output] [repository]4562 [--full-output] [repository]
4733| `--output-dir DIR` | Write scan artifacts to a private directory outside the enclosing Git worktree. Defaults to persistent Codex Security state. |4771| `--output-dir DIR` | Write scan artifacts to a private directory outside the enclosing Git worktree. Defaults to persistent Codex Security state. |
4734| `--archive-existing` | Move existing results to `DIR.previous--` and start with an empty output directory. Requires `--output-dir`. |4772| `--archive-existing` | Move existing results to `DIR.previous--` and start with an empty output directory. Requires `--output-dir`. |
4735| `--fail-on-severity LEVEL` | Return exit `1` when a completed scan reports a finding at or above `critical`, `high`, `medium`, or `low`. |4773| `--fail-on-severity LEVEL` | Return exit `1` when a completed scan reports a finding at or above `critical`, `high`, `medium`, or `low`. |
4774| `--patch` | Fix and verify selected findings after a complete scan. |
4775| `--patch-severity LEVEL` | Patch findings at or above `critical`, `high`, `medium`, or `low`. Defaults to `low`. |
4776| `--create-pr` | Commit verified patch files and open a GitHub pull request. Requires `--patch`. |
4736| `--max-cost USD` | Stop a scan when its estimated model cost exceeds the specified USD amount. |4777| `--max-cost USD` | Stop a scan when its estimated model cost exceeds the specified USD amount. |
4737| `--dry-run` | Check the repository, target, knowledge base, output directory, and Codex configuration without starting a scan. |4778| `--dry-run` | Check the repository, target, knowledge base, output directory, and Codex configuration without starting a scan. |
4738| `--headless` | Show plain-text progress instead of the interactive scan dashboard. |4779| `--headless` | Show plain-text progress instead of the interactive scan dashboard. |
4802| `--auth {auto,chatgpt,api-key}` | Select the scan credentials. The default is `auto`. |4843| `--auth {auto,chatgpt,api-key}` | Select the scan credentials. The default is `auto`. |
4803| `--provider {openai,openrouter,fireworks,amazon-bedrock}` | Select the inference provider. The default is `openai`. |4844| `--provider {openai,openrouter,fireworks,amazon-bedrock}` | Select the inference provider. The default is `openai`. |
4804| `--model MODEL` | Select the model. The default is `gpt-5.6-sol`. Required for OpenRouter, Fireworks, and Amazon Bedrock. |4845| `--model MODEL` | Select the model. The default is `gpt-5.6-sol`. Required for OpenRouter, Fireworks, and Amazon Bedrock. |
4805| `--effort {minimal,low,medium,high,xhigh}` | Select the model's reasoning effort. The default is `xhigh`. |4846| `--effort {minimal,low,medium,high,xhigh,max}` | Select the model's reasoning effort. The default is `xhigh`. |
4806| `--plugin-path PATH` | Use a Codex Security plugin directory or ZIP to override the bundled plugin. |4847| `--plugin-path PATH` | Use a Codex Security plugin directory or ZIP to override the bundled plugin. |
4807| `--python PATH` | Select the Python interpreter for the plugin runtime. |4848| `--python PATH` | Select the Python interpreter for the plugin runtime. |
4808| `--codex KEY=VALUE` | Override an isolated Codex configuration value. Values use TOML syntax. Repeat the flag for more values. |4849| `--codex KEY=VALUE` | Override an isolated Codex configuration value. Values use TOML syntax. Repeat the flag for more values. |
4851 [--workers N] [--mode {standard,deep}]4892 [--workers N] [--mode {standard,deep}]
4852 [--provider {openai,openrouter,fireworks,amazon-bedrock}]4893 [--provider {openai,openrouter,fireworks,amazon-bedrock}]
4853 [--model MODEL]4894 [--model MODEL]
4854 [--effort {minimal,low,medium,high,xhigh}]4895 [--effort {minimal,low,medium,high,xhigh,max}]
4855 [--knowledge-base PATH]4896 [--knowledge-base PATH]
4856 [--scan-prompt-file FILE]4897 [--scan-prompt-file FILE]
4857 [--post-scan-prompt-file FILE]4898 [--post-scan-prompt-file FILE]
5197 "Missing authorization check in src/routes.ts:18"5238 "Missing authorization check in src/routes.ts:18"
5198```5239```
5199 5240
5200Each argument can contain literal text or point to a file. Both commands work5241Each positional argument accepts literal text or a file path. These inputs use
5201against the current directory. Use `validate` to directly recheck an original5242the current directory. Use `validate` to recheck a finding after a fix or when a
5202finding after a fix or when a later scan no longer reports it. A scan5243later scan no longer reports it. Comparing scans alone doesn't prove that a fix
5203comparison alone doesn't prove that a fix worked. External tools can use these5244worked.
5204commands without rebuilding the scanner.
5205 5245
5206Use `--effort` to select reasoning effort for either command:5246Use `--effort` to select reasoning effort for either command:
5207 5247
5209npx @openai/codex-security validate "Possible SQL injection" --effort high5249npx @openai/codex-security validate "Possible SQL injection" --effort high
5210```5250```
5211 5251
5252#### Patch findings after a scan
5253
5254Use `scan --patch` to fix findings after a complete scan. This requires
5255`@openai/codex-security` 0.1.15 or later. The default severity threshold is
5256`low`. This command selects high and critical findings:
5257
5258```bash
5259npx @openai/codex-security scan . --patch --patch-severity high --json
5260```
5261
5262Verified and already-fixed findings don't trigger `--fail-on-severity`.
5263
5264#### Patch saved findings
5265
5266Pass a finding or occurrence ID to patch its original repository, or select
5267findings from a saved scan:
5268
5269```bash
5270npx @openai/codex-security patch OCCURRENCE_ID
5271npx @openai/codex-security patch --scan SCAN_ID --severity high --json
5272npx @openai/codex-security patch --scan latest --severity medium
5273```
5274
5275`--scan latest` selects the latest completed scan for the current repository.
5276Saved-finding commands support `--json`; literal-text and file inputs don't.
5277
5278Add `--create-pr` to commit only verified patch files and open a pull request
5279with the GitHub CLI:
5280
5281```bash
5282npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr
5283```
5284
5285If the push or pull request fails, run the printed `patch --resume-pr BRANCH`
5286command from the same repository to retry.
5287
5288#### Patch Linear issues
5289
5290Set `CODEX_SECURITY_LINEAR_API_KEY` or `LINEAR_API_KEY` for a personal API key,
5291or `LINEAR_ACCESS_TOKEN` for an OAuth token. Prefer an environment variable to
5292`--linear-api-key KEY` to keep the key out of shell history.
5293
5294Import an issue by ID or URL. Repeat `--linear-issue` to select more than one
5295issue:
5296
5297```bash
5298npx @openai/codex-security patch --linear-issue SEC-123 --linear-issue SEC-124
5299```
5300
5301Use `--linear-project` to select a project's open issues. Add `--linear-filter`
5302to narrow the selection:
5303
5304```bash
5305npx @openai/codex-security patch --linear-project "Security backlog" \
5306 --linear-filter '{"labels":{"name":{"eq":"security"}}}'
5307```
5308
5309The CLI excludes completed and canceled issues unless the filter sets `state`.
5310It doesn't change the Linear issues.
5311
5212#### `codex-security login`, `logout`, and `info`5312#### `codex-security login`, `logout`, and `info`
5213 5313
5214Sign in interactively:5314Sign in interactively:
5271npx @openai/codex-security scan . --headless5371npx @openai/codex-security scan . --headless
5272```5372```
5273 5373
5374The dashboard also shows live session details. They aren't redacted and can
5375contain source code or credentials. Review them before sharing.
5376
5274#### Verbose diagnostics5377#### Verbose diagnostics
5275 5378
5276Add `--verbose` to print redacted lifecycle, authentication, progress, and cost5379Add `--verbose` to print redacted lifecycle, authentication, progress, and cost
5328 usage5431 usage
5329```5432```
5330 5433
5434When [patching](#patch-findings-after-a-scan), JSON output also includes patch
5435results and any created pull request.
5436
5331Progress, completion summaries, archive notices, and errors remain on stderr.5437Progress, completion summaries, archive notices, and errors remain on stderr.
5332A completed scan still prints the full JSON result when a severity policy5438A completed scan still prints the full JSON result when a severity policy
5333returns exit `1` or incomplete coverage returns exit `2`.5439returns exit `1` or incomplete coverage returns exit `2`.
6486}6592}
6487```6593```
6488 6594
6595Findings can include optional `codeEvidence`, `rootCause`, `validation`,
6596`attackPath`, `remediationTests`, and `preventiveControls` fields.
6597
6489For repository-wide findings, `confirmedInLatestScan` distinguishes findings6598For repository-wide findings, `confirmedInLatestScan` distinguishes findings
6490seen in the latest scan from earlier findings that remain open:6599seen in the latest scan from earlier findings that remain open:
6491 6600
6520 onWorkerStatus(status) {6629 onWorkerStatus(status) {
6521 console.log(status.kind, status);6630 console.log(status.kind, status);
6522 },6631 },
6632 onSessionEvent(session) {
6633 console.log(session.threadId, session.worker, session.event["type"]);
6634 },
6523 onReconnect(attempt, maxAttempts) {6635 onReconnect(attempt, maxAttempts) {
6524 console.log(`Reconnect attempt ${attempt} of ${maxAttempts}`);6636 console.log(`Reconnect attempt ${attempt} of ${maxAttempts}`);
6525 },6637 },
6573| `onActivity(activity)` | A command, tool, reasoning step, or message updates. |6685| `onActivity(activity)` | A command, tool, reasoning step, or message updates. |
6574| `onProgress(progress)` | The scan phase or reviewed file count changes. |6686| `onProgress(progress)` | The scan phase or reviewed file count changes. |
6575| `onWorkerStatus(status)` | Worker preflight or dispatch status changes. |6687| `onWorkerStatus(status)` | Worker preflight or dispatch status changes. |
6688| `onSessionEvent(session)` | A scan or worker session emits an event. |
6576| `onCost(cost)` | An updated estimated scan cost is available. |6689| `onCost(cost)` | An updated estimated scan cost is available. |
6577| `onWarning(warning)` | The scan reports a warning. |6690| `onWarning(warning)` | The scan reports a warning. |
6578| `onObserverError(observer, error)` | Another scan lifecycle callback raises an error. |6691| `onObserverError(observer, error)` | Another scan lifecycle callback raises an error. |
6580Trusted Access status is `granted`, `not_granted`, or `unknown`. Missing or6693Trusted Access status is `granted`, `not_granted`, or `unknown`. Missing or
6581unknown access also triggers `onWarning`.6694unknown access also triggers `onWarning`.
6582 6695
6696`onSessionEvent` receives events that aren't redacted and can contain source
6697code or credentials. Filter them before sending them to shared logs or other
6698services.
6699
6583#### Configure the runtime and credentials6700#### Configure the runtime and credentials
6584 6701
6585Pass runtime configuration when you need a specific plugin, interpreter, or6702Pass runtime configuration when you need a specific plugin, interpreter, or
17931 18048
17932Source: [Worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees.md)18049Source: [Worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees.md)
17933 18050
17934In the ChatGPT desktop app, worktrees let Codex run multiple independent chats in the same project without interfering with each other. For Git repositories, [scheduled tasks](https://learn.chatgpt.com/docs/automations) can run on dedicated background worktrees so they don't conflict with your ongoing work. In non-version-controlled projects, scheduled tasks run directly in the project directory. You can also start chats in a worktree manually and use Handoff to move a chat between Local and Worktree.18051Worktrees let Codex run multiple independent chats in the same project without interfering with each other. The repository, worktree, and commands remain on the computer or remote development environment that contains the project. You can work directly in the ChatGPT desktop app, or use [Remote](https://learn.chatgpt.com/docs/remote) in the ChatGPT mobile app to start, guide, approve, and review worktree chats on a connected computer.
18052
18053For Git repositories, [scheduled tasks](https://learn.chatgpt.com/docs/automations) can run on dedicated background worktrees so they don't conflict with your ongoing work. In non-version-controlled projects, scheduled tasks run directly in the project directory. You can also start chats in a worktree manually and use Handoff to move a chat between Local and Worktree.
17935 18054
17936Worktrees are available only in Codex in the ChatGPT desktop app. Select18055Worktrees don't run locally on your phone. With Remote, the mobile app
17937**Codex** before you start a chat in a worktree.18056controls Codex on your connected computer, where the repository and worktree
18057remain, or in the remote development environment that computer uses. The
18058desktop-specific instructions below apply on the connected computer.
17938 18059
17939#### What's a worktree18060#### What's a worktree
17940 18061
