Documentation — Spybara

codex-manual.md +181 −83

Details

3909 3909

3910#### How do deep-scan time limits work3910#### How do deep-scan time limits work

3911 3911

3912Set a discovery deadline when starting a deep scan:3912Set a worker deadline when starting a deep scan:

3913 3913

3914```bash3914```bash

3915npx @openai/codex-security scan . --mode deep --max-time-hours 1.53915npx @openai/codex-security scan . --mode deep --max-time-hours 1.5

3916```3916```

3917 3917

3918The default is `96` hours. Use any positive value up to `96`, including3918The default is `96` hours. Use any positive value up to `96`, including

3919fractions. The limit applies only to discovery, so validation and reporting3919fractions. At the deadline, Codex Security stops unfinished workers, keeps

3920can continue after the deadline. If no source review finishes, the report3920completed standard-scan results, and aggregates them into the final report. If

3921records partial coverage and the CLI returns exit code `2`.3921no worker finishes source review, the report records partial coverage and the

3922CLI returns exit code `2`.

3922 3923

3923For persistent settings or bulk campaigns, set `max_time_hours` under3924For persistent settings or bulk campaigns, set `max_time_hours` under

3924`[deep_scan]` in the [deep-scan3925`[deep_scan]` in the [deep-scan

3933```3934```

3934 3935

3935The limit is an estimate, not a hard spending cap. Requests already in3936The limit is an estimate, not a hard spending cap. Requests already in

3936progress can finish above it. If a deep scan reaches the limit after discovery3937progress can finish above it. If a deep scan reaches the limit after Codex

3937finishes, the CLI saves the completed report with partial coverage and exits3938Security aggregates completed worker results, the CLI saves the completed

3938with code `2`. Otherwise, it preserves any available partial output.3939report with partial coverage and exits with code `2`. Otherwise, it preserves

3940any available partial output.

3939 3941

3940#### Can scans check commits and pull requests3942#### Can scans check commits and pull requests

3941 3943

4191npx @openai/codex-security scan "$REPOSITORY" --mode deep4193npx @openai/codex-security scan "$REPOSITORY" --mode deep

4192```4194```

4193 4195

4194To control discovery workers, subagents, and when the scan stops:4196To control workers, subagents, and when the scan stops:

4195 4197

4196```bash4198```bash

4197npx @openai/codex-security scan "$REPOSITORY" \4199npx @openai/codex-security scan "$REPOSITORY" \

4204```4206```

4205 4207

4206These options require deep mode, which supports repository and path targets,4208These options require deep mode, which supports repository and path targets,

4207not diff or working-tree scans. Here, `--workers` controls discovery workers4209not diff or working-tree scans. Here, `--workers` controls independent

4208within one scan; `bulk-scan --workers` controls concurrent repository scans.4210standard-scan workers within one scan; `bulk-scan --workers` controls concurrent

4209`--max-time-hours` accepts a positive number up to `96`, including fractional4211repository scans. `--max-time-hours` accepts a positive number up to `96`,

4210hours. When discovery reaches that limit, the scan preserves completed work4212including fractional hours. At the limit, the scan stops unfinished workers,

4211and continues with validation and reporting.4213preserves completed scan results, and aggregates them into the final report.

4212 4214

4213#### Add architecture and security context4215#### Add architecture and security context

4214 4216

4249```4251```

4250 4252

4251Requests already in progress can finish slightly above the limit. If a deep4253Requests already in progress can finish slightly above the limit. If a deep

4252scan reaches the limit after discovery finishes, the CLI saves the completed4254scan reaches the limit after Codex Security aggregates completed worker

4253report, marks its coverage as `partial`, and returns exit code `2`. If the4255results, the CLI saves the completed report, marks its coverage as `partial`,

4254scan can't produce a completed report, any available partial output stays on4256and returns exit code `2`. If the scan can't produce a completed report, any

4255disk.4257available partial output stays on disk.

4256 4258

4257#### Scan changes before each commit4259#### Scan changes before each commit

4258 4260

4638 4640

4639#### Configure deep scans4641#### Configure deep scans

4640 4642

4641Use these options with `--mode deep` to control discovery concurrency and4643Use these options with `--mode deep` to control worker concurrency and runtime:

4642runtime:

4643 4644

4644| Argument | Description |4645| Argument | Description |

4645| ------------------------ | ----------------------------------------------------------------------- |4646| ------------------------ | -------------------------------------------------------------------------------------- |

4651 4652

4652`--subagents` accepts zero or a positive integer. `--max-time-hours` accepts a4653`--subagents` accepts zero or a positive integer. `--max-time-hours` accepts a

4653positive number no greater than `96`. The remaining options require a positive4654positive number no greater than `96`. The remaining options require a positive

4654integer. These options aren't available for standard scans.4655integer. These options aren't available for standard scans.

4655 4656

4656For example, use two discovery workers, allow up to ten runs, and stop4657For example, use two workers, allow up to ten runs, and stop worker execution

4657discovery after 1.5 hours:4658after 1.5 hours:

4658 4659

4659```bash4660```bash

4660npx @openai/codex-security scan . \4661npx @openai/codex-security scan . \

4666 --max-time-hours 1.54667 --max-time-hours 1.5

4667```4668```

4668 4669

4669The time limit applies only to discovery. When it expires, the scan stops4670When the time limit expires, the scan stops unfinished workers, keeps completed

4670unfinished discovery, keeps completed discovery results, and continues with4671scan results, and aggregates them into the final report. If no worker finishes

4671validation and reporting. If no source review finishes, the scan records4672source review, the scan records partial coverage and returns exit code `2`.

4672partial coverage and returns exit code `2`.

4673 4673

4674Set persistent defaults in `~/.codex/codex-security/config.toml`, or in4674Set persistent defaults in `~/.codex/codex-security/config.toml`, or in

4675`$CODEX_HOME/codex-security/config.toml` when you set `CODEX_HOME`:4675`$CODEX_HOME/codex-security/config.toml` when you set `CODEX_HOME`:

4684```4684```

4685 4685

4686Command-line options override these defaults. `scan --workers` controls4686Command-line options override these defaults. `scan --workers` controls

4687discovery workers within one scan; `bulk-scan --workers` controls concurrent4687independent standard-scan workers within one deep scan; `bulk-scan --workers`

4688repository scans. Set `stop_after_consecutive_errors` only in the TOML file;4688controls concurrent repository scans. Set `stop_after_consecutive_errors` only

4689its default is `3`.4689in the TOML file; its default is `3`.

4690 4690

4691#### Add security context4691#### Add security context

4692 4692

4743 4743

4744The cost limit is an estimate, not a hard spending cap. Requests already in4744The cost limit is an estimate, not a hard spending cap. Requests already in

4745progress can finish slightly above the limit. If a deep scan reaches the limit4745progress can finish slightly above the limit. If a deep scan reaches the limit

4746after discovery finishes, the CLI seals the available results, marks coverage4746after Codex Security aggregates completed worker results, the CLI seals the

4747as `partial`, and returns exit code `2`. Otherwise, it returns `2` and leaves4747available results, marks coverage as `partial`, and returns exit code `2`.

4748any available partial output on disk.4748Otherwise, it returns `2` and leaves any available partial output on disk.

4749 4749

4750When you omit `--output-dir`, results persist under4750When you omit `--output-dir`, results persist under

4751`$CODEX_HOME/state/plugins/codex-security/scans/`. `CODEX_HOME`4751`$CODEX_HOME/state/plugins/codex-security/scans/`. `CODEX_HOME`

5643 5643

5644Use this changelog to see what changed in the Codex Security plugin.5644Use this changelog to see what changed in the Codex Security plugin.

5645 5645

5646**Latest plugin version:** `0.1.19`.5646**Latest plugin version:** `0.1.20`.

5647 5647

5648Check the plugin version in your current Codex environment before you use a5648Check the plugin version in your current Codex environment before you use a

5649feature from a newer release.5649feature from a newer release.

5652SDK users can run `npx @openai/codex-security info --json` to check the5652SDK users can run `npx @openai/codex-security info --json` to check the

5653package and bundled plugin versions together.5653package and bundled plugin versions together.

5654 5654

5655#### 0.1.20 (August 17, 2026)

5656

5657#### Run deep scans as complete independent audits

5658

5659- Run each deep scan worker through the same end-to-end audit used by standard

5660 scans, including threat modeling, validation, attack-path analysis, and

5661 coverage reporting.

5662- Combine completed worker reports into one scan while preserving configured

5663 time limits, partial coverage, restart recovery, and cancellation.

5664- Use four concurrent workers by default, stop after four consecutive completed

5665 scans add no new findings, and limit a deep scan to 40 worker runs. Existing

5666 `workers = "auto"` settings now resolve to four workers. See

5667 [Configure deep-scan runtime](https://learn.chatgpt.com/docs/security/plugin/deep-scans#configure-deep-scan-runtime).

5668- Resume workers that finished source review but lost their final draft instead

5669 of repeating the complete audit.

5670

5671#### Check Trusted Access for Cyber before hosted scans

5672

5673- In Codex hosts that expose the Codex Security Access app, check Trusted Access

5674 status before standard, change, and deep scans begin.

5675- See a prominent warning when protected scan output might not be available,

5676 with an enrollment link when access isn't granted.

5677- Continue the scan when the check can't verify Trusted Access status or access

5678 isn't granted; the advisory doesn't control whether the scan runs.

5679- The public CLI and SDK packages don't run this advisory in `0.1.20`.

5680

5681#### Run deep scans in more environments

5682

5683- Launch deep scan workers from packaged CLI and SDK installations, including

5684 Windows installations without a global `codex` executable.

5685- Keep standalone CLI and SDK deep scan settings isolated from other running

5686 scans.

5687- Keep non-interactive approval settings in nested deep scan workers.

5688

5689#### Preserve scan results through more failures

5690

5691- Preserve more saved scans and completed worker results across restart,

5692 archive, and handoff recovery paths.

5693- Recover valid findings from older or incomplete scan data.

5694- Complete scans when independent coverage reports overlap.

5695- Report cached input correctly in token usage totals across current and older

5696 provider responses.

5697

5655#### 0.1.19 (August 13, 2026)5698#### 0.1.19 (August 13, 2026)

5656 5699

5657#### Set a time limit for deep scans5700#### Set a time limit for deep scans

6327```6370```

6328 6371

6329Deep mode supports repository and path targets. Use standard mode for diff and6372Deep mode supports repository and path targets. Use standard mode for diff and

6330working-tree scans. The optional settings control concurrent discovery workers,6373working-tree scans. The optional settings control concurrent independent

6331subagents per worker, consecutive discovery runs without new findings, and the6374standard-scan workers, subagents per worker, consecutive completed worker scans

6332total number and duration of discovery runs. They require `mode: "deep"`.6375without new findings, and the total number and duration of worker runs. They

6376require `mode: "deep"`.

6333 6377

6334`maxTimeHours` defaults to `96` and accepts a positive number up to `96`,6378`maxTimeHours` defaults to `96` and accepts a positive number up to `96`,

6335including fractional hours. At the deadline, Codex Security stops unfinished6379including fractional hours. At the deadline, Codex Security stops unfinished

6336discovery, keeps completed discovery results, and continues with validation6380workers, keeps completed scan results, and aggregates them into the final

6337and reporting. Review `result.coverage.completeness` before treating a6381report. Review `result.coverage.completeness` before treating a time-limited

6338time-limited scan as evidence of full coverage.6382scan as evidence of full coverage.

6339 6383

6340#### Add a security knowledge base6384#### Add a security knowledge base

6341 6385

6389 6433

6390The limit estimates spending but isn't a hard cap, so requests already in6434The limit estimates spending but isn't a hard cap, so requests already in

6391progress can finish slightly above it. If a deep scan reaches the limit after6435progress can finish slightly above it. If a deep scan reaches the limit after

6392discovery finishes, `run` returns a result with `coverage.completeness` set to6436Codex Security aggregates completed worker results, `run` returns a result

6393`"partial"` and reports the budget warning through `onWarning`.6437with `coverage.completeness` set to `"partial"` and reports the budget warning

6438through `onWarning`.

6394 6439

6395If the scan can't produce a completed partial result, `run` throws6440If the scan can't produce a completed partial result, `run` throws

6396`ScanCostLimitExceededError` and preserves any available output.6441`ScanCostLimitExceededError` and preserves any available output.

7557```7602```

7558 7603

7560| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |7605| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |

7562| `subagents` | `3` | Number of subagents each discovery worker may start. Set `0` to disable them. |7607| `subagents` | `3` | Number of subagents each worker may start. Set `0` to disable them. |

7563| `stop_after_no_new` | `6` | Stop discovery after this many consecutive runs produce no new candidates. |7608| `stop_after_no_new` | `4` | Stop after this many consecutive completed worker scans produce no new findings. |

7564| `stop_after_consecutive_errors` | `3` | Stop discovery after this many consecutive worker errors. |7609| `stop_after_consecutive_errors` | `3` | Stop after this many consecutive worker errors. |

7565| `max_discovery_runs` | `60` | Limit on discovery runs before the scan moves to validation. |7610| `max_discovery_runs` | `40` | Limit the number of independent standard-scan runs before aggregation. |

7566| `max_time_hours` | `96` | Limit discovery to a positive number of hours up to `96`; use fractions as needed. |7611| `max_time_hours` | `96` | Limit worker execution to a positive number of hours up to `96`; use fractions as needed. |

7567 7612

7568Lower values can reduce scan time and token use but may miss findings.7613Lower values can reduce scan time and token use but may miss findings.

7569Configuration changes apply to new deep scans, not scans already in progress.7614Configuration changes apply to new deep scans, not scans already in progress.

7570 7615

7571The time limit applies only to discovery. When it expires, Codex Security7616When the time limit expires, Codex Security stops unfinished workers, keeps

7572stops unfinished discovery, keeps completed results, and continues with7617completed scan results, and aggregates them into the final report. If no worker

7573validation and reporting. If no source review finishes before the deadline,7618finishes source review before the deadline, the report records partial

7574the report records partial coverage.7619coverage.

7575 7620

7576The `max_time_hours` setting requires plugin version `0.1.19` or later. See the7621The `max_time_hours` setting requires plugin version `0.1.19` or later. See the

7577[plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) for release details.7622[plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) for release details.

76094. Open **Additional context** for concrete attack vectors, sensitive76544. Open **Additional context** for concrete attack vectors, sensitive

7610 application areas, or repository context that the code can't reveal.7655 application areas, or repository context that the code can't reveal.

76115. Select **Start scan**.76565. Select **Start scan**.

76126. Review any setup or capability warning before you approve a configuration

7613 change.

~~7614~~

7615Deep scans require delegated workers. If the current runtime doesn't meet the

7616capability requirements, use a standard scan or try again when enough capacity

7617is available.

7618 7657

7619Discovery workers inherit your selected model and reasoning settings. Follow7658Deep scan workers inherit your selected model and reasoning settings. Each

7620the saved scan from **Scans**, or select **View activity** to inspect its Codex7659worker runs a complete standard scan, and Codex Security aggregates the

7621task. Check the [plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you7660completed results. Follow the saved scan from **Scans**, or select **View

7622update the plugin or start a long-running scan.7661activity** to inspect its Codex task. Check the [plugin

7662changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you update the plugin or

7663start a long-running scan.

7623 7664

7624 Track the active deep-scan phase and inspect its Codex activity before7665 Track the active deep-scan phase and inspect its Codex activity before

7625 reviewing the completed result.7666 reviewing the completed result.

7745```7786```

7746 7787

7747`--workers` controls concurrent repository scans and defaults to `4`. It does7788`--workers` controls concurrent repository scans and defaults to `4`. It does

7748not set the number of discovery workers within each deep scan; configure those7789not set the number of independent standard-scan workers within each deep scan;

7749limits through [`[deep_scan]`](/codex/security/cli/reference#configure-deep-scans).7790configure those limits through

7750Use `--mode deep` to select deep scanning for rows without their own `mode`.7791[`[deep_scan]`](/codex/security/cli/reference#configure-deep-scans). Use `--mode

7751Each CSV row can still choose its own scan mode and repository scope.7792deep` to select deep scanning for rows without their own `mode`. Each CSV row

7793can still choose its own scan mode and repository scope.

7752 7794

7753Set `[deep_scan].max_time_hours` to limit discovery for each deep scan in the7795Set `[deep_scan].max_time_hours` to limit worker execution for each deep scan in

7754campaign. The `--max-time-hours` flag works with `scan`, not `bulk-scan`.7796the campaign. The `--max-time-hours` flag works with `scan`, not `bulk-scan`.

7755 7797

7756The CLI checks out each pinned revision, scans the selected target, records the7798The CLI checks out each pinned revision, scans the selected target, records the

7757result, and removes the temporary repository checkout. A repository counts as7799result, and removes the temporary repository checkout. A repository counts as

14166 14208

14167[Computer History](https://learn.chatgpt.com/docs/customization/computer-history) is an opt-in macOS14209[Computer History](https://learn.chatgpt.com/docs/customization/computer-history) is an opt-in macOS

14168desktop feature that can turn activity across allowed apps and websites into14210desktop feature that can turn activity across allowed apps and websites into

14169memories and a timeline. It records interaction events rather than screenshots14211memories and a timeline. It uses interaction events, along with text and other

14170or audio.14212context available through macOS accessibility features. It does not include

14213screenshots in your history or record audio.

14171 14214

14172Review what Computer History includes before enabling it. You can pause it,14215Review what Computer History includes before enabling it. You can pause it,

14173exclude apps and websites, inspect or delete individual timeline items, and14216exclude apps and websites, inspect or delete individual timeline items, and

21347and can inspect or delete your history at any time.21390and can inspect or delete your history at any time.

21348 21391

21349Computer History replaces the earlier Chronicle research preview, but it is a21392Computer History replaces the earlier Chronicle research preview, but it is a

21350rebuilt system rather than a rename. Chronicle used screenshots. Computer21393rebuilt system rather than a rename. It uses interaction events, along with

21351History records interaction events and does not capture your screen or audio.21394text and other context available through macOS accessibility features, to

21395create summaries you can review and delete. It does not include screenshots in

21396your history or record audio, and private-mode web browsing activity is never

21397included.

21352 21398

21353#### How Computer History helps21399#### How Computer History helps

21354 21400

21380History periodically turns these events into text summaries and local memory21426History periodically turns these events into text summaries and local memory

21381files.21427files.

21382 21428

21383Computer History does **not** capture screenshots, screen recordings,21429Computer History does not include screenshots in your history or record

21384microphone input, or system audio. Private-mode web browsing activity is never21430microphone input or system audio. Private-mode web browsing activity is never

21385included.21431included.

21386 21432

21387In **Settings > Computer history > History**, the timeline groups summaries by21433In **Settings > Computer history > History**, the timeline groups summaries by

21494#### Privacy and local storage21540#### Privacy and local storage

21495 21541

21496Computer History stores the interaction-event stream temporarily on your Mac so21542Computer History stores the interaction-event stream temporarily on your Mac so

21497ChatGPT and Codex can generate memories and build suggested workflows. It does21543ChatGPT and Codex can generate memories and build suggested workflows. The

21498**not** capture screenshots, screen recordings, microphone input, or system21544stream can include activity such as clicks and typing, along with text and other

21499audio.21545context available through macOS accessibility features. Computer History does

21546not include screenshots in your history or record microphone input or system

21547audio. Private-mode web browsing activity is never included.

21500 21548

21501Temporary event files are retained for up to 48 hours. Generated memory files21549Temporary event files are retained for up to 48 hours. Generated memory files

21502remain on your filesystem until you delete or clear them, and you can reveal21550remain on your filesystem until you delete or clear them, and you can reveal

24579 - Environment variables24627 - Environment variables

24580- **Streamable HTTP servers**: Servers that you access at an address.24628- **Streamable HTTP servers**: Servers that you access at an address.

24581 - Bearer token authentication24629 - Bearer token authentication

24582 - OAuth authentication24630 - OAuth authentication, including Client ID Metadata Documents (CIMD) and

24631 Dynamic Client Registration (DCR)

24583 - ChatGPT session authentication for trusted first-party servers24632 - ChatGPT session authentication for trusted first-party servers

24584- **Server instructions**: Codex reads the MCP `instructions` field returned during initialization and uses it as server-wide guidance alongside the server's tools.24633- **Server instructions**: Codex reads the MCP `instructions` field returned during initialization and uses it as server-wide guidance alongside the server's tools.

24585 24634

24715server-advertised scopes during OAuth login. Otherwise, Codex falls back to the24764server-advertised scopes during OAuth login. Otherwise, Codex falls back to the

24716scopes configured in `config.toml`.24765scopes configured in `config.toml`.

24717 24766

24767#### OAuth client registration

24768

24769Codex supports [OAuth Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)

24770and Dynamic Client Registration (DCR). By default, Codex automatically chooses

24771CIMD when the authorization server advertises

24772`client_id_metadata_document_supported: true`, includes `none` in

24773`token_endpoint_auth_methods_supported`, and the callback uses a supported

24774loopback URL. Otherwise, Codex uses DCR when available. A configured OAuth client

24775ID always takes precedence and skips client registration.

24776

24777For CIMD, Codex uses a ChatGPT-hosted metadata document specific to the MCP

24778server:

24779

24780```text

24781https://chatgpt.com/oauth/codex/<callback_id>/client.json

24782```

24783

24784Codex derives ``from the MCP server URL and includes it in the

24785loopback redirect URI, such as`http://127.0.0.1:/callback/`. The metadata document registers

24786the matching loopback URI without a port. Authorization servers must accept the

24787port selected at login while matching the host and path exactly, as required by

24788[RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html#section-7.3). Custom

24789callback hosts, paths, or query parameters require DCR or a configured OAuth

24790client ID.

24791

24792Support for a stable, shared CIMD document is in development and coming soon:

24793

24794```text

24795https://chatgpt.com/oauth/codex/client.json

24796```

24797

24798Codex will use the stable document with the shared `/callback` path when the

24799authorization server advertises

24800`authorization_response_iss_parameter_supported: true`, provides a valid

24801`issuer` in its metadata, and includes a matching `iss` in authorization

24802responses. Servers without issuer-bound responses will continue using the

24803callback-specific document.

24804

24805To choose a registration method for one CLI login, use

24806`--oauth-client-registration`:

24807

24808```bash

24809codex mcp login <server-name> --oauth-client-registration cimd

24810codex mcp login <server-name> --oauth-client-registration dcr

24811```

24812

24813The default is `auto`. Registration choices apply only to the current login and

24814aren't stored in `config.toml`.

24815

24718#### config.toml examples24816#### config.toml examples

24719 24817

24720```toml24818```toml

customization/computer-history.md +12 −7

Details

21and can inspect or delete your history at any time.21and can inspect or delete your history at any time.

22 22

23Computer History replaces the earlier Chronicle research preview, but it is a23Computer History replaces the earlier Chronicle research preview, but it is a

~~24rebuilt system rather than a rename. Chronicle used screenshots. Computer~~24rebuilt system rather than a rename. It uses interaction events, along with

~~25History records interaction events and does not capture your screen or audio.~~25text and other context available through macOS accessibility features, to

26create summaries you can review and delete. It does not include screenshots in

27your history or record audio, and private-mode web browsing activity is never

28included.

26 29

27<Illustration description="Computer History timeline showing activity summaries, contributing apps, and suggested skills and automations">30<Illustration description="Computer History timeline showing activity summaries, contributing apps, and suggested skills and automations">

28 <ComputerHistoryTimelineIllustration />31 <ComputerHistoryTimelineIllustration />

94History periodically turns these events into text summaries and local memory97History periodically turns these events into text summaries and local memory

95files.98files.

96 99

~~97Computer History does **not** capture screenshots, screen recordings,~~100Computer History does not include screenshots in your history or record

~~98microphone input, or system audio. Private-mode web browsing activity is never~~101microphone input or system audio. Private-mode web browsing activity is never

99included.102included.

100 103

101In **Settings > Computer history > History**, the timeline groups summaries by104In **Settings > Computer history > History**, the timeline groups summaries by

208## Privacy and local storage211## Privacy and local storage

209 212

210Computer History stores the interaction-event stream temporarily on your Mac so213Computer History stores the interaction-event stream temporarily on your Mac so

211ChatGPT and Codex can generate memories and build suggested workflows. It does214ChatGPT and Codex can generate memories and build suggested workflows. The

212**not** capture screenshots, screen recordings, microphone input, or system215stream can include activity such as clicks and typing, along with text and other

213audio.216context available through macOS accessibility features. Computer History does

217not include screenshots in your history or record microphone input or system

218audio. Private-mode web browsing activity is never included.

214 219

215Temporary event files are retained for up to 48 hours. Generated memory files220Temporary event files are retained for up to 48 hours. Generated memory files

216remain on your filesystem until you delete or clear them, and you can reveal221remain on your filesystem until you delete or clear them, and you can reveal

mcp.md +52 −1

Details

25 - Environment variables25 - Environment variables

26- **Streamable HTTP servers**: Servers that you access at an address.26- **Streamable HTTP servers**: Servers that you access at an address.

27 - Bearer token authentication27 - Bearer token authentication

~~28 - OAuth authentication~~28 - OAuth authentication, including Client ID Metadata Documents (CIMD) and

29 Dynamic Client Registration (DCR)

29 - ChatGPT session authentication for trusted first-party servers30 - ChatGPT session authentication for trusted first-party servers

30- **Server instructions**: Codex reads the MCP `instructions` field returned during initialization and uses it as server-wide guidance alongside the server's tools.31- **Server instructions**: Codex reads the MCP `instructions` field returned during initialization and uses it as server-wide guidance alongside the server's tools.

31 32

193server-advertised scopes during OAuth login. Otherwise, Codex falls back to the194server-advertised scopes during OAuth login. Otherwise, Codex falls back to the

194scopes configured in `config.toml`.195scopes configured in `config.toml`.

195 196

197#### OAuth client registration

198

199Codex supports [OAuth Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)

200and Dynamic Client Registration (DCR). By default, Codex automatically chooses

201CIMD when the authorization server advertises

202`client_id_metadata_document_supported: true`, includes `none` in

203`token_endpoint_auth_methods_supported`, and the callback uses a supported

204loopback URL. Otherwise, Codex uses DCR when available. A configured OAuth client

205ID always takes precedence and skips client registration.

206

207For CIMD, Codex uses a ChatGPT-hosted metadata document specific to the MCP

208server:

209

210```text

211https://chatgpt.com/oauth/codex/<callback_id>/client.json

212```

213

214Codex derives `<callback_id>` from the MCP server URL and includes it in the

215loopback redirect URI, such as

216`http://127.0.0.1:<port>/callback/<callback_id>`. The metadata document registers

217the matching loopback URI without a port. Authorization servers must accept the

218port selected at login while matching the host and path exactly, as required by

219[RFC 8252](https://www.rfc-editor.org/rfc/rfc8252.html#section-7.3). Custom

220callback hosts, paths, or query parameters require DCR or a configured OAuth

221client ID.

222

223Support for a stable, shared CIMD document is in development and coming soon:

224

225```text

226https://chatgpt.com/oauth/codex/client.json

227```

228

229Codex will use the stable document with the shared `/callback` path when the

230authorization server advertises

231`authorization_response_iss_parameter_supported: true`, provides a valid

232`issuer` in its metadata, and includes a matching `iss` in authorization

233responses. Servers without issuer-bound responses will continue using the

234callback-specific document.

235

236To choose a registration method for one CLI login, use

237`--oauth-client-registration`:

238

239```bash

240codex mcp login <server-name> --oauth-client-registration cimd

241codex mcp login <server-name> --oauth-client-registration dcr

242```

243

244The default is `auto`. Registration choices apply only to the current login and

245aren't stored in `config.toml`.

246

196#### config.toml examples247#### config.toml examples

197 248

198```toml249```toml

personalize.md +3 −2

Details

34 34

35[Computer History](https://learn.chatgpt.com/docs/customization/computer-history) is an opt-in macOS35[Computer History](https://learn.chatgpt.com/docs/customization/computer-history) is an opt-in macOS

36desktop feature that can turn activity across allowed apps and websites into36desktop feature that can turn activity across allowed apps and websites into

~~37memories and a timeline. It records interaction events rather than screenshots~~37memories and a timeline. It uses interaction events, along with text and other

~~38or audio.~~38context available through macOS accessibility features. It does not include

39screenshots in your history or record audio.

39 40

40Review what Computer History includes before enabling it. You can pause it,41Review what Computer History includes before enabling it. You can pause it,

41exclude apps and websites, inspect or delete individual timeline items, and42exclude apps and websites, inspect or delete individual timeline items, and

security/cli.md +10 −10

Details

225npx @openai/codex-security scan "$REPOSITORY" --mode deep225npx @openai/codex-security scan "$REPOSITORY" --mode deep

226```226```

227 227

228To control discovery workers, subagents, and when the scan stops:228To control workers, subagents, and when the scan stops:

229 229

230```bash230```bash

231npx @openai/codex-security scan "$REPOSITORY" \231npx @openai/codex-security scan "$REPOSITORY" \

238```238```

239 239

240These options require deep mode, which supports repository and path targets,240These options require deep mode, which supports repository and path targets,

241not diff or working-tree scans. Here, `--workers` controls discovery workers241not diff or working-tree scans. Here, `--workers` controls independent

242within one scan; `bulk-scan --workers` controls concurrent repository scans.242standard-scan workers within one scan; `bulk-scan --workers` controls concurrent

243`--max-time-hours` accepts a positive number up to `96`, including fractional243repository scans. `--max-time-hours` accepts a positive number up to `96`,

244hours. When discovery reaches that limit, the scan preserves completed work244including fractional hours. At the limit, the scan stops unfinished workers,

245and continues with validation and reporting.245preserves completed scan results, and aggregates them into the final report.

246 246

247## Add architecture and security context247## Add architecture and security context

248 248

283```283```

284 284

285Requests already in progress can finish slightly above the limit. If a deep285Requests already in progress can finish slightly above the limit. If a deep

286scan reaches the limit after discovery finishes, the CLI saves the completed286scan reaches the limit after Codex Security aggregates completed worker

287report, marks its coverage as `partial`, and returns exit code `2`. If the287results, the CLI saves the completed report, marks its coverage as `partial`,

288scan can't produce a completed report, any available partial output stays on288and returns exit code `2`. If the scan can't produce a completed report, any

289disk.289available partial output stays on disk.

290 290

291## Scan changes before each commit291## Scan changes before each commit

292 292

security/cli/bulk-scans.md +8 −7

Details

101```101```

102 102

103`--workers` controls concurrent repository scans and defaults to `4`. It does103`--workers` controls concurrent repository scans and defaults to `4`. It does

104not set the number of discovery workers within each deep scan; configure those104not set the number of independent standard-scan workers within each deep scan;

105limits through [`[deep_scan]`](/codex/security/cli/reference#configure-deep-scans).105configure those limits through

106Use `--mode deep` to select deep scanning for rows without their own `mode`.106[`[deep_scan]`](/codex/security/cli/reference#configure-deep-scans). Use `--mode

107Each CSV row can still choose its own scan mode and repository scope.107deep` to select deep scanning for rows without their own `mode`. Each CSV row

~~108~~ 108can still choose its own scan mode and repository scope.

109Set `[deep_scan].max_time_hours` to limit discovery for each deep scan in the109

110campaign. The `--max-time-hours` flag works with `scan`, not `bulk-scan`.110Set `[deep_scan].max_time_hours` to limit worker execution for each deep scan in

111the campaign. The `--max-time-hours` flag works with `scan`, not `bulk-scan`.

111 112

112The CLI checks out each pinned revision, scans the selected target, records the113The CLI checks out each pinned revision, scans the selected target, records the

113result, and removes the temporary repository checkout. A repository counts as114result, and removes the temporary repository checkout. A repository counts as

security/cli/faq.md +9 −7

Details

237 237

238### How do deep-scan time limits work238### How do deep-scan time limits work

239 239

240Set a discovery deadline when starting a deep scan:240Set a worker deadline when starting a deep scan:

241 241

242```bash242```bash

243npx @openai/codex-security scan . --mode deep --max-time-hours 1.5243npx @openai/codex-security scan . --mode deep --max-time-hours 1.5

244```244```

245 245

246The default is `96` hours. Use any positive value up to `96`, including246The default is `96` hours. Use any positive value up to `96`, including

247fractions. The limit applies only to discovery, so validation and reporting247fractions. At the deadline, Codex Security stops unfinished workers, keeps

248can continue after the deadline. If no source review finishes, the report248completed standard-scan results, and aggregates them into the final report. If

249records partial coverage and the CLI returns exit code `2`.249no worker finishes source review, the report records partial coverage and the

250CLI returns exit code `2`.

250 251

251For persistent settings or bulk campaigns, set `max_time_hours` under252For persistent settings or bulk campaigns, set `max_time_hours` under

252`[deep_scan]` in the [deep-scan253`[deep_scan]` in the [deep-scan

261```262```

262 263

263The limit is an estimate, not a hard spending cap. Requests already in264The limit is an estimate, not a hard spending cap. Requests already in

264progress can finish above it. If a deep scan reaches the limit after discovery265progress can finish above it. If a deep scan reaches the limit after Codex

265finishes, the CLI saves the completed report with partial coverage and exits266Security aggregates completed worker results, the CLI saves the completed

266with code `2`. Otherwise, it preserves any available partial output.267report with partial coverage and exits with code `2`. Otherwise, it preserves

268any available partial output.

267 269

268### Can scans check commits and pull requests270### Can scans check commits and pull requests

269 271

security/cli/reference.md +18 −20

Details

244 244

245### Configure deep scans245### Configure deep scans

246 246

247Use these options with `--mode deep` to control discovery concurrency and247Use these options with `--mode deep` to control worker concurrency and runtime:

248runtime:

249 248

250| Argument | Description |249| Argument | Description |

251| ------------------------ | ----------------------------------------------------------------------- |250| ------------------------ | -------------------------------------------------------------------------------------- |

257 256

258`--subagents` accepts zero or a positive integer. `--max-time-hours` accepts a257`--subagents` accepts zero or a positive integer. `--max-time-hours` accepts a

259positive number no greater than `96`. The remaining options require a positive258positive number no greater than `96`. The remaining options require a positive

260integer. These options aren't available for standard scans.259integer. These options aren't available for standard scans.

261 260

262For example, use two discovery workers, allow up to ten runs, and stop261For example, use two workers, allow up to ten runs, and stop worker execution

263discovery after 1.5 hours:262after 1.5 hours:

264 263

265```bash264```bash

266npx @openai/codex-security scan . \265npx @openai/codex-security scan . \

272 --max-time-hours 1.5271 --max-time-hours 1.5

273```272```

274 273

275The time limit applies only to discovery. When it expires, the scan stops274When the time limit expires, the scan stops unfinished workers, keeps completed

276unfinished discovery, keeps completed discovery results, and continues with275scan results, and aggregates them into the final report. If no worker finishes

277validation and reporting. If no source review finishes, the scan records276source review, the scan records partial coverage and returns exit code `2`.

278partial coverage and returns exit code `2`.

279 277

280Set persistent defaults in `~/.codex/codex-security/config.toml`, or in278Set persistent defaults in `~/.codex/codex-security/config.toml`, or in

281`$CODEX_HOME/codex-security/config.toml` when you set `CODEX_HOME`:279`$CODEX_HOME/codex-security/config.toml` when you set `CODEX_HOME`:

290```288```

291 289

292Command-line options override these defaults. `scan --workers` controls290Command-line options override these defaults. `scan --workers` controls

293discovery workers within one scan; `bulk-scan --workers` controls concurrent291independent standard-scan workers within one deep scan; `bulk-scan --workers`

294repository scans. Set `stop_after_consecutive_errors` only in the TOML file;292controls concurrent repository scans. Set `stop_after_consecutive_errors` only

295its default is `3`.293in the TOML file; its default is `3`.

296 294

297### Add security context295### Add security context

298 296

349 347

350The cost limit is an estimate, not a hard spending cap. Requests already in348The cost limit is an estimate, not a hard spending cap. Requests already in

351progress can finish slightly above the limit. If a deep scan reaches the limit349progress can finish slightly above the limit. If a deep scan reaches the limit

352after discovery finishes, the CLI seals the available results, marks coverage350after Codex Security aggregates completed worker results, the CLI seals the

353as `partial`, and returns exit code `2`. Otherwise, it returns `2` and leaves351available results, marks coverage as `partial`, and returns exit code `2`.

354any available partial output on disk.352Otherwise, it returns `2` and leaves any available partial output on disk.

355 353

356When you omit `--output-dir`, results persist under354When you omit `--output-dir`, results persist under

357`$CODEX_HOME/state/plugins/codex-security/scans/<repository>`. `CODEX_HOME`355`$CODEX_HOME/state/plugins/codex-security/scans/<repository>`. `CODEX_HOME`

security/plugin/changelog.md +44 −1

Details

4 4

5Use this changelog to see what changed in the Codex Security plugin.5Use this changelog to see what changed in the Codex Security plugin.

6 6

~~7**Latest plugin version:** `0.1.19`.~~7**Latest plugin version:** `0.1.20`.

8 8

9Check the plugin version in your current Codex environment before you use a9Check the plugin version in your current Codex environment before you use a

10feature from a newer release.10feature from a newer release.

13SDK users can run `npx @openai/codex-security info --json` to check the13SDK users can run `npx @openai/codex-security info --json` to check the

14package and bundled plugin versions together.14package and bundled plugin versions together.

15 15

16## 0.1.20 (August 17, 2026)

18### Run deep scans as complete independent audits

20- Run each deep scan worker through the same end-to-end audit used by standard

21 scans, including threat modeling, validation, attack-path analysis, and

22 coverage reporting.

23- Combine completed worker reports into one scan while preserving configured

24 time limits, partial coverage, restart recovery, and cancellation.

25- Use four concurrent workers by default, stop after four consecutive completed

26 scans add no new findings, and limit a deep scan to 40 worker runs. Existing

27 `workers = "auto"` settings now resolve to four workers. See

28 [Configure deep-scan runtime](https://learn.chatgpt.com/docs/security/plugin/deep-scans#configure-deep-scan-runtime).

29- Resume workers that finished source review but lost their final draft instead

30 of repeating the complete audit.

32### Check Trusted Access for Cyber before hosted scans

34- In Codex hosts that expose the Codex Security Access app, check Trusted Access

35 status before standard, change, and deep scans begin.

36- See a prominent warning when protected scan output might not be available,

37 with an enrollment link when access isn't granted.

38- Continue the scan when the check can't verify Trusted Access status or access

39 isn't granted; the advisory doesn't control whether the scan runs.

40- The public CLI and SDK packages don't run this advisory in `0.1.20`.

42### Run deep scans in more environments

44- Launch deep scan workers from packaged CLI and SDK installations, including

45 Windows installations without a global `codex` executable.

46- Keep standalone CLI and SDK deep scan settings isolated from other running

47 scans.

48- Keep non-interactive approval settings in nested deep scan workers.

50### Preserve scan results through more failures

52- Preserve more saved scans and completed worker results across restart,

53 archive, and handoff recovery paths.

54- Recover valid findings from older or incomplete scan data.

55- Complete scans when independent coverage reports overlap.

56- Report cached input correctly in token usage totals across current and older

57 provider responses.

16## 0.1.19 (August 13, 2026)59## 0.1.19 (August 13, 2026)

17 60

18### Set a time limit for deep scans61### Set a time limit for deep scans

security/plugin/deep-scans.md +17 −21

Details

37```37```

38 38

~~40| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |~~40| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |

~~42| `subagents` | `3` | Number of subagents each discovery worker may start. Set `0` to disable them. |~~42| `subagents` | `3` | Number of subagents each worker may start. Set `0` to disable them. |

~~43| `stop_after_no_new` | `6` | Stop discovery after this many consecutive runs produce no new candidates. |~~43| `stop_after_no_new` | `4` | Stop after this many consecutive completed worker scans produce no new findings. |

~~44| `stop_after_consecutive_errors` | `3` | Stop discovery after this many consecutive worker errors. |~~44| `stop_after_consecutive_errors` | `3` | Stop after this many consecutive worker errors. |

~~45| `max_discovery_runs` | `60` | Limit on discovery runs before the scan moves to validation. |~~45| `max_discovery_runs` | `40` | Limit the number of independent standard-scan runs before aggregation. |

~~46| `max_time_hours` | `96` | Limit discovery to a positive number of hours up to `96`; use fractions as needed. |~~46| `max_time_hours` | `96` | Limit worker execution to a positive number of hours up to `96`; use fractions as needed. |

47 47

48Lower values can reduce scan time and token use but may miss findings.48Lower values can reduce scan time and token use but may miss findings.

49Configuration changes apply to new deep scans, not scans already in progress.49Configuration changes apply to new deep scans, not scans already in progress.

50 50

~~51The time limit applies only to discovery. When it expires, Codex Security~~51When the time limit expires, Codex Security stops unfinished workers, keeps

~~52stops unfinished discovery, keeps completed results, and continues with~~52completed scan results, and aggregates them into the final report. If no worker

~~53validation and reporting. If no source review finishes before the deadline,~~53finishes source review before the deadline, the report records partial

~~54the report records partial coverage.~~54coverage.

55 55

56The `max_time_hours` setting requires plugin version `0.1.19` or later. See the56The `max_time_hours` setting requires plugin version `0.1.19` or later. See the

57[plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) for release details.57[plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) for release details.

914. Open **Additional context** for concrete attack vectors, sensitive914. Open **Additional context** for concrete attack vectors, sensitive

92 application areas, or repository context that the code can't reveal.92 application areas, or repository context that the code can't reveal.

935. Select **Start scan**.935. Select **Start scan**.

~~946. Review any setup or capability warning before you approve a configuration~~

~~95 change.~~

96 94

97</WorkflowSteps>95</WorkflowSteps>

98 96

~~99Deep scans require delegated workers. If the current runtime doesn't meet the~~97Deep scan workers inherit your selected model and reasoning settings. Each

100capability requirements, use a standard scan or try again when enough capacity98worker runs a complete standard scan, and Codex Security aggregates the

101is available.99completed results. Follow the saved scan from **Scans**, or select **View

~~102~~ 100activity** to inspect its Codex task. Check the [plugin

103Discovery workers inherit your selected model and reasoning settings. Follow101changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you update the plugin or

104the saved scan from **Scans**, or select **View activity** to inspect its Codex102start a long-running scan.

105task. Check the [plugin changelog](https://learn.chatgpt.com/docs/security/plugin/changelog) before you

106update the plugin or start a long-running scan.

107 103

108<figure className="not-prose my-8">104<figure className="not-prose my-8">

109 <CodexScreenshot105 <CodexScreenshot

security/sdk.md +10 −8

Details

191```191```

192 192

193Deep mode supports repository and path targets. Use standard mode for diff and193Deep mode supports repository and path targets. Use standard mode for diff and

194working-tree scans. The optional settings control concurrent discovery workers,194working-tree scans. The optional settings control concurrent independent

195subagents per worker, consecutive discovery runs without new findings, and the195standard-scan workers, subagents per worker, consecutive completed worker scans

196total number and duration of discovery runs. They require `mode: "deep"`.196without new findings, and the total number and duration of worker runs. They

197require `mode: "deep"`.

197 198

198`maxTimeHours` defaults to `96` and accepts a positive number up to `96`,199`maxTimeHours` defaults to `96` and accepts a positive number up to `96`,

199including fractional hours. At the deadline, Codex Security stops unfinished200including fractional hours. At the deadline, Codex Security stops unfinished

200discovery, keeps completed discovery results, and continues with validation201workers, keeps completed scan results, and aggregates them into the final

201and reporting. Review `result.coverage.completeness` before treating a202report. Review `result.coverage.completeness` before treating a time-limited

202time-limited scan as evidence of full coverage.203scan as evidence of full coverage.

203 204

204### Add a security knowledge base205### Add a security knowledge base

205 206

253 254

254The limit estimates spending but isn't a hard cap, so requests already in255The limit estimates spending but isn't a hard cap, so requests already in

255progress can finish slightly above it. If a deep scan reaches the limit after256progress can finish slightly above it. If a deep scan reaches the limit after

256discovery finishes, `run` returns a result with `coverage.completeness` set to257Codex Security aggregates completed worker results, `run` returns a result

257`"partial"` and reports the budget warning through `onWarning`.258with `coverage.completeness` set to `"partial"` and reports the budget warning

259through `onWarning`.

258 260

259If the scan can't produce a completed partial result, `run` throws261If the scan can't produce a completed partial result, `run` throws

260`ScanCostLimitExceededError` and preserves any available output.262`ScanCostLimitExceededError` and preserves any available output.

Documentation 2026-08-17 23:58 UTC to 2026-08-18 07:00 UTC