Documentation 2026-08-17 23:58 UTC to 2026-08-18 13:01 UTC

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| ------------------------ | -------------------------------------------------------------------------------------- |

4646| `--workers N` | Limit on concurrent discovery workers. Defaults to automatic selection. |4647| `--workers N` | Limit on concurrent independent standard-scan workers. Defaults to `4`. |

4647| `--subagents N` | Subagents available to each discovery worker. Defaults to `3`. |4648| `--subagents N` | Subagents available to each worker. Defaults to `3`. |

4648| `--stop-after-no-new N` | Stop after `N` consecutive runs find no new issues. Defaults to `6`. |4649| `--stop-after-no-new N` | Stop after `N` consecutive completed worker scans find no new issues. Defaults to `4`. |

4649| `--max-discovery-runs N` | Limit on total discovery runs. Defaults to `60`. |4650| `--max-discovery-runs N` | Limit on total independent standard-scan runs. Defaults to `40`. |

4650| `--max-time-hours HOURS` | Discovery time limit in hours. Defaults to `96`; accepts fractions. |4651| `--max-time-hours HOURS` | Worker execution time limit in hours. Defaults to `96`; accepts fractions. |

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 

7559| Setting | Default | Description |7604| Setting | Default | Description |

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

7561| `workers` | `auto` | Number of discovery workers allowed to run at the same time. Set a positive integer or `"auto"`. |7606| `workers` | `4` | Number of independent standard-scan workers allowed to run at the same time. Legacy `"auto"` also resolves to `4`. |

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 7657 

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

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

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

7618 7661activity** to inspect its Codex task. Check the [plugin

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

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

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

7622update the plugin or start 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

18518 18561 

18519Source: [Sites](https://learn.chatgpt.com/docs/sites.md)18562Source: [Sites](https://learn.chatgpt.com/docs/sites.md)

18520 18563 

18521Sites is in public beta. Availability can depend on your plan, region, and18564Sites is in public beta and is available with ChatGPT Plus, Pro, Business,

18522workspace settings. Plan-specific usage limits apply across all Sites during18565Enterprise and Edu plans. Plan-specific usage limits apply across all Sites

18523the beta. ChatGPT shows the current limits and notifies you as you approach18566during the beta. ChatGPT shows the current limits and notifies you as you

18524one. Reaching a limit can prevent you from creating a Site, adding storage, or18567approach one. Reaching a limit can prevent you from creating a Site, adding

18525keeping a high-usage Site public, but you can still edit and manage existing18568storage, or keeping a high-usage Site public, but you can still edit and

18526Sites.18569manage existing Sites.

18527 18570 

18528Sites lets ChatGPT create, host, refine, and share websites, web apps, and games.18571Sites lets ChatGPT create, host, refine, and share websites, web apps, and games.

18529Use Sites when you want to turn a prompt or compatible existing project into a18572Use Sites when you want to turn a prompt or compatible existing project into a

18824frameworks, private networks, databases, background services, and hosting18867frameworks, private networks, databases, background services, and hosting

18825patterns aren't supported.18868patterns aren't supported.

18826 18869 

18870Each Site has these storage limits:

18871 

18872| Resource | Limit |

18873| ------------------- | ---------------------- |

18874| D1 database storage | 10 GB |

18875| R2 object storage | No fixed storage limit |

18876 

18827Sites doesn't support data residency or inference residency at launch. This18877Sites doesn't support data residency or inference residency at launch. This

18828includes deployed Sites, Site code, D1 and R2 data and file storage, generated18878includes deployed Sites, Site code, D1 and R2 data and file storage, generated

18829artifacts, and logs.18879artifacts, and logs.

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

21348 21398 

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

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

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

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

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

21404included.

21352 21405 

21353#### How Computer History helps21406#### How Computer History helps

21354 21407 

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

21381files.21434files.

21382 21435 

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

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

21385included.21438included.

21386 21439 

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

21494#### Privacy and local storage21547#### Privacy and local storage

21495 21548 

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

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

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

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

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

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

21500 21555 

21501Temporary event files are retained for up to 48 hours. Generated memory files21556Temporary 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 reveal21557remain on your filesystem until you delete or clear them, and you can reveal

24579 - Environment variables24634 - Environment variables

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

24581 - Bearer token authentication24636 - Bearer token authentication

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

24638 Dynamic Client Registration (DCR)

24583 - ChatGPT session authentication for trusted first-party servers24639 - 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.24640- **Server instructions**: Codex reads the MCP `instructions` field returned during initialization and uses it as server-wide guidance alongside the server's tools.

24585 24641 

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

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

24717 24773 

24774#### OAuth client registration

24775 

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

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

24778CIMD when the authorization server advertises

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

24780`token_endpoint_auth_methods_supported`, and the callback uses a supported

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

24782ID always takes precedence and skips client registration.

24783 

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

24785server:

24786 

24787```text

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

24789```

24790 

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

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

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

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

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

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

24797client ID.

24798 

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

24800 

24801```text

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

24803```

24804 

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

24806authorization server advertises

24807`authorization_response_iss_parameter_supported: true`, provides a valid

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

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

24810callback-specific document.

24811 

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

24813`--oauth-client-registration`:

24814 

24815```bash

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

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

24818```

24819 

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

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

24822 

24718#### config.toml examples24823#### config.toml examples

24719 24824 

24720```toml24825```toml

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. Computer24rebuilt 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 never101microphone 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

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 authentication28 - 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

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 screenshots37memories 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

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 

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

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 

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| ------------------------ | -------------------------------------------------------------------------------------- |

252| `--workers N` | Limit on concurrent discovery workers. Defaults to automatic selection. |251| `--workers N` | Limit on concurrent independent standard-scan workers. Defaults to `4`. |

253| `--subagents N` | Subagents available to each discovery worker. Defaults to `3`. |252| `--subagents N` | Subagents available to each worker. Defaults to `3`. |

254| `--stop-after-no-new N` | Stop after `N` consecutive runs find no new issues. Defaults to `6`. |253| `--stop-after-no-new N` | Stop after `N` consecutive completed worker scans find no new issues. Defaults to `4`. |

255| `--max-discovery-runs N` | Limit on total discovery runs. Defaults to `60`. |254| `--max-discovery-runs N` | Limit on total independent standard-scan runs. Defaults to `40`. |

256| `--max-time-hours HOURS` | Discovery time limit in hours. Defaults to `96`; accepts fractions. |255| `--max-time-hours HOURS` | Worker execution time limit in hours. Defaults to `96`; accepts fractions. |

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`

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)

17 

18### Run deep scans as complete independent audits

19 

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.

31 

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

33 

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`.

41 

42### Run deep scans in more environments

43 

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.

49 

50### Preserve scan results through more failures

51 

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.

58 

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

37```37```

38 38 

39| Setting | Default | Description |39| Setting | Default | Description |

40| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |40| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |

41| `workers` | `auto` | Number of discovery workers allowed to run at the same time. Set a positive integer or `"auto"`. |41| `workers` | `4` | Number of independent standard-scan workers allowed to run at the same time. Legacy `"auto"` also resolves to `4`. |

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 Security51When the time limit expires, Codex Security stops unfinished workers, keeps

52stops unfinished discovery, keeps completed results, and continues with52completed 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 the97Deep 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

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.

2 2 

3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.3> For the complete documentation index, see [llms.txt](https://learn.chatgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

4 4 

5Sites is in public beta. Availability can depend on your plan, region, and5Sites is in public beta and is available with ChatGPT Plus, Pro, Business,

6 workspace settings. Plan-specific usage limits apply across all Sites during6 Enterprise and Edu plans. Plan-specific usage limits apply across all Sites

7 the beta. ChatGPT shows the current limits and notifies you as you approach7 during the beta. ChatGPT shows the current limits and notifies you as you

8 one. Reaching a limit can prevent you from creating a Site, adding storage, or8 approach one. Reaching a limit can prevent you from creating a Site, adding

9 keeping a high-usage Site public, but you can still edit and manage existing9 storage, or keeping a high-usage Site public, but you can still edit and

10 Sites.10 manage existing Sites.

11 11 

12Sites lets ChatGPT create, host, refine, and share websites, web apps, and games.12Sites lets ChatGPT create, host, refine, and share websites, web apps, and games.

13Use Sites when you want to turn a prompt or compatible existing project into a13Use Sites when you want to turn a prompt or compatible existing project into a

378frameworks, private networks, databases, background services, and hosting378frameworks, private networks, databases, background services, and hosting

379patterns aren't supported.379patterns aren't supported.

380 380 

381Each Site has these storage limits:

382 

383| Resource | Limit |

384| ------------------- | ---------------------- |

385| D1 database storage | 10 GB |

386| R2 object storage | No fixed storage limit |

387 

381Sites doesn't support data residency or inference residency at launch. This388Sites doesn't support data residency or inference residency at launch. This

382includes deployed Sites, Site code, D1 and R2 data and file storage, generated389includes deployed Sites, Site code, D1 and R2 data and file storage, generated

383artifacts, and logs.390artifacts, and logs.

27 suggestedEffort: medium27 suggestedEffort: medium

28relatedLinks:28relatedLinks:

29 - label: ChatGPT desktop app29 - label: ChatGPT desktop app

30 url: /codex/app30 url: /docs/app

31---31---

32 32 

33> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.33> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

13 body: /goal Complete [objective] without stopping until [verifiable end state].13 body: /goal Complete [objective] without stopping until [verifiable end state].

14relatedLinks:14relatedLinks:

15 - label: "`/goal` in CLI slash commands"15 - label: "`/goal` in CLI slash commands"

16 url: /codex/developer-commands?surface=cli#cli-set-or-view-a-task-goal-with-goal16 url: /docs/developer-commands?surface=cli#cli-set-or-view-a-task-goal-with-goal

17 - label: Codex workflows17 - label: Codex workflows

18 url: /codex/prompting18 url: /docs/prompting

19 - label: Run code migrations19 - label: Run code migrations

20 url: /codex/use-cases/code-migrations20 url: /use-cases/code-migrations

21 - label: Iterate on difficult problems21 - label: Iterate on difficult problems

22 url: /codex/use-cases/iterate-on-difficult-problems22 url: /use-cases/iterate-on-difficult-problems

23---23---

24 24 

25> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.25> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

48 suggestedEffort: medium48 suggestedEffort: medium

49relatedLinks:49relatedLinks:

50 - label: Skills50 - label: Skills

51 url: /codex/build-skills51 url: /docs/build-skills

52---52---

53 53 

54> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.54> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

63 63 

64Give Codex the clearest references you have for the UI you want. A single screenshot can be enough for a narrow task, but the handoff gets better when you include multiple states such as desktop and mobile layouts, hover or selected states, and any empty or loading views that matter.64Give Codex the clearest references you have for the UI you want. A single screenshot can be enough for a narrow task, but the handoff gets better when you include multiple states such as desktop and mobile layouts, hover or selected states, and any empty or loading views that matter.

65 65 

66The references do not need to be perfect design deliverables. They just need to make the intended hierarchy, spacing, and direction concrete enough that Codex is not guessing.66The references do not need to be perfect design assets. They just need to make the intended hierarchy, spacing, and direction concrete enough that Codex is not guessing.

67 67 

68## Be specific68## Be specific

69 69 

70The more specific you are about the expected interaction patterns and the style you want, the better the result will be.70The more specific you are about the expected interaction patterns and the style you want, the better the result will be.

71The model tends to default to high-frequency patterns and style so if it's not obvious from your references that you want something else, the UI might look generic.71The model tends to default to high-frequency patterns and style so if it's not clear from your references that you want something else, the UI might look generic.

72The more input you give, be it more reference inspiration or more specific instructions, the more you can expect to have a UI that stands out.72The more input you give, be it more reference inspiration or more specific instructions, the more you can expect to have a UI that stands out.

73 73 

74## Prepare the design system74## Prepare the design system

75 75 

76Codex works best when the target repo already has a clear component layer. Codex can automatically use your existing component and design system instead of recreating them from scratch.76Codex works best when the target repo already has a clear component layer. Codex can automatically use your existing component and design system instead of recreating them from scratch.

77 77 

78If you think it's necessary (i.e. if you're not using a standard stack), specify to Codex which primitives to reuse, where your tokens live, and what the repo considers canonical for buttons, inputs, cards, typography, and icons.78If necessary, such as when you're not using a standard stack, specify to Codex which primitives to reuse, where your tokens live, and what the repo considers canonical for buttons, inputs, cards, typography, and icons.

79 79 

80If you're starting from an existing codebase, it's very likely that Codex will understand on its own how to use your components and design system, but if starting from scratch, it's a good idea to be explicit.80If you're starting from an existing codebase, Codex will likely understand on its own how to use your components and design system, but if starting from scratch, it's a good idea to be explicit.

81 81 

82Ask Codex to treat the screenshots as a visual target but to translate that target into the project's actual utilities, component wrappers, color system, typography scale, spacing tokens, routing, state management, and data-fetch patterns.82Ask Codex to treat the screenshots as a visual target but to translate that target into the project's actual utilities, component wrappers, color system, typography scale, spacing tokens, routing, state management, and data-fetch patterns.

83 83 

87 87 

88It can resize the browser window to different screen sizes and check the layout at different breakpoints.88It can resize the browser window to different screen sizes and check the layout at different breakpoints.

89 89 

90Make sure you have the Playwright interactive skill enabled in Codex. For more details, see the [skills documentation](https://developers.openai.com/codex/build-skills).90Make sure you have the Playwright interactive skill enabled in Codex. For more details, see the [skills documentation](https://developers.openai.com/docs/build-skills).

91 91 

92## Iterate92## Iterate

93 93 

95 95 

96Ask Codex to compare the implementation back to the screenshots, not just whether the page builds. When conflicts come up, it should prefer the repo's design-system tokens and only make minimal spacing or sizing adjustments needed to preserve the overall look of the design.96Ask Codex to compare the implementation back to the screenshots, not just whether the page builds. When conflicts come up, it should prefer the repo's design-system tokens and only make minimal spacing or sizing adjustments needed to preserve the overall look of the design.

97 97 

98Use additional screenshots or short notes if they help clarify states that are not obvious from one image.98Use additional screenshots or short notes if they help clarify states that are not clear from one image.

99 99 

100### Suggested follow-up prompt100### Suggested follow-up prompt

101 101 

73 suggestedEffort: medium73 suggestedEffort: medium

74relatedLinks:74relatedLinks:

75 - label: Plugins75 - label: Plugins

76 url: /codex/plugins76 url: /docs/plugins

77 - label: Scheduled tasks77 - label: Scheduled tasks

78 url: /codex/automations78 url: /docs/automations

79---79---

80 80 

81> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.81> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

84 84 

85You can run this in ChatGPT Work in the browser or desktop app. Before you start:85You can run this in ChatGPT Work in the browser or desktop app. Before you start:

86 86 

87- **Connect your email.** Install the [Gmail or Outlook Email plugin](https://developers.openai.com/codex/plugins). You can also connect Slack, Google Drive, and your calendar to give ChatGPT more context when drafting replies.87- **Connect your email.** Install the [Gmail or Outlook Email plugin](https://developers.openai.com/docs/plugins). You can also connect Slack, Google Drive, and your calendar to give ChatGPT more context when drafting replies.

88- **Choose where scheduled checks run.** Start in the browser if you want checks to continue when your laptop is off. On desktop, keep your computer on and the ChatGPT desktop app running. Voice chats don't support [scheduled tasks](https://developers.openai.com/codex/automations), so set up or manage them in chat instead.88- **Choose where scheduled checks run.** Start in the browser if you want checks to continue when your laptop is off. On desktop, keep your computer on and the ChatGPT desktop app running. Voice chats don't support [scheduled tasks](https://developers.openai.com/docs/automations), so set up or manage them in chat instead.

89 89 

90## What to expect90## What to expect

91 91 

19 changing anything important.19 changing anything important.

20relatedLinks:20relatedLinks:

21 - label: Computer Use21 - label: Computer Use

22 url: /codex/computer-use22 url: /docs/computer-use

23 - label: Plugins23 - label: Plugins

24 url: /codex/plugins24 url: /docs/plugins

25 - label: Customize ChatGPT25 - label: Customize ChatGPT

26 url: /codex/customization/overview26 url: /docs/customization/overview

27---27---

28 28 

29> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.29> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.

30 30 

31## Introduction31## Introduction

32 32 

33Use [Computer Use](https://developers.openai.com/codex/computer-use) when a task moves across desktop apps, windows, or local files. ChatGPT can click, type, and navigate the apps you allow, then return the result for review. For a website or signed-in browser session, start a separate browser task with `@Chrome`.33Use [Computer Use](https://developers.openai.com/docs/computer-use) when a task moves across desktop apps, windows, or local files. ChatGPT can click, type, and navigate the apps you allow, then return the result for review. For a website or signed-in browser session, start a separate browser task with `@Chrome`.

34 34 

35**Computer Use requires the ChatGPT desktop app.** In supported regions, Computer Use is available on macOS and Windows in ChatGPT Work and Codex. Cloud Work tasks on web or mobile cannot directly access your local apps, files, or signed-in desktop browser sessions. You can start or steer a desktop task from [Remote on mobile](https://developers.openai.com/codex/remote-connections) when you connect a Mac or Windows host.35**Computer Use requires the ChatGPT desktop app.** In supported regions, Computer Use is available on macOS and Windows in ChatGPT Work and Codex. Cloud Work tasks on web or mobile cannot directly access your local apps, files, or signed-in desktop browser sessions. You can start or steer a desktop task from [Remote on mobile](https://developers.openai.com/codex/remote-connections) when you connect a Mac or Windows host.

36 36 

49 49 

50## How to use50## How to use

51 51 

521. Open the ChatGPT desktop app and install the [Computer Use plugin](https://developers.openai.com/codex/computer-use).521. Open the ChatGPT desktop app and install the [Computer Use plugin](https://developers.openai.com/docs/computer-use).

532. Start your request with `@Computer` for desktop apps or `@Chrome` for browser tasks.532. Start your request with `@Computer` for desktop apps or `@Chrome` for browser tasks.

543. Describe the task, the apps or files involved, and the result you want.543. Describe the task, the apps or files involved, and the result you want.

554. Review access prompts and pause before actions that send, submit, or change important data.554. Review access prompts and pause before actions that send, submit, or change important data.

159- **[Built-in browser](https://developers.openai.com/codex/browser?surface=app):** Use it when you want a separate browser session for localhost or public sites. It has its own browser state and can wait while you sign in.159- **[Built-in browser](https://developers.openai.com/codex/browser?surface=app):** Use it when you want a separate browser session for localhost or public sites. It has its own browser state and can wait while you sign in.

160- **Cloud browser in ChatGPT Work on web or mobile:** Use it for supported public, signed-out sites. It cannot access local files, open tabs, extensions, or saved passwords, sign in to sites, or complete payments.160- **Cloud browser in ChatGPT Work on web or mobile:** Use it for supported public, signed-out sites. It cannot access local files, open tabs, extensions, or saved passwords, sign in to sites, or complete payments.

161 161 

162Name the browser in the prompt when it matters, and use [customization](https://developers.openai.com/codex/customization/overview) for a recurring desktop preference.162Name the browser in the prompt when it matters, and use [customization](https://developers.openai.com/docs/customization/overview) for a recurring desktop preference.

163 163 

164### Avoid parallel runs in the same app164### Avoid parallel runs in the same app

165 165 

167 167 

168### Prepare signed-in apps and locked use168### Prepare signed-in apps and locked use

169 169 

170Before starting a desktop task, sign in to the apps and services it needs. On macOS, you can enable [locked use](https://developers.openai.com/codex/computer-use#locked-use) if the task must continue after the Mac locks. Locked use is not available for Windows Computer Use.170Before starting a desktop task, sign in to the apps and services it needs. On macOS, you can enable [locked use](https://developers.openai.com/docs/computer-use#locked-use) if the task must continue after the Mac locks. Locked use is not available for Windows Computer Use.