SpyBara
Go Premium

Documentation 2026-07-16 20:57 UTC to 2026-07-17 22:57 UTC

160 files changed +1,802 −1,231. View all changes and history on the product overview
2026
Fri 17 22:57 Thu 16 20:57 Wed 15 19:58 Tue 14 17:03 Wed 8 02:01 Mon 6 22:58
Details

3<CodexDocsOverviewLanding3<CodexDocsOverviewLanding

4 title="Administration"4 title="Administration"

5 description="Set access and policy boundaries for ChatGPT, Codex developer tools, APIs, plugins, and connected systems."5 description="Set access and policy boundaries for ChatGPT, Codex developer tools, APIs, plugins, and connected systems."

6 intro="Administration covers six related boundaries: ChatGPT workspace access; local runtime policy for covered capabilities in the ChatGPT desktop app, Codex CLI, and IDE extension; Codex cloud eligibility; Platform API access; plugin and app availability; and permissions in connected systems. Start with workspace identity and access, then apply the runtime and source-system controls required for each deployment."6 intro="Administration covers six related boundaries: ChatGPT workspace access; local runtime policy for covered capabilities in the ChatGPT desktop app, Codex CLI, and IDE extension; Codex cloud eligibility; Platform API access; plugin availability and connector permissions; and permissions in connected systems. Start with workspace identity and access, then apply the runtime and source-system controls required for each deployment."

7 primaryCta={{7 primaryCta={{

8 label: "Explore authentication",8 label: "Explore authentication",

9 href: "/codex/auth?surface=app",9 href: "/codex/auth?surface=app",


27 icon: "users",27 icon: "users",

28 },28 },

29 {29 {

30 title: "ChatGPT Work Admin FAQ",30 title: "Work mode admin FAQ",

31 description:31 description:

32 "Review access, data, governance, usage, and incident controls for ChatGPT Work.",32 "Review access, data, governance, usage, and incident controls for Work mode.",

33 href: "/codex/enterprise/work-admin-faq",33 href: "/codex/enterprise/work-admin-faq",

34 icon: "userLock",34 icon: "userLock",

35 },35 },


100 {100 {

101 title: "Plugin and connector controls",101 title: "Plugin and connector controls",

102 description:102 description:

103 "Control plugin installation, bundled skills, app-backed capabilities, and connected-service access.",103 "Control plugin installation, bundled skills, connector-backed capabilities, and connected-service access.",

104 pages: [104 pages: [

105 {105 {

106 title: "Plugin controls",106 title: "Plugin controls",

107 description:107 description:

108 "Separate plugin availability from app enablement, actions, and source-system permissions.",108 "Manage plugin availability, connector access and actions, and source-system permissions.",

109 href: "/codex/enterprise/apps-and-connectors",109 href: "/codex/enterprise/apps-and-connectors",

110 icon: "connect",110 icon: "connect",

111 },111 },


133 {133 {

134 title: "Workspace analytics",134 title: "Workspace analytics",

135 description:135 description:

136 "Review ChatGPT adoption and distinguish it from Codex analytics.",136 "Review workspace-level ChatGPT adoption and Codex usage.",

137 href: "/codex/enterprise/workspace-analytics",137 href: "/codex/enterprise/workspace-analytics",

138 icon: "dataControls",138 icon: "dataControls",

139 },139 },

Details

403### Overview403### Overview

404 404 

405- Codex turns off OTel export by default to keep local runs self-contained.405- Codex turns off OTel export by default to keep local runs self-contained.

406- When enabled, Codex emits structured log events covering conversations, API requests, SSE/WebSocket stream activity, user prompts (redacted by default), tool approval decisions, and tool results.406- When enabled, Codex emits structured log events covering chats, API requests, SSE/WebSocket stream activity, user prompts (redacted by default), tool approval decisions, and tool results.

407- Codex tags exported events with `service.name` (originator), CLI version, and an environment label to separate dev/staging/prod traffic.407- Codex tags exported events with `service.name` (originator), CLI version, and an environment label to separate dev/staging/prod traffic.

408 408 

409### Enable OTel (opt-in)409### Enable OTel (opt-in)

Details

1# Speed1# Speed

2 2 

3<strong>ChatGPT Work and Codex share usage.</strong> Work usage inside ChatGPT3<strong>Work mode and Codex share usage.</strong> Work mode usage inside

4 uses the same pricing, credits, and usage limits as Codex. See [Codex4 ChatGPT uses the same pricing, credits, and usage limits as Codex. See [Codex

5 pricing](https://learn.chatgpt.com/docs/pricing) for details.5 pricing](https://learn.chatgpt.com/docs/pricing) for details.

6 6 

7## Fast mode7## Fast mode

Details

1# Subagents1# Subagents

2 2 

3ChatGPT Work and Codex can run subagent workflows by spawning specialized3Work mode and Codex can run subagent workflows by spawning specialized

4agents in parallel and then collecting their results in one response. This can4agents in parallel and then collecting their results in one response. This can

5be particularly helpful for complex tasks that are highly parallel, such as5be particularly helpful for complex tasks that are highly parallel, such as

6codebase exploration or implementing a multi-step feature plan.6codebase exploration or implementing a multi-step feature plan.


28 28 

29 29 

30 30 

31Ask Codex in an app task to delegate independent parts of the work to31Ask Codex in an app chat to delegate independent parts of the work to

32subagents. Current local Codex releases delegate when you ask directly or when32subagents. Current local Codex releases delegate when you ask directly or when

33applicable `AGENTS.md` or skill instructions request it. The app surfaces each33applicable `AGENTS.md` or skill instructions request it. The app surfaces each

34subagent thread so you can inspect its work and the summary returned to the main34subagent thread so you can inspect its work and the summary returned to the main

35task.35chat.

36 36 

37 37 

38 38 


42 42 

43## Why subagent workflows help43## Why subagent workflows help

44 44 

45Even with large context windows, models have limits. If you flood the main conversation (where you're defining requirements, constraints, and decisions) with noisy intermediate output such as exploration notes, test logs, stack traces, and command output, the session can become less reliable over time.45Even with large context windows, models have limits. If you flood the main chat (where you're defining requirements, constraints, and decisions) with noisy intermediate output such as exploration notes, test logs, stack traces, and command output, the session can become less reliable over time.

46 46 

47This is often described as:47This is often described as:

48 48 

49- **Context pollution**: useful information gets buried under noisy intermediate output.49- **Context pollution**: useful information gets buried under noisy intermediate output.

50- **Context rot**: performance degrades as the conversation fills up with less relevant details.50- **Context rot**: performance degrades as the chat fills up with less relevant details.

51 51 

52For background, see the Chroma writeup on [context rot](https://research.trychroma.com/context-rot).52For background, see the Chroma writeup on [context rot](https://research.trychroma.com/context-rot).

53 53 


186- Ask Codex directly to steer a running subagent, stop it, or close completed186- Ask Codex directly to steer a running subagent, stop it, or close completed

187 subagent threads.187 subagent threads.

188 188 

189<Illustration description="Codex desktop task showing two subagents working in parallel.">189<Illustration description="Codex desktop chat showing two subagents working in parallel.">

190 <SubagentWorkflowIllustration ariaLabel="Codex desktop task showing two subagents working in parallel." />190 <SubagentWorkflowIllustration ariaLabel="Codex desktop chat showing two subagents working in parallel." />

191</Illustration>191</Illustration>

192 192 

193<Illustration description="Codex desktop Subagents panel with no active subagents and three completed audits.">193<Illustration description="Codex desktop Subagents panel with no active subagents and three completed audits.">

amazon-bedrock.md +50 −34

Details

1# Use Codex with Amazon Bedrock1# Use ChatGPT Work and Codex with Amazon Bedrock

2 2 

3Configure Codex to use OpenAI models available through Amazon Bedrock. In this3Configure local ChatGPT Work and Codex surfaces to use OpenAI models available

4setup, Codex runs locally and sends model requests to Bedrock using4through Amazon Bedrock. In this setup, the local client sends model requests to

5AWS-managed authentication and access controls.5Bedrock using AWS-managed authentication and access controls.

6 6 

7## How it works7## How it works

8 8 

9When you configure Codex with Amazon Bedrock as the model provider, the9When you configure a local ChatGPT Work or Codex surface with Amazon Bedrock as

10OpenAI-hosted Responses API isn't in the request path. Codex sends model10the model provider, the OpenAI-hosted Responses API isn't in the request path.

11requests to Amazon Bedrock, and Bedrock provides an OpenAI-compatible Responses11The local client sends model requests to Amazon Bedrock, and Bedrock provides an

12API implementation for supported OpenAI models.12OpenAI-compatible Responses API implementation for supported OpenAI models.

13 13 

14Authentication is AWS-native. Users authenticate with a Bedrock API key or AWS14Authentication is AWS-native. Users authenticate with a Bedrock API key or AWS

15 IAM credentials. They do not use ChatGPT sign-in or `OPENAI_API_KEY` for this15 IAM credentials. They do not use ChatGPT sign-in or `OPENAI_API_KEY` for this


24- Authentication for the Amazon Bedrock Mantle path configured for the AWS24- Authentication for the Amazon Bedrock Mantle path configured for the AWS

25 account.25 account.

26 26 

27## Configure Codex27## Configure the provider

28 28 

29Add the `amazon-bedrock` model provider for the Amazon Bedrock Mantle path to29Add the `amazon-bedrock` model provider for the Amazon Bedrock Mantle path to

30`~/.codex/config.toml`. Supplying a model is optional. Select a supported model30`~/.codex/config.toml`. The ChatGPT desktop app, Codex CLI, IDE extension, and

31explicitly when needed.31SDK read the same local configuration layers. Supplying a model is optional.

32Select a supported model explicitly when needed.

32 33 

33```toml34```toml

34model_provider = "amazon-bedrock"35model_provider = "amazon-bedrock"

35```36```

36 37 

37This guide covers the Amazon Bedrock Mantle path in supported commercial AWS38This guide covers the Amazon Bedrock Mantle path in supported commercial AWS

38 Regions. Codex doesn't support Bedrock Mantle endpoints in AWS GovCloud39 Regions. Local ChatGPT Work and Codex surfaces don't support Bedrock Mantle

39 Regions.40 endpoints in AWS GovCloud Regions.

40 41 

41## Authentication options42## Authentication options

42 43 

43Codex supports two Bedrock authentication paths. It checks them in this order:44Local ChatGPT Work and Codex surfaces support two Bedrock authentication paths.

45They check them in this order:

44 46 

451. Bedrock API key.471. Bedrock API key.

462. AWS SDK credential chain.482. AWS SDK credential chain.

47 49 

48### Option 1: Bedrock API key50### Option 1: Bedrock API key

49 51 

50Set the Bedrock API key in the environment Codex reads. You must specify a52Set the Bedrock API key in the environment the local client reads. You must

51Region when using API-key authentication.53specify a Region when using API-key authentication.

52 54 

53```shell55```shell

54export AWS_BEARER_TOKEN_BEDROCK=<your-bedrock-api-key>56export AWS_BEARER_TOKEN_BEDROCK=<your-bedrock-api-key>


58### Option 2: AWS SDK credentials60### Option 2: AWS SDK credentials

59 61 

60Use this path when your organization manages Bedrock access through the AWS SDK62Use this path when your organization manages Bedrock access through the AWS SDK

61credential chain. Codex can use these standard AWS SDK credential sources:63credential chain. The local client can use these standard AWS SDK credential

64sources:

62 65 

631. Shared AWS `config` and `credentials` files.661. Shared AWS `config` and `credentials` files.

64 67 


88 ```91 ```

89 92 

905. Federated identity configured with `credential_process`. For corporate SSO or935. Federated identity configured with `credential_process`. For corporate SSO or

91 OIDC federation, configure the AWS profile outside Codex and let the AWS SDK94 OIDC federation, configure the AWS profile outside the local client and let

92 resolve credentials. Put browser login, token exchange, caching, and refresh95 the AWS SDK resolve credentials. Put browser login, token exchange, caching,

93 in your AWS profile's `credential_process` helper.96 and refresh in your AWS profile's `credential_process` helper.

94 97 

95## Desktop app and VS Code extension98## Desktop app and IDE extension

96 99 

97Desktop apps and IDE extensions may not inherit environment variables from the100Desktop apps and IDE extensions may not inherit environment variables from the

98shell. Put required values in `~/.codex/.env`, then restart the app or101shell. Put required values in `~/.codex/.env`, then restart the app or


107 110 

108- In Codex CLI, open `/status` and confirm Codex is using the111- In Codex CLI, open `/status` and confirm Codex is using the

109 `amazon-bedrock` model provider.112 `amazon-bedrock` model provider.

110- In the desktop app or VS Code extension, start a new session after restarting113- In the ChatGPT desktop app, select Work or Codex and start a new task after

111 the app.114 restarting the app.

115- In the IDE extension, start a new session after restarting the extension.

112- Confirm the selected model is available in the configured AWS Region and that116- Confirm the selected model is available in the configured AWS Region and that

113 the AWS identity has permission to access it.117 the AWS identity has permission to access it.

114 118 


117Use exact model IDs:121Use exact model IDs:

118 122 

119```text123```text

124openai.gpt-5.6-sol

125openai.gpt-5.6-terra

126openai.gpt-5.6-luna

120openai.gpt-5.5127openai.gpt-5.5

121openai.gpt-5.4128openai.gpt-5.4

122```129```


127 134 

128## Feature availability135## Feature availability

129 136 

130This configuration supports local Codex workflows. Some features that depend on137This configuration supports local ChatGPT Work and Codex workflows. Hosted

131OpenAI-hosted cloud services, hosted tools, or cloud-managed discovery aren't138ChatGPT Work on the web, Codex cloud, and features that depend on OpenAI-hosted

132currently available.139cloud services, hosted tools, or cloud-managed discovery aren't currently

140available.

133 141 

134Fast Mode isn't available with Amazon Bedrock. Fast Mode uses priority142Fast Mode isn't available with Amazon Bedrock. Fast Mode uses priority

135 processing, and the initial Amazon Bedrock offering supports on-demand143 processing, and the initial Amazon Bedrock offering supports on-demand


150 {158 {

151 title: "Access and surfaces",159 title: "Access and surfaces",

152 features: [160 features: [

161 {

162 name: "ChatGPT Work on the web",

163 href: "/codex/get-started-with-work",

164 availability: {

165 bedrock: "unavailable",

166 },

167 },

153 {168 {

154 name: "Codex cloud",169 name: "Codex cloud",

155 href: "/codex/cloud",170 href: "/codex/cloud",


158 },173 },

159 },174 },

160 {175 {

161 name: "ChatGPT desktop app for local tasks",176 name: "ChatGPT Work or Codex in the ChatGPT desktop app",

177 shortName: "ChatGPT desktop app",

162 href: "/codex/app",178 href: "/codex/app",

163 availability: {179 availability: {

164 bedrock: "available",180 bedrock: "available",


419 title: "Cloud and integrations",435 title: "Cloud and integrations",

420 features: [436 features: [

421 {437 {

422 name: "Codex cloud tasks",438 name: "Codex cloud chats",

423 shortName: "Cloud tasks",439 shortName: "Cloud chats",

424 href: "/codex/cloud",440 href: "/codex/cloud",

425 availability: {441 availability: {

426 bedrock: "unavailable",442 bedrock: "unavailable",


589- The Bedrock API key or AWS credentials are valid and not expired.605- The Bedrock API key or AWS credentials are valid and not expired.

590- The AWS identity has permission to access the selected Bedrock model.606- The AWS identity has permission to access the selected Bedrock model.

591- `AWS_BEARER_TOKEN_BEDROCK` isn't set to an expired or unintended key.607- `AWS_BEARER_TOKEN_BEDROCK` isn't set to an expired or unintended key.

592- For desktop app or VS Code extension usage, required environment variables608- For desktop app or IDE extension usage, required environment variables are

593 are present in `~/.codex/.env`.609 present in `~/.codex/.env`.

594 610 

595## Support boundaries611## Support boundaries

596 612 

597OpenAI Support can help with Codex client setup, configuration, local CLI613OpenAI Support can help with ChatGPT Work and Codex client setup,

598behavior, desktop app behavior, IDE extension behavior, and the local Codex614configuration, local CLI behavior, desktop app behavior, IDE extension behavior,

599product experience.615and the local product experience.

600 616 

601For AWS credentials, IAM permissions, Bedrock model access, quotas, billing,617For AWS credentials, IAM permissions, Bedrock model access, quotas, billing,

602regional availability, Bedrock request failures, AWS service logs, or Bedrock618regional availability, Bedrock request failures, AWS service logs, or Bedrock

app/automations.md +17 −16

Details

25<a id="scheduled-tasks-in-threads"></a>25<a id="scheduled-tasks-in-threads"></a>

26<a id="scheduled-tasks-in-chats"></a>26<a id="scheduled-tasks-in-chats"></a>

27<a id="schedule-work-from-a-task"></a>27<a id="schedule-work-from-a-task"></a>

28<a id="schedule-a-task-inside-a-chat"></a>

28<a id="test-automations"></a>29<a id="test-automations"></a>

29<a id="test-scheduled-tasks"></a>30<a id="test-scheduled-tasks"></a>

30<a id="worktree-cleanup-for-automations"></a>31<a id="worktree-cleanup-for-automations"></a>


42 43 

43For example, schedule a task to evaluate telemetry errors and submit fixes,44For example, schedule a task to evaluate telemetry errors and submit fixes,

44or to create reports about recent codebase changes. For ongoing work that45or to create reports about recent codebase changes. For ongoing work that

45should keep using the same context, [schedule work from an existing task](#schedule-work-from-a-task).46should keep using the same context, [schedule a task inside an existing chat](#schedule-a-task-inside-a-chat).

46 47 

47For project-scoped scheduled tasks, keep the machine powered on and the ChatGPT48For project-scoped scheduled tasks, keep the machine powered on and the ChatGPT

48desktop app running. The selected project must still be available on disk when49desktop app running. The selected project must still be available on disk when


84 />85 />

85</Illustration>86</Illustration>

86 87 

87Standalone scheduled tasks start a new task for each scheduled run and report88Standalone scheduled tasks start a new chat for each scheduled run and report

88results in **Scheduled**. Use them when each run should be independent or when one89results in **Scheduled**. Use them when each run should be independent or when one

89scheduled task should run across one or more projects. If you need a custom90scheduled task should run across one or more projects. If you need a custom

90cadence, use the custom schedule controls. For an advanced schedule, edit its91cadence, use the custom schedule controls. For an advanced schedule, edit its


103 104 

104 105 

105 106 

106Scheduled tasks in ChatGPT Work on the web or in Work or Codex in the ChatGPT desktop107Scheduled tasks in Work mode on the web, or in Work mode or Codex in the ChatGPT

107app can use plugins. Scheduled tasks can also use skills. To keep scheduled108desktop app, can use plugins. Scheduled tasks can also use skills. To keep scheduled

108tasks maintainable and shareable across teams, use [skills](https://learn.chatgpt.com/docs/build-skills) to109tasks maintainable and shareable across teams, use [skills](https://learn.chatgpt.com/docs/build-skills) to

109define the action and provide tools and context. Select or invoke a specific110define the action and provide tools and context. Select or invoke a specific

110skill in the task prompt when the workflow shouldn't rely on automatic tool111skill in the task prompt when the workflow shouldn't rely on automatic tool


112 113 

113## Ask ChatGPT to create or update scheduled tasks114## Ask ChatGPT to create or update scheduled tasks

114 115 

115You can create and update scheduled tasks from a Work or Codex task in ChatGPT.116You can create and update scheduled tasks from a ChatGPT or Codex chat.

116Describe the work, the schedule, and whether each scheduled run should return to117Describe the work, the schedule, and whether each scheduled run should return to

117the current task or start a new task. ChatGPT can draft the prompt, choose the118the current chat or start a new chat. ChatGPT can draft the prompt, choose the

118right destination, and update the scheduled task when its scope or cadence119right destination, and update the scheduled task when its scope or cadence

119changes.120changes.

120 121 

121For example, ask ChatGPT to schedule a follow-up from the current task while a122For example, ask ChatGPT to schedule a follow-up from the current chat while a

122deployment finishes, or ask it to create a standalone scheduled task that checks123deployment finishes, or ask it to create a standalone scheduled task that checks

123a project on a recurring schedule.124a project on a recurring schedule.

124 125 


126babysitting a pull request could set up a scheduled task that checks the127babysitting a pull request could set up a scheduled task that checks the

127PR status with the GitHub plugin and fixes new review feedback.128PR status with the GitHub plugin and fixes new review feedback.

128 129 

129## Schedule work from a task130## Schedule a task inside a chat

130 131 

131Schedule work from an existing task when you want ChatGPT to return to that task132Schedule a task inside an existing chat when you want ChatGPT to return to that chat

132on a schedule. The scheduled work uses the task's existing context instead of133on a schedule. The scheduled task uses the chat's existing context instead of

133starting from a new prompt each time.134starting from a new prompt each time.

134 135 

135Scheduled work in a task can use minute-based intervals for active follow-up136Scheduled tasks in a chat can use minute-based intervals for active follow-up

136loops, or daily and weekly schedules when you need a check-in at a specific137loops, or daily and weekly schedules when you need a check-in at a specific

137time.138time.

138 139 

139Schedule work from a task for:140Schedule a task inside a chat for:

140 141 

141- checking a long-running operation until it finishes142- checking a long-running operation until it finishes

142- polling Slack, GitHub, or another connected source when the results should143- polling Slack, GitHub, or another connected source when the results should

143 stay in the same task144 stay in the same chat

144- reminding ChatGPT to continue a review loop at a fixed cadence145- reminding ChatGPT to continue a review loop at a fixed cadence

145- running a skill-driven workflow that uses plugins, such as checking PR status146- running a skill-driven workflow that uses plugins, such as checking PR status

146 and addressing new feedback147 and addressing new feedback

147- continuing an ongoing research or triage task without losing its context148- continuing an ongoing research or triage chat without losing its context

148 149 

149Use a standalone scheduled task when each run should be independent or when150Use a standalone scheduled task when each run should be independent or when

150findings should appear as separate runs in **Scheduled**.151findings should appear as separate runs in **Scheduled**.

151 152 

152When you schedule work from a task, make the prompt durable. It should describe153When you schedule a task inside a chat, make the prompt durable. It should describe

153what ChatGPT should do on each scheduled run, how to decide whether there is154what ChatGPT should do on each scheduled run, how to decide whether there is

154anything important to report, and when to stop or ask you for input.155anything important to report, and when to stop or ask you for input.

155 156 

156## Test scheduled tasks157## Test scheduled tasks

157 158 

158Before you schedule a task, test the prompt manually in a regular task159Before you schedule a task, test the prompt manually in a regular chat

159first. This helps you confirm:160first. This helps you confirm:

160 161 

161- The prompt is clear and scoped correctly.162- The prompt is clear and scoped correctly.

app/browser.md +9 −8

Details

12 12 

13 13 

14The built-in browser in the ChatGPT desktop app gives you and ChatGPT a shared14The built-in browser in the ChatGPT desktop app gives you and ChatGPT a shared

15view of websites and local web apps inside a task. Use it to preview a page,15view of websites and local web apps inside a chat. Use it to preview a page,

16leave visual feedback, or let ChatGPT interact with a site on your behalf.16leave visual feedback, or let ChatGPT interact with a site on your behalf.

17 17 

18The built-in browser uses a browser profile that is separate from your regular18The built-in browser uses a browser profile that is separate from your regular


44 44 

45## Computer Use in the browser45## Computer Use in the browser

46 46 

47Computer Use lets ChatGPT operate the built-in browser directly. ChatGPT can47In the desktop app, Computer Use lets ChatGPT in Work mode or Codex operate the

48open pages, click, type, inspect rendered state, take screenshots, and verify48built-in browser directly. The selected experience can open pages, click, type,

49the result of its work in the page.49inspect rendered state, take screenshots, and verify the result of its work in

50the page.

50 51 

51In the desktop app, open the Plugins Directory and install **Browser**. Then ask52Select ChatGPT and switch to Work mode, or select Codex. Open the Plugins

52ChatGPT to use the browser in your task, or reference it directly with53Directory and install **Browser**. Then ask ChatGPT or Codex to use the browser

53`@Browser`.54in your task, or reference it directly with `@Browser`.

54 55 

55For example:56For example:

56 57 


931. Turn on **Annotation mode**.941. Turn on **Annotation mode**.

942. Click an element, or drag to select an area.952. Click an element, or drag to select an area.

953. Write and save your comment.963. Write and save your comment.

964. Send a message in the task asking ChatGPT to address the comments.974. Send a message in the chat asking ChatGPT to address the comments.

97 98 

98Comments work best when you name the problem and the result you want:99Comments work best when you name the problem and the result you want:

99 100 

Details

33 can also press <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>.</kbd>.33 can also press <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>.</kbd>.

343. Ask a question about the page or give ChatGPT a task.343. Ask a question about the page or give ChatGPT a task.

35 35 

36The panel stays with the tab where you opened it. Threads you start in Chrome36The panel stays with the tab where you opened it. Chats you start in Chrome

37are available in the ChatGPT app, and you can open recent ChatGPT threads in37are available in the ChatGPT app, and you can open recent ChatGPT chats in

38Chrome, so you can continue work in either place.38Chrome, so you can continue work in either place.

39 39 

40<Illustration description="ChatGPT open beside the current Chrome tab.">40<Illustration description="ChatGPT open beside the current Chrome tab.">


76 76 

77## Start a Chrome task from ChatGPT77## Start a Chrome task from ChatGPT

78 78 

79After the plugin setup is complete, start a new task in Work or Codex. ChatGPT79After the plugin setup is complete, start a new chat in Work mode or Codex. ChatGPT

80can use Chrome automatically when a task needs a website and you're already80can use Chrome automatically when a task needs a website and you're already

81signed in to Chrome. You can also invoke it directly in a prompt:81signed in to Chrome. You can also invoke it directly in a prompt:

82 82 


159OpenAI doesn't store a separate complete record of your Chrome actions from the159OpenAI doesn't store a separate complete record of your Chrome actions from the

160extension. OpenAI stores browser activity only when it becomes part of the ChatGPT160extension. OpenAI stores browser activity only when it becomes part of the ChatGPT

161context, such as text ChatGPT reads from a page, screenshots, tool calls,161context, such as text ChatGPT reads from a page, screenshots, tool calls,

162summaries, messages, or other content included in the task.162summaries, messages, or other content included in the chat.

163 163 

164Your ChatGPT data controls apply to content processed in context.164Your ChatGPT data controls apply to content processed in context.

165Avoid sending secrets or highly sensitive data through browser tasks unless165Avoid sending secrets or highly sensitive data through browser tasks unless


1762. Close the ChatGPT side panel, restart Chrome, then reopen the extension from1762. Close the ChatGPT side panel, restart Chrome, then reopen the extension from

177 the Chrome toolbar or **Extensions** menu. Confirm the side chat loads. If177 the Chrome toolbar or **Extensions** menu. Confirm the side chat loads. If

178 it doesn't load or mentions a missing native host, remove and re-add the178 it doesn't load or mentions a missing native host, remove and re-add the

179 Chrome plugin from **Plugins** in Work or Codex in the ChatGPT desktop app,179 Chrome plugin from **Plugins** in the ChatGPT desktop app, then follow the

180 then follow the setup flow again.180 setup flow again.

1813. In the app, select Work or Codex, open **Plugins**, and confirm that the1813. In the app, select ChatGPT and switch to Work mode, or select Codex. Open

182 Chrome plugin is on. If the plugin is off, turn it on and182 **Plugins** and confirm that the Chrome plugin is on. If the plugin is off,

183 try the task again.183 turn it on and try the task again.

1844. Make sure you are using the same Chrome profile where the extension is1844. Make sure you are using the same Chrome profile where the extension is

185 installed. If you use more than one Chrome profile, install and enable the185 installed. If you use more than one Chrome profile, install and enable the

186 extension in the active profile.186 extension in the active profile.

1875. Start a new task in Work or Codex and try the Chrome task again. This can1875. Start a new chat in Work mode or Codex and try the Chrome task again. This can

188 clear task-specific connection state.188 clear chat-specific connection state.

1896. Restart the ChatGPT desktop app, then try again. If the extension still1896. Restart the ChatGPT desktop app, then try again. If the extension still

190 doesn't connect, uninstall the Chrome extension, remove and re-add the Chrome190 doesn't connect, uninstall the Chrome extension, remove and re-add the Chrome

191 plugin from **Plugins**, and follow the setup flow again.191 plugin from **Plugins**, and follow the setup flow again.

1927. If the side chat loads but ChatGPT still can't use Chrome, run `/feedback`1927. If the side chat loads but ChatGPT still can't use Chrome, run `/feedback`

193 in the app and include the task ID when you contact support.193 in the app and include the chat ID when you contact support.

194 194 

195### Upload files195### Upload files

196 196 

app/commands.md +35 −29

Details

5## Keyboard shortcuts5## Keyboard shortcuts

6 6 

7| | Action | Shortcut |7| | Action | Shortcut |

8| ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------- |8| ----------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------- |

9| **General** | | |9| **General** | | |

10| | Command menu | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> or <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>K</kbd> |10| | Command menu | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> or <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>K</kbd> |

11| | Settings | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>,</kbd> |11| | Settings | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>,</kbd> |


21| | Toggle bottom panel | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>J</kbd> |21| | Toggle bottom panel | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>J</kbd> |

22| | Toggle terminal | <kbd>Ctrl</kbd> + <kbd>`</kbd> |22| | Toggle terminal | <kbd>Ctrl</kbd> + <kbd>`</kbd> |

23| | Clear the terminal | <kbd>Ctrl</kbd> + <kbd>L</kbd> |23| | Clear the terminal | <kbd>Ctrl</kbd> + <kbd>L</kbd> |

24| **Chat** | Quick Chat | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>N</kbd> |24| **Chat** | Quick chat | <kbd>Cmd</kbd> + <kbd>Option</kbd> + <kbd>N</kbd> (macOS) or <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>N</kbd> (Windows) |

25| **Task** | New task | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>N</kbd> or <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>O</kbd> |25| | New chat | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>N</kbd> or <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>O</kbd> |

26| | Search tasks | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>G</kbd> |26| | Search chats | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>G</kbd> |

27| | Find in task | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>F</kbd> |27| | Find in chat | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>F</kbd> |

28| | Previous task | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>[</kbd> |28| | Previous chat | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>[</kbd> |

29| | Next task | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>]</kbd> |29| | Next chat | <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>]</kbd> |

30| **Input** | Dictation | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>D</kbd> |30| **Input** | Dictation | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>D</kbd> |

31 31 

32To find, customize, or reset shortcuts, open **Settings > Keyboard Shortcuts**.32To find, customize, or reset shortcuts, open **Settings > Keyboard Shortcuts**.

33You can search by command name or switch the search field into keystroke mode33You can search by command name or switch the search field into keystroke mode

34and press the shortcut you want to find.34and press the shortcut you want to find.

35 35 

36## Search past tasks and find in a task36<a id="search-past-tasks-and-find-in-a-task"></a>

37 37 

38Use task search (<kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>G</kbd>) to reopen a past38## Search past chats and find in a chat

39task. When expanded matching is available, it can also match task content and39 

40Git branch names, so you can search for a phrase from the task or a40Use chat search (<kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>G</kbd>) to reopen a past

41chat. When expanded matching is available, it can also match chat content and

42Git branch names, so you can search for a phrase from the chat or a

41branch such as `fix/login-redirect`.43branch such as `fix/login-redirect`.

42 44 

43Use **Find in task** (<kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>F</kbd>) after opening45Use **Find in chat** (<kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>F</kbd>) after opening

44a task to find text within it. It doesn't search across other tasks.46a chat to find text within it. It doesn't search across other chats.

45 47 

46For actions that start with `/`, see [Slash commands](https://learn.chatgpt.com/docs/reference/slash-commands).48For actions that start with `/`, see [Slash commands](https://learn.chatgpt.com/docs/reference/slash-commands).

47 49 


57 59 

58| Deep link | Opens |60| Deep link | Opens |

59| --------------------------------------------------------------------------- | ------------------------------------------------------- |61| --------------------------------------------------------------------------- | ------------------------------------------------------- |

60| `codex://threads/new` | A new local task. |62| `codex://threads/new` | A new local chat. |

61| `codex://new?<query>` | A new local task with at least one query parameter. |63| `codex://new?<query>` | A new local chat with at least one query parameter. |

62| `codex://threads/<thread-id>` | A local task. `<thread-id>` is its technical thread ID. |64| `codex://threads/<thread-id>` | A local chat. `<thread-id>` is its technical thread ID. |

63| `codex://settings` | Settings. |65| `codex://settings` | Settings. |

64| `codex://settings/connections/<connection-type>` | Computer, device, or SSH connection settings. |66| `codex://settings/connections/<connection-type>` | Computer, device, or SSH connection settings. |

65| `codex://settings/connections/ssh/add?name=<ssh-config-host>` | Adds a host from your SSH config to Codex. |67| `codex://settings/connections/ssh/add?name=<ssh-config-host>` | Adds a host from your SSH config to Codex. |


70| `codex://plugins/<plugin-name>?marketplacePath=<absolute-marketplace-path>` | A local plugin detail page from a local marketplace. |72| `codex://plugins/<plugin-name>?marketplacePath=<absolute-marketplace-path>` | A local plugin detail page from a local marketplace. |

71| `codex://pets/install?name=<pet-name>&imageUrl=<https-image-url>` | The pet install flow. |73| `codex://pets/install?name=<pet-name>&imageUrl=<https-image-url>` | The pet install flow. |

72 74 

73### Tasks75<a id="tasks"></a>

76 

77### Chats

74 78 

75Use these links when you need to open an existing local task or start a new one.79Use these links when you need to open an existing local chat or start a new one.

76 80 

77| Deep link | Opens |81| Deep link | Opens |

78| ----------------------------- | ------------------------------------------------------------------------------------------------------------ |82| ----------------------------- | ------------------------------------------------------------------------------------------------------------ |

79| `codex://threads/<thread-id>` | A local task. `<thread-id>` is its technical thread ID. |83| `codex://threads/<thread-id>` | A local chat. `<thread-id>` is its technical thread ID. |

80| `codex://threads/new` | A new local task. |84| `codex://threads/new` | A new local chat. |

81| `codex://threads/new?<query>` | A new local task with optional query parameters. |85| `codex://threads/new?<query>` | A new local chat with optional query parameters. |

82| `codex://new?<query>` | A new local task. Include at least one of `prompt`, `path`, or `originUrl`; otherwise the link does nothing. |86| `codex://new?<query>` | A new local chat. Include at least one of `prompt`, `path`, or `originUrl`; otherwise the link does nothing. |

83 87 

84For `codex://threads/new` or `codex://new`, add any of these query parameters as needed; you can combine them in the same URL.88For `codex://threads/new` or `codex://new`, add any of these query parameters as needed; you can combine them in the same URL.

85 89 

86| Query parameter | Required | What it does |90| Query parameter | Required | What it does |

87| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |91| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |

88| `prompt=<text>` | No | Sets the initial composer text. |92| `prompt=<text>` | No | Sets the initial composer text. |

89| `path=<absolute-path>` | No | Opens the new task in a local workspace. `path` must be an absolute path to a local directory. When valid, Codex uses that directory as the active workspace. |93| `path=<absolute-path>` | No | Opens the new chat in a local workspace. `path` must be an absolute path to a local directory. When valid, Codex uses that directory as the active workspace. |

90| `originUrl=<git-remote-url>` | No | Matches one of your current workspace roots by Git remote URL. If `path` is also present, Codex resolves `path` first. |94| `originUrl=<git-remote-url>` | No | Matches one of your current workspace roots by Git remote URL. If `path` is also present, Codex resolves `path` first. |

91 95 

92Example: [Show me some fun stats about how I've been using Codex](codex://threads/new?prompt=Show%20me%20some%20fun%20stats%20about%20how%20I%27ve%20been%20using%20Codex)96Example: [Show me some fun stats about how I've been using Codex](codex://threads/new?prompt=Show%20me%20some%20fun%20stats%20about%20how%20I%27ve%20been%20using%20Codex)

93 97 

94#### Start a task with a plugin98<a id="start-a-task-with-a-plugin"></a>

99 

100#### Start a chat with a plugin

95 101 

96To help users start a plugin-backed task, include a plugin mention in the102To help users start a plugin-backed chat, include a plugin mention in the

97prompt before you encode it:103prompt before you encode it:

98 104 

99```text105```text


107codex://new?prompt=%5B%40Example%5D(plugin%3A%2F%2Fexample%40openai-curated)%20Summarize%20this%20document%3A%20https%3A%2F%2Fexample.com%2Fdocument%2F123113codex://new?prompt=%5B%40Example%5D(plugin%3A%2F%2Fexample%40openai-curated)%20Summarize%20this%20document%3A%20https%3A%2F%2Fexample.com%2Fdocument%2F123

108```114```

109 115 

110The link opens a new task with the decoded prompt in the composer. It doesn't116The link opens a new chat with the decoded prompt in the composer. It doesn't

111send the prompt automatically. After the user sends it, Codex can use an117send the prompt automatically. After the user sends it, Codex can use an

112installed plugin in that task. If the plugin isn't installed but is available118installed plugin in that chat. If the plugin isn't installed but is available

113to the user, Codex asks the user to install it and connect any required apps.119to the user, Codex asks the user to install it and connect any required connectors.

114After setup, the user can select **Continue** to resume the same task. Workspace120After setup, the user can select **Continue** to resume the same chat. Workspace

115settings can limit which plugins a user can install. For plugin installation121settings can limit which plugins a user can install. For plugin installation

116and permission details, see [Plugins](https://learn.chatgpt.com/docs/plugins).122and permission details, see [Plugins](https://learn.chatgpt.com/docs/plugins).

117 123 

Details

1# Computer Use1# Computer Use

2 2 

3In supported regions, Computer Use in the ChatGPT desktop app is available on3In supported regions, Computer Use in the ChatGPT desktop app is available on

4 macOS and Windows in ChatGPT Work and Codex. Install the Computer Use plugin.4 macOS and Windows in Work mode and Codex. Install the Computer Use plugin. On

5 On macOS, grant Screen Recording and Accessibility permissions when prompted.5 macOS, grant Screen Recording and Accessibility permissions when prompted.

6 6 

7With Computer Use, ChatGPT can see and operate graphical user interfaces on macOS7With Computer Use, ChatGPT can see and operate graphical user interfaces on macOS

8or Windows. Use it for tasks where command-line tools or structured integrations8or Windows. Use it for tasks where command-line tools or structured integrations


16 16 

17## Set up Computer Use17## Set up Computer Use

18 18 

19In the ChatGPT desktop app, select Work or Codex. Open **Plugins > Computer19In the ChatGPT desktop app, select ChatGPT and switch to Work mode, or select

20Codex. Open **Plugins > Computer

20Use** and select **Install plugin** if prompted. If ChatGPT shows **Enable**,21Use** and select **Install plugin** if prompted. If ChatGPT shows **Enable**,

21select it. Turn on the Computer Use server and skill toggles, then select **Try22select it. Turn on the Computer Use server and skill toggles, then select **Try

22now** to start.23now** to start.

app/features.md +7 −7

Details

3<CodexDocsOverviewLanding3<CodexDocsOverviewLanding

4 title="Features"4 title="Features"

5 description="Explore workflows, capabilities, commands, and settings for working in ChatGPT."5 description="Explore workflows, capabilities, commands, and settings for working in ChatGPT."

6 intro="ChatGPT brings projects and long-running tasks together with web browsing, files, images, and plugins. Commands, settings, and troubleshooting references round out these workflows, from choosing the right workflow to giving each task the context and tools it needs."6 intro="ChatGPT brings projects and long-running chats together with web browsing, files, images, and plugins. Commands, settings, and troubleshooting references round out these workflows, from choosing the right workflow to giving each chat the context and tools it needs."

7 primaryCta={{7 primaryCta={{

8 label: "Explore projects and tasks",8 label: "Explore projects and chats",

9 href: "/codex/projects",9 href: "/codex/projects",

10 }}10 }}

11 hero={{11 hero={{

12 illustration: "features-menu",12 illustration: "features-menu",

13 backgroundImage: "/images/codex/codex-wallpaper-1.webp",13 backgroundImage: "/images/codex/codex-wallpaper-1.webp",

14 alt: "Codex sidebar and Add menu for tasks, plugins, and content tools",14 alt: "Codex sidebar and Add menu for chats, plugins, and content tools",

15 }}15 }}

16 sections={[16 sections={[

17 {17 {


19 description: "Ways to organize, delegate, and review work.",19 description: "Ways to organize, delegate, and review work.",

20 pages: [20 pages: [

21 {21 {

22 title: "Projects, chats, and tasks",22 title: "Projects and chats",

23 description: "Keep related chats, tasks, context, and work together.",23 description: "Keep related chats, context, and work together.",

24 href: "/codex/projects",24 href: "/codex/projects",

25 icon: "folder",25 icon: "folder",

26 },26 },


59 },59 },

60 {60 {

61 title: "Pets",61 title: "Pets",

62 description: "Choose an animated companion and follow task activity.",62 description: "Choose an animated companion and follow chat activity.",

63 href: "/codex/pets",63 href: "/codex/pets",

64 icon: "customize",64 icon: "customize",

65 },65 },

66 {66 {

67 title: "Codex Micro",67 title: "Codex Micro",

68 description:68 description:

69 "Monitor and control ChatGPT tasks from a Work Louder keyboard.",69 "Monitor and control ChatGPT chats from a Work Louder keyboard.",

70 href: "/codex/features/codex-micro",70 href: "/codex/features/codex-micro",

71 icon: "key",71 icon: "key",

72 },72 },

Details

13 13 

14## Setup scripts14## Setup scripts

15 15 

16Since worktrees run in different directories than your local tasks, your project might not be fully set up and might be missing dependencies or files that aren't checked into your repository. Setup scripts run automatically when Codex creates a new worktree at the start of a new task.16Since worktrees run in different directories than your local chats, your project might not be fully set up and might be missing dependencies or files that aren't checked into your repository. Setup scripts run automatically when Codex creates a new worktree at the start of a new chat.

17 17 

18Use this script to run any command required to configure your environment, such as installing dependencies or running a build process.18Use this script to run any command required to configure your environment, such as installing dependencies or running a build process.

19 19 

app/review.md +4 −4

Details

58 58 

59Review findings appear as inline comments in the review pane.59Review findings appear as inline comments in the review pane.

60 60 

61Reviews run in the current task by default. Under **Settings** > **General** >61Reviews run in the current chat by default. Under **Settings** > **General** >

62**Code review**, choose **Detached** to start a separate review task. See62**Code review**, choose **Detached** to start a separate review chat. See

63[developer settings](https://learn.chatgpt.com/docs/developer-settings?surface=app#app-code-review).63[developer settings](https://learn.chatgpt.com/docs/developer-settings?surface=app#app-code-review).

64 64 

65<CodexScreenshot65<CodexScreenshot


1052. Hover over the line you want to comment on.1052. Hover over the line you want to comment on.

1063. Select the **+** button that appears.1063. Select the **+** button that appears.

1074. Write your feedback and submit it.1074. Write your feedback and submit it.

1085. After you finish leaving feedback, send a message back to the task.1085. After you finish leaving feedback, send a message back to the chat.

109 109 

110Because comments are line-specific, Codex can respond more precisely than with110Because comments are line-specific, Codex can respond more precisely than with

111a general instruction.111a general instruction.


120the pull request branch, the ChatGPT desktop app can help you work through pull120the pull request branch, the ChatGPT desktop app can help you work through pull

121request feedback without leaving the app. The sidebar shows pull request121request feedback without leaving the app. The sidebar shows pull request

122context and feedback from reviewers, and the review pane shows comments122context and feedback from reviewers, and the review pane shows comments

123alongside the diff so you can ask Codex to address issues in the same task.123alongside the diff so you can ask Codex to address issues in the same chat.

124 124 

125Install the GitHub CLI (`gh`) and authenticate it with `gh auth login` so Codex125Install the GitHub CLI (`gh`) and authenticate it with `gh auth login` so Codex

126can load pull request context, review comments, and changed files. If `gh` is126can load pull request context, review comments, and changed files. If `gh` is

app/settings.md +15 −11

Details

8## General8## General

9 9 

10Require <kbd>Cmd</kbd>+<kbd>Enter</kbd> for multiline prompts, or turn on10Require <kbd>Cmd</kbd>+<kbd>Enter</kbd> for multiline prompts, or turn on

11**Prevent sleep while running** so local tasks can continue while you step away.11**Prevent sleep while running** so local chats can continue while you step away.

12Under **Follow-up behavior**, choose whether a message sent while ChatGPT works12Under **Follow-up behavior**, choose whether a message sent while ChatGPT works

13should steer the current run or wait for the next run.13should steer the current run or wait for the next run.

14 14 


61 **Tuck Away Pet** to control the floating overlay.61 **Tuck Away Pet** to control the floating overlay.

62 62 

63 See [Pets](https://learn.chatgpt.com/docs/pets?surface=app) to understand pet status, follow63 See [Pets](https://learn.chatgpt.com/docs/pets?surface=app) to understand pet status, follow

64 activity across tasks, or create your own pet.64 activity across chats, or create your own pet.

65 65 

66 </div>66 </div>

67 67 


102## Memories102## Memories

103 103 

104Enable Memories, where available, to let ChatGPT carry useful context from past104Enable Memories, where available, to let ChatGPT carry useful context from past

105chats and tasks into future work. See [Memories](https://learn.chatgpt.com/docs/customization/memories)105chats into future work. See [Memories](https://learn.chatgpt.com/docs/customization/memories)

106for setup, storage, and controls for individual chats and tasks.106for setup, storage, and controls for individual chats.

107 107 

108## Archived tasks108<a id="archived-tasks"></a>

109 109 

110The **Archived tasks** section lists archived tasks with dates and project110## Archived chats

111context. Use **Unarchive** to restore a task.

112 111 

112The **Archived chats** section lists archived chats with dates and project

113context. Use **Unarchive** to restore a chat.

114 

115<a id="keep-an-app-task-near-your-work"></a>

113<a id="keep-an-app-chat-near-your-work"></a>116<a id="keep-an-app-chat-near-your-work"></a>

117<a id="keep-a-task-near-your-work"></a>

114 118 

115## Keep a task near your work119## Keep a chat near your work

116 120 

117In the ChatGPT desktop app, pop out an active task into a separate window and place it121In the ChatGPT desktop app, pop out an active chat into a separate window and place it

118next to your browser, editor, or design preview. Turn on **Always on top** when122next to your browser, editor, or design preview. Turn on **Always on top** when

119you want the task to remain visible while you work in another app.123you want the chat to remain visible while you work in another app.

120 124 

121<CodexScreenshot125<CodexScreenshot

122 alt="ChatGPT desktop app task displayed in a floating pop-out window"126 alt="ChatGPT desktop app chat displayed in a floating pop-out window"

123 lightSrc="/images/codex/app/popover-light.webp"127 lightSrc="/images/codex/app/popover-light.webp"

124 darkSrc="/images/codex/app/popover-dark.webp"128 darkSrc="/images/codex/app/popover-dark.webp"

125 maxHeight="400px"129 maxHeight="400px"

Details

20 20 

21To remove a project from the sidebar, hover over the name of your project, click21To remove a project from the sidebar, hover over the name of your project, click

22the three dots and choose "Remove." To restore it, re-add the22the three dots and choose "Remove." To restore it, re-add the

23project using the **Add new project** button next to **Tasks** or using23project using the **Add new project** button next to **Chats** or using

24 24 

25<kbd>Cmd</kbd>+<kbd>O</kbd>.25<kbd>Cmd</kbd>+<kbd>O</kbd>.

26 26 

27<a id="find-archived-threads"></a>27<a id="find-archived-threads"></a>

28<a id="find-archived-chats"></a>28<a id="find-archived-tasks"></a>

29 29 

30### Find archived tasks30### Find archived chats

31 31 

32Archived tasks can be found in [Settings](codex://settings). When you unarchive32Archived chats can be found in [Settings](codex://settings). When you unarchive

33a task, it reappears in its original sidebar location.33a chat, it reappears in its original sidebar location.

34 34 

35<a id="only-some-threads-appear-in-the-sidebar"></a>35<a id="only-some-threads-appear-in-the-sidebar"></a>

36<a id="only-some-chats-appear-in-the-sidebar"></a>36<a id="only-some-tasks-appear-in-the-sidebar"></a>

37 37 

38### Only some tasks appear in the sidebar38### Only some chats appear in the sidebar

39 39 

40The sidebar lets you filter tasks based on the state of a project. If you're40The sidebar lets you filter chats based on the state of a project. If you're

41missing tasks, select the filter icon next to **Tasks**, then select41missing chats, select the filter icon next to **Chats**, then select

42**Chronological**. If you still don't see the task, open42**Chronological**. If you still don't see the chat, open

43[Settings](codex://settings) and check **Archived tasks**.43[Settings](codex://settings) and check **Archived chats**.

44 44 

45### Code doesn't run on a worktree45### Code doesn't run on a worktree

46 46 


76 76 

77### Recover a prompt after selecting the wrong target77### Recover a prompt after selecting the wrong target

78 78 

79If you started a task with the wrong target (**Local**, **Worktree**, or **Cloud**) by accident, you can cancel the current run and recover your previous prompt by pressing the up arrow key in the composer.79If you started a chat with the wrong target (**Local**, **Worktree**, or **Cloud**) by accident, you can cancel the current run and recover your previous prompt by pressing the up arrow key in the composer.

80 80 

81### Feature is working in the Codex CLI but not in the ChatGPT desktop app81### Feature is working in the Codex CLI but not in the ChatGPT desktop app

82 82 


100## Feedback and logs100## Feedback and logs

101 101 

102Type <kbd>/</kbd> into the message composer to provide feedback for the team. If102Type <kbd>/</kbd> into the message composer to provide feedback for the team. If

103you trigger feedback in an existing conversation, you can choose to share the103you trigger feedback in an existing chat, you can choose to share the

104existing session along with your feedback. After submitting your feedback,104existing session along with your feedback. After submitting your feedback,

105you'll receive a session ID that you can share with the team.105you'll receive a session ID that you can share with the team.

106 106 


120 120 

121## Stuck states and recovery patterns121## Stuck states and recovery patterns

122 122 

123If a task appears stuck:123If a chat appears stuck:

124 124 

1251. Check whether Codex is waiting for an approval.1251. Check whether Codex is waiting for an approval.

1262. Open the terminal and run a basic command like `git status`.1262. Open the terminal and run a basic command like `git status`.

1273. Start a new task with a smaller, more focused prompt.1273. Start a new chat with a smaller, more focused prompt.

128 128 

129If you cancel worktree creation by mistake and lose your prompt, press the up129If you cancel worktree creation by mistake and lose your prompt, press the up

130arrow key in the composer to recover it.130arrow key in the composer to recover it.


140If commands behave differently than expected, validate the current directory and140If commands behave differently than expected, validate the current directory and

141branch in the terminal first.141branch in the terminal first.

142 142 

143If it continues to be stuck, wait until your active tasks are complete and restart the app.143If it continues to be stuck, wait until your active chats are complete and restart the app.

144 144 

145**Fonts aren't rendering correctly**145**Fonts aren't rendering correctly**

146 146 

app/windows.md +3 −3

Details

1# ChatGPT desktop app for Windows1# ChatGPT desktop app for Windows

2 2 

3The [ChatGPT desktop app for Windows](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi) gives you one interface for3The [ChatGPT desktop app for Windows](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi) gives you one interface for

4working across projects, running parallel tasks, and reviewing results.4working across projects, running parallel chats, and reviewing results.

5The Windows app supports core workflows such as worktrees, scheduled tasks, Git5The Windows app supports core workflows such as worktrees, scheduled tasks, Git

6functionality, the built-in browser, file previews, plugins, and skills.6functionality, the built-in browser, file previews, plugins, and skills.

7It runs natively on Windows using PowerShell and the7It runs natively on Windows using PowerShell and the


9run in [Windows Subsystem for Linux 2 (WSL2)](#windows-subsystem-for-linux-wsl).9run in [Windows Subsystem for Linux 2 (WSL2)](#windows-subsystem-for-linux-wsl).

10 10 

11<CodexScreenshot11<CodexScreenshot

12 alt="ChatGPT desktop app for Windows showing a project sidebar, active task, and review pane"12 alt="ChatGPT desktop app for Windows showing a project sidebar, active chat, and review pane"

13 lightSrc="/images/codex/windows/codex-windows-light.webp"13 lightSrc="/images/codex/windows/codex-windows-light.webp"

14 darkSrc="/images/codex/windows/codex-windows-dark.webp"14 darkSrc="/images/codex/windows/codex-windows-dark.webp"

15 variant="no-wallpaper"15 variant="no-wallpaper"


84- WSL84- WSL

85 85 

86This change applies only to new terminal sessions. If you already have an86This change applies only to new terminal sessions. If you already have an

87integrated terminal open, restart the app or start a new task before87integrated terminal open, restart the app or start a new chat before

88expecting the new default terminal to appear.88expecting the new default terminal to appear.

89 89 

90</div>90</div>

app/worktrees.md +33 −32

Details

1# Worktrees1# Worktrees

2 2 

3In the ChatGPT desktop app, worktrees let Codex run multiple independent tasks in the same project without interfering with each other. For Git repositories, [scheduled tasks](https://learn.chatgpt.com/docs/automations) can run on dedicated background worktrees so they don't conflict with your ongoing work. In non-version-controlled projects, scheduled tasks run directly in the project directory. You can also start tasks in a worktree manually and use Handoff to move a task between Local and Worktree.3In the ChatGPT desktop app, worktrees let Codex run multiple independent chats in the same project without interfering with each other. For Git repositories, [scheduled tasks](https://learn.chatgpt.com/docs/automations) can run on dedicated background worktrees so they don't conflict with your ongoing work. In non-version-controlled projects, scheduled tasks run directly in the project directory. You can also start chats in a worktree manually and use Handoff to move a chat between Local and Worktree.

4 4 

5Worktrees are available only in Codex in the ChatGPT desktop app. Select5Worktrees are available only in Codex in the ChatGPT desktop app. Select

6 **Codex** before you start a task in a worktree.6 **Codex** before you start a chat in a worktree.

7 7 

8## What's a worktree8## What's a worktree

9 9 


13 13 

14- **Local checkout**: The repository that you created. Sometimes just referred to as **Local** in the ChatGPT desktop app.14- **Local checkout**: The repository that you created. Sometimes just referred to as **Local** in the ChatGPT desktop app.

15- **Worktree**: A [Git worktree](https://git-scm.com/docs/git-worktree) that was created from your local checkout in the ChatGPT desktop app.15- **Worktree**: A [Git worktree](https://git-scm.com/docs/git-worktree) that was created from your local checkout in the ChatGPT desktop app.

16- **Handoff**: The flow that moves a task between Local and Worktree. Codex handles the Git operations required to move your work safely between them.16- **Handoff**: The flow that moves a chat between Local and Worktree. Codex handles the Git operations required to move your work safely between them.

17 17 

18## Why use a worktree18## Why use a worktree

19 19 

201. Work in parallel with Codex without disturbing your current Local setup.201. Work in parallel with Codex without disturbing your current Local setup.

212. Queue up background work while you stay focused on the foreground.212. Queue up background work while you stay focused on the foreground.

223. Move a task into Local later when you're ready to inspect, test, or collaborate more directly.223. Move a chat into Local later when you're ready to inspect, test, or collaborate more directly.

23 23 

24## Getting started24## Getting started

25 25 


29 29 

301. Select "Worktree"301. Select "Worktree"

31 31 

32 In the new task view, select **Worktree** under the composer.32 In the new chat view, select **Worktree** under the composer.

33 Optionally, choose a [local environment](https://learn.chatgpt.com/docs/environments/local-environment) to run setup scripts for the worktree.33 Optionally, choose a [local environment](https://learn.chatgpt.com/docs/environments/local-environment) to run setup scripts for the worktree.

34 34 

352. Select the starting branch352. Select the starting branch


42 42 

434. Choose where to keep working434. Choose where to keep working

44 44 

45 When you're ready, you can either keep working directly on the worktree or hand the task off to your local checkout. Handing off to or from Local moves your task _and_ code so you can continue in the other checkout.45 When you're ready, you can either keep working directly on the worktree or hand the chat off to your local checkout. Handing off to or from Local moves your chat _and_ code so you can continue in the other checkout.

46 46 

47</WorkflowSteps>47</WorkflowSteps>

48 48 

49## Working between Local and Worktree49## Working between Local and Worktree

50 50 

51Worktrees look and feel much like your local checkout. The difference is where they fit into your flow. You can think of Local as the foreground and Worktree as the background. Handoff lets you move a task between them.51Worktrees look and feel much like your local checkout. The difference is where they fit into your flow. You can think of Local as the foreground and Worktree as the background. Handoff lets you move a chat between them.

52 52 

53Under the hood, Handoff handles the Git operations required to move work between two checkouts safely. This matters because **Git only allows a branch to be checked out in one place at a time**. If you check out a branch on a worktree, you **can't** check it out in your local checkout at the same time, and vice versa.53Under the hood, Handoff handles the Git operations required to move work between two checkouts safely. This matters because **Git only allows a branch to be checked out in one place at a time**. If you check out a branch on a worktree, you **can't** check it out in your local checkout at the same time, and vice versa.

54 54 

55In practice, there are two common paths:55In practice, there are two common paths:

56 56 

571. [Work exclusively on the worktree](#option-1-working-on-the-worktree). This path works best when you can verify changes directly on the worktree, for example because you have dependencies and tools installed using a [local environment setup script](https://learn.chatgpt.com/docs/environments/local-environment).571. [Work exclusively on the worktree](#option-1-working-on-the-worktree). This path works best when you can verify changes directly on the worktree, for example because you have dependencies and tools installed using a [local environment setup script](https://learn.chatgpt.com/docs/environments/local-environment).

582. [Hand the task off to Local](#option-2-handing-a-task-off-to-local). Use this when you want to bring the task into the foreground, for example because you want to inspect changes in your usual IDE or can run only one instance of your app.582. [Hand the chat off to Local](#option-2-handing-a-chat-off-to-local). Use this when you want to bring the chat into the foreground, for example because you want to inspect changes in your usual IDE or can run only one instance of your app.

59 59 

60### Option 1: Working on the worktree60### Option 1: Working on the worktree

61 61 


63 63 

64<div>64<div>

65 65 

66If you want to stay exclusively on the worktree with your changes, turn your worktree into a branch using the **Create branch here** button in the task header.66If you want to stay exclusively on the worktree with your changes, turn your worktree into a branch using the **Create branch here** button in the chat header.

67 67 

68From here you can commit your changes, push your branch to your remote repository, and open a pull request on GitHub.68From here you can commit your changes, push your branch to your remote repository, and open a pull request on GitHub.

69 69 


72</div>72</div>

73 73 

74<CodexScreenshot74<CodexScreenshot

75 alt="Worktree task view with branch controls and worktree details"75 alt="Worktree chat view with branch controls and worktree details"

76 lightSrc="/images/codex/app/worktree-light.webp"76 lightSrc="/images/codex/app/worktree-light.webp"

77 darkSrc="/images/codex/app/worktree-dark.webp"77 darkSrc="/images/codex/app/worktree-dark.webp"

78 maxHeight="400px"78 maxHeight="400px"


85 85 

86<a id="option-2-handing-a-thread-off-to-local"></a>86<a id="option-2-handing-a-thread-off-to-local"></a>

87<a id="option-2-handing-a-chat-off-to-local"></a>87<a id="option-2-handing-a-chat-off-to-local"></a>

88<a id="option-2-handing-a-task-off-to-local"></a>

88 89 

89### Option 2: Handing a task off to Local90### Option 2: Handing a chat off to Local

90 91 

91<div class="feature-grid">92<div class="feature-grid">

92 93 

93<div>94<div>

94 95 

95If you want to bring a task into the foreground, select **Hand off** in the task header and move it to **Local**.96If you want to bring a chat into the foreground, select **Hand off** in the chat header and move it to **Local**.

96 97 

97This path works well when you want to read the changes in your usual IDE window, run your existing development server, or validate the work in the same environment you already use day to day.98This path works well when you want to read the changes in your usual IDE window, run your existing development server, or validate the work in the same environment you already use day to day.

98 99 

99Codex handles the Git steps required to move the task safely between the worktree and your local checkout.100Codex handles the Git steps required to move the chat safely between the worktree and your local checkout.

100 101 

101Each task keeps the same associated worktree over time. If you hand the task back to a worktree later, Codex returns it to that same background environment so you can pick up where you left off.102Each chat keeps the same associated worktree over time. If you hand the chat back to a worktree later, Codex returns it to that same background environment so you can pick up where you left off.

102 103 

103</div>104</div>

104 105 

105<CodexScreenshot106<CodexScreenshot

106 alt="Handoff dialog moving a task from a worktree to Local"107 alt="Handoff dialog moving a chat from a worktree to Local"

107 lightSrc="/images/codex/app/handoff-light.webp"108 lightSrc="/images/codex/app/handoff-light.webp"

108 darkSrc="/images/codex/app/handoff-dark.webp"109 darkSrc="/images/codex/app/handoff-dark.webp"

109 maxHeight="400px"110 maxHeight="400px"


112 113 

113</div>114</div>

114 115 

115You can also go the other direction. If you're already working in Local and want to free up the foreground, use **Hand off** to move the task to a worktree. This is useful when you want Codex to keep working in the background while you switch your attention back to something else locally.116You can also go the other direction. If you're already working in Local and want to free up the foreground, use **Hand off** to move the chat to a worktree. This is useful when you want Codex to keep working in the background while you switch your attention back to something else locally.

116 117 

117Since Handoff uses Git operations, any files that are part of your `.gitignore` file won't move with the task unless Codex copies them into a local managed worktree with `.worktreeinclude`.118Since Handoff uses Git operations, any files that are part of your `.gitignore` file won't move with the chat unless Codex copies them into a local managed worktree with `.worktreeinclude`.

118 119 

119## Advanced details120## Advanced details

120 121 

121### Codex-managed and permanent worktrees122### Codex-managed and permanent worktrees

122 123 

123By default, tasks use a Codex-managed worktree. These are meant to feel lightweight and disposable. A Codex-managed worktree is typically dedicated to one task, and Codex returns that task to the same worktree if you hand it back there later.124By default, chats use a Codex-managed worktree. These are meant to feel lightweight and disposable. A Codex-managed worktree is typically dedicated to one chat, and Codex returns that chat to the same worktree if you hand it back there later.

124 125 

125If you want a long-lived environment, create a permanent worktree from the three-dot menu on a project in the sidebar. This creates a new permanent worktree as its own project. Permanent worktrees aren't automatically deleted, and you can start multiple tasks from the same worktree.126If you want a long-lived environment, create a permanent worktree from the three-dot menu on a project in the sidebar. This creates a new permanent worktree as its own project. Permanent worktrees aren't automatically deleted, and you can start multiple chats from the same worktree.

126 127 

127### How Codex manages worktrees for you128### How Codex manages worktrees for you

128 129 

129Codex creates worktrees in `$CODEX_HOME/worktrees`. The starting commit is the `HEAD` commit of the branch selected when you start your task. If you chose a branch with local changes, Codex applies the uncommitted changes to the worktree as well. The worktree isn't checked out as a branch. It's in a [detached HEAD](https://git-scm.com/docs/git-checkout#_detached_head) state. This lets Codex create several worktrees without polluting your branches.130Codex creates worktrees in `$CODEX_HOME/worktrees`. The starting commit is the `HEAD` commit of the branch selected when you start your chat. If you chose a branch with local changes, Codex applies the uncommitted changes to the worktree as well. The worktree isn't checked out as a branch. It's in a [detached HEAD](https://git-scm.com/docs/git-checkout#_detached_head) state. This lets Codex create several worktrees without polluting your branches.

130 131 

131### Copy ignored local files into managed worktrees132### Copy ignored local files into managed worktrees

132 133 


155 156 

156To resolve this, you would need to check out another branch instead of `feature/a` on the worktree.157To resolve this, you would need to check out another branch instead of `feature/a` on the worktree.

157 158 

158If you plan on checking out the branch locally, use Handoff to move the task into Local instead of trying to keep the same branch checked out in both places at once.159If you plan on checking out the branch locally, use Handoff to move the chat into Local instead of trying to keep the same branch checked out in both places at once.

159 160 

160<ToggleSection title="Why this limitation exists">161<ToggleSection title="Why this limitation exists">

161Git prevents the same branch from being checked out in more than one worktree at a time because a branch represents a single mutable reference (`refs/heads/<name>`) whose meaning is “the current checked-out state” of a working tree.162Git prevents the same branch from being checked out in more than one worktree at a time because a branch represents a single mutable reference (`refs/heads/<name>`) whose meaning is “the current checked-out state” of a working tree.


174 175 

175Codex tries to avoid deleting worktrees that are still important. Codex-managed worktrees won't be deleted automatically if:176Codex tries to avoid deleting worktrees that are still important. Codex-managed worktrees won't be deleted automatically if:

176 177 

177- A pinned conversation is tied to it178- A pinned chat is tied to it

178- The task is still in progress179- The chat is still in progress

179- The worktree is a permanent worktree180- The worktree is a permanent worktree

180 181 

181Codex-managed worktrees are deleted automatically when:182Codex-managed worktrees are deleted automatically when:

182 183 

183- You archive the associated task184- You archive the associated chat

184- Codex needs to delete older worktrees to stay within your configured limit185- Codex needs to delete older worktrees to stay within your configured limit

185 186 

186Before deleting a Codex-managed worktree, Codex saves a snapshot of the work on it. If you open a conversation after its worktree was deleted, you'll see the option to restore it.187Before deleting a Codex-managed worktree, Codex saves a snapshot of the work on it. If you open a chat after its worktree was deleted, you'll see the option to restore it.

187 188 

188## Frequently asked questions189## Frequently asked questions

189 190 


195 196 

196<a id="can-i-move-a-chat-between-local-and-worktree"></a>197<a id="can-i-move-a-chat-between-local-and-worktree"></a>

197 198 

198<ToggleSection title="Can I move a task between Local and Worktree?">199<ToggleSection title="Can I move a chat between Local and Worktree?">

199 Yes. Use **Hand off** in the task header to move a task between your local200 Yes. Use **Hand off** in the chat header to move a chat between your local

200 checkout and a worktree. Codex handles the Git operations needed to move the201 checkout and a worktree. Codex handles the Git operations needed to move the

201 task safely between environments. If you hand a task back to a worktree later,202 chat safely between environments. If you hand a chat back to a worktree later,

202 Codex returns it to the same associated worktree.203 Codex returns it to the same associated worktree.

203</ToggleSection>204</ToggleSection>

204 205 

205<a id="what-happens-to-chats-if-a-worktree-is-deleted"></a>206<a id="what-happens-to-chats-if-a-worktree-is-deleted"></a>

206 207 

207<ToggleSection title="What happens to tasks if a worktree is deleted?">208<ToggleSection title="What happens to chats if a worktree is deleted?">

208 Tasks can remain in your history even if the underlying worktree directory is209 Chats can remain in your history even if the underlying worktree directory is

209 deleted. For Codex-managed worktrees, Codex saves a snapshot before deleting210 deleted. For Codex-managed worktrees, Codex saves a snapshot before deleting

210 the worktree and offers to restore it if you reopen the associated task.211 the worktree and offers to restore it if you reopen the associated chat.

211 Permanent worktrees are not automatically deleted when you archive their212 Permanent worktrees are not automatically deleted when you archive their

212 tasks.213 chats.

213</ToggleSection>214</ToggleSection>

appshots.md +10 −10

Details

1# Appshots1# Appshots

2 2 

3Appshots let you send the frontmost app window to a task in ChatGPT. Use them when3Appshots let you send the frontmost app window to a chat in ChatGPT. Use them when

4you're actively working in another app on your computer and want to provide4you're actively working in another app on your computer and want to provide

5ChatGPT with your current context so it can help you with the task.5ChatGPT with your current context so it can help you with the task.

6 6 


15- Available text from that window, including visible text and text the app makes15- Available text from that window, including visible text and text the app makes

16 available outside the visible scroll area.16 available outside the visible scroll area.

17 17 

18After you add an appshot to a task, it behaves like an attachment. ChatGPT18After you add an appshot to a chat, it behaves like an attachment. ChatGPT

19stores appshots locally in the session file, like files or images you attach19stores appshots locally in the session file, like files or images you attach

20manually.20manually.

21 21 


403. Allow macOS permissions if ChatGPT asks.403. Allow macOS permissions if ChatGPT asks.

414. Ask ChatGPT to perform a task with the appshot.414. Ask ChatGPT to perform a task with the appshot.

42 42 

43<Illustration description="ChatGPT task composer with an Appshot attachment and follow-up prompt">43<Illustration description="ChatGPT chat composer with an Appshot attachment and follow-up prompt">

44 <AppshotsComposerIllustration ariaLabel="ChatGPT task composer with an Appshot attachment and follow-up prompt" />44 <AppshotsComposerIllustration ariaLabel="ChatGPT chat composer with an Appshot attachment and follow-up prompt" />

45</Illustration>45</Illustration>

46 46 

47By default, ChatGPT starts a new task for the appshot. If you interacted with a47By default, ChatGPT starts a new chat for the appshot. If you interacted with a

48task in the last 60 seconds, ChatGPT adds the appshot to that recent48chat in the last 60 seconds, ChatGPT adds the appshot to that recent

49task instead. Taking consecutive appshots adds them to the same task.49chat instead. Taking consecutive appshots adds them to the same chat.

50 50 

51You can change the Appshots hotkey in the app settings.51You can change the Appshots hotkey in the app settings.

52 52 


67 67 

68## Limits and troubleshooting68## Limits and troubleshooting

69 69 

70Appshots are available in the ChatGPT desktop app on macOS. If you resume a task70Appshots are available in the ChatGPT desktop app on macOS. If you resume a chat

71in the CLI that already contains an appshot, the attachment is part of the task71in the CLI that already contains an appshot, the attachment is part of the chat

72history, but the CLI can't create a new appshot.72history, but the CLI can't create a new appshot.

73 73 

74For some apps and websites, including Google Docs, Gmail, Google Sheets, and74For some apps and websites, including Google Docs, Gmail, Google Sheets, and

75Google Slides, ChatGPT may receive only the visible screenshot and may not receive75Google Slides, ChatGPT may receive only the visible screenshot and may not receive

76the full document or off-screen text. In ChatGPT Work or Codex, ChatGPT can use a76the full document or off-screen text. In Work mode or Codex, ChatGPT can use a

77matching installed plugin to access the relevant app content and help with your77matching installed plugin to access the relevant app content and help with your

78request.78request.

79 79 

Details

69 69 

70## Review and refine files70## Review and refine files

71 71 

72Use the task sidebar while a task runs. It can surface the agent's plan,72Use the chat sidebar while a task runs. It can surface the agent's plan,

73sources, generated files, and task summary so you can steer the work,73sources, generated files, and chat summary so you can steer the work,

74inspect generated files, and request another pass.74inspect generated files, and request another pass.

75 75 

76Ask ChatGPT to explain where it saved each file and how it verified the76Ask ChatGPT to explain where it saved each file and how it verified the

automations.md +17 −16

Details

25<a id="scheduled-tasks-in-threads"></a>25<a id="scheduled-tasks-in-threads"></a>

26<a id="scheduled-tasks-in-chats"></a>26<a id="scheduled-tasks-in-chats"></a>

27<a id="schedule-work-from-a-task"></a>27<a id="schedule-work-from-a-task"></a>

28<a id="schedule-a-task-inside-a-chat"></a>

28<a id="test-automations"></a>29<a id="test-automations"></a>

29<a id="test-scheduled-tasks"></a>30<a id="test-scheduled-tasks"></a>

30<a id="worktree-cleanup-for-automations"></a>31<a id="worktree-cleanup-for-automations"></a>


42 43 

43For example, schedule a task to evaluate telemetry errors and submit fixes,44For example, schedule a task to evaluate telemetry errors and submit fixes,

44or to create reports about recent codebase changes. For ongoing work that45or to create reports about recent codebase changes. For ongoing work that

45should keep using the same context, [schedule work from an existing task](#schedule-work-from-a-task).46should keep using the same context, [schedule a task inside an existing chat](#schedule-a-task-inside-a-chat).

46 47 

47For project-scoped scheduled tasks, keep the machine powered on and the ChatGPT48For project-scoped scheduled tasks, keep the machine powered on and the ChatGPT

48desktop app running. The selected project must still be available on disk when49desktop app running. The selected project must still be available on disk when


84 />85 />

85</Illustration>86</Illustration>

86 87 

87Standalone scheduled tasks start a new task for each scheduled run and report88Standalone scheduled tasks start a new chat for each scheduled run and report

88results in **Scheduled**. Use them when each run should be independent or when one89results in **Scheduled**. Use them when each run should be independent or when one

89scheduled task should run across one or more projects. If you need a custom90scheduled task should run across one or more projects. If you need a custom

90cadence, use the custom schedule controls. For an advanced schedule, edit its91cadence, use the custom schedule controls. For an advanced schedule, edit its


103 104 

104 105 

105 106 

106Scheduled tasks in ChatGPT Work on the web or in Work or Codex in the ChatGPT desktop107Scheduled tasks in Work mode on the web, or in Work mode or Codex in the ChatGPT

107app can use plugins. Scheduled tasks can also use skills. To keep scheduled108desktop app, can use plugins. Scheduled tasks can also use skills. To keep scheduled

108tasks maintainable and shareable across teams, use [skills](https://learn.chatgpt.com/docs/build-skills) to109tasks maintainable and shareable across teams, use [skills](https://learn.chatgpt.com/docs/build-skills) to

109define the action and provide tools and context. Select or invoke a specific110define the action and provide tools and context. Select or invoke a specific

110skill in the task prompt when the workflow shouldn't rely on automatic tool111skill in the task prompt when the workflow shouldn't rely on automatic tool


112 113 

113## Ask ChatGPT to create or update scheduled tasks114## Ask ChatGPT to create or update scheduled tasks

114 115 

115You can create and update scheduled tasks from a Work or Codex task in ChatGPT.116You can create and update scheduled tasks from a ChatGPT or Codex chat.

116Describe the work, the schedule, and whether each scheduled run should return to117Describe the work, the schedule, and whether each scheduled run should return to

117the current task or start a new task. ChatGPT can draft the prompt, choose the118the current chat or start a new chat. ChatGPT can draft the prompt, choose the

118right destination, and update the scheduled task when its scope or cadence119right destination, and update the scheduled task when its scope or cadence

119changes.120changes.

120 121 

121For example, ask ChatGPT to schedule a follow-up from the current task while a122For example, ask ChatGPT to schedule a follow-up from the current chat while a

122deployment finishes, or ask it to create a standalone scheduled task that checks123deployment finishes, or ask it to create a standalone scheduled task that checks

123a project on a recurring schedule.124a project on a recurring schedule.

124 125 


126babysitting a pull request could set up a scheduled task that checks the127babysitting a pull request could set up a scheduled task that checks the

127PR status with the GitHub plugin and fixes new review feedback.128PR status with the GitHub plugin and fixes new review feedback.

128 129 

129## Schedule work from a task130## Schedule a task inside a chat

130 131 

131Schedule work from an existing task when you want ChatGPT to return to that task132Schedule a task inside an existing chat when you want ChatGPT to return to that chat

132on a schedule. The scheduled work uses the task's existing context instead of133on a schedule. The scheduled task uses the chat's existing context instead of

133starting from a new prompt each time.134starting from a new prompt each time.

134 135 

135Scheduled work in a task can use minute-based intervals for active follow-up136Scheduled tasks in a chat can use minute-based intervals for active follow-up

136loops, or daily and weekly schedules when you need a check-in at a specific137loops, or daily and weekly schedules when you need a check-in at a specific

137time.138time.

138 139 

139Schedule work from a task for:140Schedule a task inside a chat for:

140 141 

141- checking a long-running operation until it finishes142- checking a long-running operation until it finishes

142- polling Slack, GitHub, or another connected source when the results should143- polling Slack, GitHub, or another connected source when the results should

143 stay in the same task144 stay in the same chat

144- reminding ChatGPT to continue a review loop at a fixed cadence145- reminding ChatGPT to continue a review loop at a fixed cadence

145- running a skill-driven workflow that uses plugins, such as checking PR status146- running a skill-driven workflow that uses plugins, such as checking PR status

146 and addressing new feedback147 and addressing new feedback

147- continuing an ongoing research or triage task without losing its context148- continuing an ongoing research or triage chat without losing its context

148 149 

149Use a standalone scheduled task when each run should be independent or when150Use a standalone scheduled task when each run should be independent or when

150findings should appear as separate runs in **Scheduled**.151findings should appear as separate runs in **Scheduled**.

151 152 

152When you schedule work from a task, make the prompt durable. It should describe153When you schedule a task inside a chat, make the prompt durable. It should describe

153what ChatGPT should do on each scheduled run, how to decide whether there is154what ChatGPT should do on each scheduled run, how to decide whether there is

154anything important to report, and when to stop or ask you for input.155anything important to report, and when to stop or ask you for input.

155 156 

156## Test scheduled tasks157## Test scheduled tasks

157 158 

158Before you schedule a task, test the prompt manually in a regular task159Before you schedule a task, test the prompt manually in a regular chat

159first. This helps you confirm:160first. This helps you confirm:

160 161 

161- The prompt is clear and scoped correctly.162- The prompt is clear and scoped correctly.

browser.md +9 −8

Details

12 12 

13 13 

14The built-in browser in the ChatGPT desktop app gives you and ChatGPT a shared14The built-in browser in the ChatGPT desktop app gives you and ChatGPT a shared

15view of websites and local web apps inside a task. Use it to preview a page,15view of websites and local web apps inside a chat. Use it to preview a page,

16leave visual feedback, or let ChatGPT interact with a site on your behalf.16leave visual feedback, or let ChatGPT interact with a site on your behalf.

17 17 

18The built-in browser uses a browser profile that is separate from your regular18The built-in browser uses a browser profile that is separate from your regular


44 44 

45## Computer Use in the browser45## Computer Use in the browser

46 46 

47Computer Use lets ChatGPT operate the built-in browser directly. ChatGPT can47In the desktop app, Computer Use lets ChatGPT in Work mode or Codex operate the

48open pages, click, type, inspect rendered state, take screenshots, and verify48built-in browser directly. The selected experience can open pages, click, type,

49the result of its work in the page.49inspect rendered state, take screenshots, and verify the result of its work in

50the page.

50 51 

51In the desktop app, open the Plugins Directory and install **Browser**. Then ask52Select ChatGPT and switch to Work mode, or select Codex. Open the Plugins

52ChatGPT to use the browser in your task, or reference it directly with53Directory and install **Browser**. Then ask ChatGPT or Codex to use the browser

53`@Browser`.54in your task, or reference it directly with `@Browser`.

54 55 

55For example:56For example:

56 57 


931. Turn on **Annotation mode**.941. Turn on **Annotation mode**.

942. Click an element, or drag to select an area.952. Click an element, or drag to select an area.

953. Write and save your comment.963. Write and save your comment.

964. Send a message in the task asking ChatGPT to address the comments.974. Send a message in the chat asking ChatGPT to address the comments.

97 98 

98Comments work best when you name the problem and the result you want:99Comments work best when you name the problem and the result you want:

99 100 

build-plugins.md +27 −26

Details

1# Build plugins1# Build plugins

2 2 

3This page is for plugin authors. If you want to browse, install, and use3This page is for plugin authors. If you want to browse, install, and use

4plugins in ChatGPT Work on the web or in Work or Codex in the ChatGPT desktop app, see4plugins in Work mode in ChatGPT on the web or in Work mode or Codex in the

5[Plugins](https://learn.chatgpt.com/docs/plugins). If you are still iterating on one repo or one personal5ChatGPT desktop app, see [Plugins](https://learn.chatgpt.com/docs/plugins). If you are still iterating on

6workflow, start with a local skill. Build a plugin when you want to share that6one repo or one personal workflow, start with a local skill. Build a plugin when

7workflow across teams, bundle connectors or MCP config, package lifecycle hooks,7you want to share that workflow across teams, bundle connectors or MCP config,

8or publish a stable package.8package lifecycle hooks, or publish a stable package.

9 9 

10A plugin can include skills, an MCP-backed app, or both. If your plugin needs10A plugin can include skills, an MCP-backed app, or both. If your plugin needs

11to connect to a service or expose tools through an MCP server, see11to connect to a service or expose tools through an MCP server, see


39 39 

40### Create and test a plugin locally that points to an MCP-server-backed dev-mode app40### Create and test a plugin locally that points to an MCP-server-backed dev-mode app

41 41 

42You can also use `$plugin-creator` if you want to test a plugin locally that42You can also use the plugin-creator skill if you want to test a plugin locally

43includes an MCP-server backed app. The plugin still needs a local plugin folder43that includes an MCP-server backed app. The plugin still needs a local plugin

44and manifest, but the app itself starts in ChatGPT developer mode.44folder and manifest, but the app itself starts in ChatGPT developer mode.

45 45 

46First, enable developer mode in ChatGPT:46First, enable developer mode in ChatGPT:

47 47 


584. After ChatGPT creates it, copy the app ID from the browser URL. It starts584. After ChatGPT creates it, copy the app ID from the browser URL. It starts

59 with `plugin_asdk_app`.59 with `plugin_asdk_app`.

60 60 

61Give that `plugin_asdk_app...` ID to `$plugin-creator` in ChatGPT or Codex. For61Give that `plugin_asdk_app...` ID to `@plugin-creator` in Work mode in ChatGPT

62example:62or `$plugin-creator` in Codex. For example, in Work mode:

63 63 

64<div class="not-prose my-6 overflow-hidden rounded-xl border border-subtle bg-surface shadow-sm">64<div class="not-prose my-6 overflow-hidden rounded-xl border border-subtle bg-surface shadow-sm">

65 <div class="border-b border-subtle bg-surface-secondary px-4 py-3">65 <div class="border-b border-subtle bg-surface-secondary px-4 py-3">


68 </span>68 </span>

69 </div>69 </div>

70 <div class="overflow-x-auto p-4 font-mono text-sm leading-6 text-primary">70 <div class="overflow-x-auto p-4 font-mono text-sm leading-6 text-primary">

71 <code class="whitespace-pre-wrap break-words">{`$plugin-creator create a Codex plugin for my ChatGPT app.71 <code class="whitespace-pre-wrap break-words">{`@plugin-creator create a Codex plugin for my ChatGPT app.

72Use plugin_asdk_app_6a4c0062f3b88191855c0a80eac5d53d and name it Acme Support.72Use plugin_asdk_app_6a4c0062f3b88191855c0a80eac5d53d and name it Acme Support.

73Include a personal marketplace entry so I can test it locally.`}</code>73Include a personal marketplace entry so I can test it locally.`}</code>

74 </div>74 </div>

75</div>75</div>

76 76 

77`$plugin-creator` will create the plugin folder, create the required77The plugin-creator skill will create the plugin folder, create the required

78`.codex-plugin/plugin.json`, and add app wiring for the ChatGPT app. If you ask78`.codex-plugin/plugin.json`, and add app wiring for the ChatGPT app. If you ask

79it to create a personal marketplace entry, the plugin appears in your local79it to create a personal marketplace entry, the plugin appears under your local

80plugin directory for testing.80source in the Plugins Directory for testing.

81 81 

82After `$plugin-creator` creates the plugin:82After the plugin-creator skill creates the plugin:

83 83 

841. Review `.app.json` and confirm it points at the correct841. Review `.app.json` and confirm it points at the correct

85 `plugin_asdk_app...` ID.85 `plugin_asdk_app...` ID.


87 `./.app.json`.87 `./.app.json`.

883. Add any bundled skills under `skills/` if the plugin should include883. Add any bundled skills under `skills/` if the plugin should include

89 repeatable workflows alongside the app.89 repeatable workflows alongside the app.

904. If `$plugin-creator` created a personal marketplace entry, refresh ChatGPT904. If the skill created a personal marketplace entry, refresh ChatGPT

91 and install the plugin from your local plugin directory. Then test it in a91 and install the plugin from your local source in the Plugins Directory. Then

92 new task.92 test it in a new chat.

93 93 

94For the manifest shape and file layout, see [Plugin structure](#plugin-structure)94For the manifest shape and file layout, see [Plugin structure](#plugin-structure)

95and [Path rules](#path-rules).95and [Path rules](#path-rules).


100for a single plugin, and you can keep adding entries to that same marketplace100for a single plugin, and you can keep adding entries to that same marketplace

101to build your own curated list for a repo, team, or personal workflow.101to build your own curated list for a repo, team, or personal workflow.

102 102 

103In Work or Codex in the ChatGPT desktop app, each marketplace appears as a103In Work mode or Codex in the ChatGPT desktop app, each marketplace appears as a

104selectable source in the plugin directory. Use104selectable source in the Plugins Directory. Use

105`$REPO_ROOT/.agents/plugins/marketplace.json` for a repo-scoped list or105`$REPO_ROOT/.agents/plugins/marketplace.json` for a repo-scoped list or

106`~/.agents/plugins/marketplace.json` for a personal list. Add one entry per106`~/.agents/plugins/marketplace.json` for a personal list. Add one entry per

107plugin under `plugins[]`, point each `source.path` at the plugin folder with a107plugin under `plugins[]`, point each `source.path` at the plugin folder with a

108`./`-prefixed path relative to the marketplace root, and set108`./`-prefixed path relative to the marketplace root, and set

109`interface.displayName` to the label you want the app to show in the marketplace109`interface.displayName` to the label you want the app to show in the marketplace

110picker. Then restart the ChatGPT desktop app. After that, open the plugin110picker. Then restart the ChatGPT desktop app. After that, open the Plugins

111directory, choose your marketplace, and browse or install the plugins in that111Directory, choose your marketplace, and browse or install the plugins in that

112curated list.112curated list.

113 113 

114You don't need a separate marketplace per plugin. One marketplace can expose a114You don't need a separate marketplace per plugin. One marketplace can expose a


116you add more plugins.116you add more plugins.

117 117 

118<CodexScreenshot118<CodexScreenshot

119 alt="custom local marketplace in the plugin directory"119 alt="custom local marketplace in the Plugins Directory"

120 lightSrc="/images/codex/plugins/codex-local-plugin-light.png"120 lightSrc="/images/codex/plugins/codex-local-plugin-light.png"

121 darkSrc="/images/codex/plugins/codex-local-plugin.png"121 darkSrc="/images/codex/plugins/codex-local-plugin.png"

122/>122/>


294 294 

295### Share a local plugin with your workspace295### Share a local plugin with your workspace

296 296 

297After you create a plugin and add it to Work or Codex, you can share it with297After you create a plugin, add it from the ChatGPT desktop app. Select ChatGPT

298other members of your ChatGPT workspace from the ChatGPT desktop app.298and switch to Work mode, or select Codex, then open **Plugins**. You can then

299share it with other members of your ChatGPT workspace.

299 300 

3001. Open **Plugins** in the ChatGPT desktop app.3011. Open **Plugins** in the ChatGPT desktop app.

3012. Go to **Created by you** and open the plugin details page.3022. Go to **Created by you** and open the plugin details page.


3045. Choose who has access, then send the invitation or link.3055. Choose who has access, then send the invitation or link.

305 306 

306People you share with can find the plugin under **Shared with you** in the307People you share with can find the plugin under **Shared with you** in the

307plugin directory. Sharing a local plugin with your workspace doesn't publish308Plugins Directory. Sharing a local plugin with your workspace doesn't publish

308it to the public Plugins Directory. Shared plugins stay within your workspace309it to the public Plugins Directory. Shared plugins stay within your workspace

309and organization boundary; accounts that aren't signed in to that workspace310and organization boundary; accounts that aren't signed in to that workspace

310can't access them. Use groups when a team or role should share the same plugin311can't access them. Use groups when a team or role should share the same plugin

build-skills.md +1 −1

Details

2 2 

3Use agent skills to extend Codex with task-specific capabilities. A skill packages instructions, resources, and optional scripts so Codex can follow a workflow reliably. Skills build on the [open agent skills standard](https://agentskills.io).3Use agent skills to extend Codex with task-specific capabilities. A skill packages instructions, resources, and optional scripts so Codex can follow a workflow reliably. Skills build on the [open agent skills standard](https://agentskills.io).

4 4 

5Skills are the authoring format for reusable workflows. Plugins distribute reusable skills and connectors to ChatGPT Work on the web and to Work and Codex in the ChatGPT desktop app. Codex CLI can also install plugins. Use skills to design the workflow itself, then package it as a [plugin](https://learn.chatgpt.com/docs/build-plugins) when you want other people in your workspace to install it.5Skills are the authoring format for reusable workflows. Plugins distribute reusable skills and connectors to Work mode in ChatGPT on the web and to Work mode and Codex in the ChatGPT desktop app. Codex CLI can also install plugins. Use skills to design the workflow itself, then package it as a [plugin](https://learn.chatgpt.com/docs/build-plugins) when you want other people in your workspace to install it.

6 6 

7Skills are available in the ChatGPT desktop app, Codex CLI, and IDE extension.7Skills are available in the ChatGPT desktop app, Codex CLI, and IDE extension.

8 8 

Details

33 can also press <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>.</kbd>.33 can also press <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>.</kbd>.

343. Ask a question about the page or give ChatGPT a task.343. Ask a question about the page or give ChatGPT a task.

35 35 

36The panel stays with the tab where you opened it. Threads you start in Chrome36The panel stays with the tab where you opened it. Chats you start in Chrome

37are available in the ChatGPT app, and you can open recent ChatGPT threads in37are available in the ChatGPT app, and you can open recent ChatGPT chats in

38Chrome, so you can continue work in either place.38Chrome, so you can continue work in either place.

39 39 

40<Illustration description="ChatGPT open beside the current Chrome tab.">40<Illustration description="ChatGPT open beside the current Chrome tab.">


76 76 

77## Start a Chrome task from ChatGPT77## Start a Chrome task from ChatGPT

78 78 

79After the plugin setup is complete, start a new task in Work or Codex. ChatGPT79After the plugin setup is complete, start a new chat in Work mode or Codex. ChatGPT

80can use Chrome automatically when a task needs a website and you're already80can use Chrome automatically when a task needs a website and you're already

81signed in to Chrome. You can also invoke it directly in a prompt:81signed in to Chrome. You can also invoke it directly in a prompt:

82 82 


159OpenAI doesn't store a separate complete record of your Chrome actions from the159OpenAI doesn't store a separate complete record of your Chrome actions from the

160extension. OpenAI stores browser activity only when it becomes part of the ChatGPT160extension. OpenAI stores browser activity only when it becomes part of the ChatGPT

161context, such as text ChatGPT reads from a page, screenshots, tool calls,161context, such as text ChatGPT reads from a page, screenshots, tool calls,

162summaries, messages, or other content included in the task.162summaries, messages, or other content included in the chat.

163 163 

164Your ChatGPT data controls apply to content processed in context.164Your ChatGPT data controls apply to content processed in context.

165Avoid sending secrets or highly sensitive data through browser tasks unless165Avoid sending secrets or highly sensitive data through browser tasks unless


1762. Close the ChatGPT side panel, restart Chrome, then reopen the extension from1762. Close the ChatGPT side panel, restart Chrome, then reopen the extension from

177 the Chrome toolbar or **Extensions** menu. Confirm the side chat loads. If177 the Chrome toolbar or **Extensions** menu. Confirm the side chat loads. If

178 it doesn't load or mentions a missing native host, remove and re-add the178 it doesn't load or mentions a missing native host, remove and re-add the

179 Chrome plugin from **Plugins** in Work or Codex in the ChatGPT desktop app,179 Chrome plugin from **Plugins** in the ChatGPT desktop app, then follow the

180 then follow the setup flow again.180 setup flow again.

1813. In the app, select Work or Codex, open **Plugins**, and confirm that the1813. In the app, select ChatGPT and switch to Work mode, or select Codex. Open

182 Chrome plugin is on. If the plugin is off, turn it on and182 **Plugins** and confirm that the Chrome plugin is on. If the plugin is off,

183 try the task again.183 turn it on and try the task again.

1844. Make sure you are using the same Chrome profile where the extension is1844. Make sure you are using the same Chrome profile where the extension is

185 installed. If you use more than one Chrome profile, install and enable the185 installed. If you use more than one Chrome profile, install and enable the

186 extension in the active profile.186 extension in the active profile.

1875. Start a new task in Work or Codex and try the Chrome task again. This can1875. Start a new chat in Work mode or Codex and try the Chrome task again. This can

188 clear task-specific connection state.188 clear chat-specific connection state.

1896. Restart the ChatGPT desktop app, then try again. If the extension still1896. Restart the ChatGPT desktop app, then try again. If the extension still

190 doesn't connect, uninstall the Chrome extension, remove and re-add the Chrome190 doesn't connect, uninstall the Chrome extension, remove and re-add the Chrome

191 plugin from **Plugins**, and follow the setup flow again.191 plugin from **Plugins**, and follow the setup flow again.

1927. If the side chat loads but ChatGPT still can't use Chrome, run `/feedback`1927. If the side chat loads but ChatGPT still can't use Chrome, run `/feedback`

193 in the app and include the task ID when you contact support.193 in the app and include the chat ID when you contact support.

194 194 

195### Upload files195### Upload files

196 196 

cli/reference.md +58 −48

Details

99 99 

100### `codex apply`100### `codex apply`

101 101 

102Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.102Apply the most recent diff from a Codex cloud chat to your local repository. You must authenticate and have access to the chat.

103 103 

104<ConfigTable client:load options={applyOptions} />104<ConfigTable client:load options={applyOptions} />

105 105 


146 146 

147### `codex cloud`147### `codex cloud`

148 148 

149Interact with Codex cloud tasks from the terminal. The default command opens an interactive picker; `codex cloud exec` submits a task directly, and `codex cloud list` returns recent tasks for scripting or quick inspection.149Interact with Codex cloud chats from the terminal. The default command opens an interactive picker; `codex cloud exec` submits a task directly, and `codex cloud list` returns recent chats for scripting or quick inspection.

150 150 

151<ConfigTable client:load options={cloudExecOptions} />151<ConfigTable client:load options={cloudExecOptions} />

152 152 


154 154 

155#### `codex cloud list`155#### `codex cloud list`

156 156 

157List recent cloud tasks with optional filtering and pagination.157List recent cloud chats with optional filtering and pagination.

158 158 

159<ConfigTable client:load options={cloudListOptions} />159<ConfigTable client:load options={cloudListOptions} />

160 160 


265 265 

266### `codex resume`266### `codex resume`

267 267 

268Continue an interactive session by ID or resume the most recent conversation. `codex resume` scopes `--last` to the current working directory unless you pass `--all`. It accepts the same global flags as `codex`, including model and sandbox overrides.268Continue an interactive session by ID or resume the most recent chat. `codex resume` scopes `--last` to the current working directory unless you pass `--all`. It accepts the same global flags as `codex`, including model and sandbox overrides.

269 269 

270<ConfigTable client:load options={resumeOptions} />270<ConfigTable client:load options={resumeOptions} />

271 271 

272### `codex fork`272### `codex fork`

273 273 

274Fork a previous interactive session into a new task. By default, `codex fork` opens the session picker; add `--last` to fork your most recent session instead.274Fork a previous interactive session into a new chat. By default, `codex fork` opens the session picker; add `--last` to fork your most recent session instead.

275 275 

276<ConfigTable client:load options={forkOptions} />276<ConfigTable client:load options={forkOptions} />

277 277 


310- Prefix a line with `!` to run a local shell command under the current approval and sandbox settings.310- Prefix a line with `!` to run a local shell command under the current approval and sandbox settings.

311- Press <kbd>Tab</kbd> while Codex is working to queue a follow-up prompt, slash command, or shell command for the next turn.311- Press <kbd>Tab</kbd> while Codex is working to queue a follow-up prompt, slash command, or shell command for the next turn.

312- Press <kbd>Enter</kbd> while Codex is working to inject new instructions into the current turn.312- Press <kbd>Enter</kbd> while Codex is working to inject new instructions into the current turn.

313- Press <kbd>Esc</kbd> twice with an empty composer to edit the previous user message and fork the conversation from that point.313- Press <kbd>Esc</kbd> twice with an empty composer to edit the previous user message and fork the chat from that point.

314- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or run `/exit` to close the session.314- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or run `/exit` to close the session.

315 315 

316## Related resources316## Related resources


323Slash commands give you fast, keyboard-first control over Codex. Type `/` in323Slash commands give you fast, keyboard-first control over Codex. Type `/` in

324the composer to open the slash popup, choose a command, and Codex will perform324the composer to open the slash popup, choose a command, and Codex will perform

325actions such as switching models, adjusting permissions, or summarizing long325actions such as switching models, adjusting permissions, or summarizing long

326conversations without leaving the terminal.326chats without leaving the terminal.

327 327 

328This guide shows you how to:328This guide shows you how to:

329 329 


336Codex ships with the following commands. Open the slash popup and start typing336Codex ships with the following commands. Open the slash popup and start typing

337the command name to filter the list.337the command name to filter the list.

338 338 

339When a task is already running, you can type a slash command and press `Tab` to339When a chat is already running, you can type a slash command and press `Tab` to

340queue it for the next turn. Codex parses queued slash commands when they run, so340queue it for the next turn. Codex parses queued slash commands when they run, so

341command menus and errors appear after the current turn finishes. Slash341command menus and errors appear after the current turn finishes. Slash

342completion still works before you queue the command.342completion still works before you queue the command.


353| [`/apps`](#browse-apps-with-apps) | Browse apps (connectors) and insert them into your prompt. | Attach an app as `$app-slug` before asking Codex to use it. |353| [`/apps`](#browse-apps-with-apps) | Browse apps (connectors) and insert them into your prompt. | Attach an app as `$app-slug` before asking Codex to use it. |

354| [`/plugins`](#browse-plugins-with-plugins) | Browse installed and discoverable plugins. | Inspect plugin tools, install suggested plugins, or manage plugin availability. |354| [`/plugins`](#browse-plugins-with-plugins) | Browse installed and discoverable plugins. | Inspect plugin tools, install suggested plugins, or manage plugin availability. |

355| [`/hooks`](#view-and-manage-lifecycle-hooks-with-hooks) | View and manage lifecycle hooks. | Inspect configured hooks, trust new or changed hooks, or disable non-managed hooks before they run. |355| [`/hooks`](#view-and-manage-lifecycle-hooks-with-hooks) | View and manage lifecycle hooks. | Inspect configured hooks, trust new or changed hooks, or disable non-managed hooks before they run. |

356| [`/clear`](#clear-the-terminal-and-start-a-new-task-with-clear) | Clear the terminal and start a fresh task. | Reset the visible UI and task context together when you want a fresh start. |356| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and chat context together when you want a fresh start. |

357| [`/rename`](#rename-the-current-task-with-rename) | Rename the current task. | Give a saved session a recognizable name without leaving the TUI. |357| [`/rename`](#rename-the-current-chat-with-rename) | Rename the current chat. | Give a saved session a recognizable name without leaving the TUI. |

358| [`/archive`](#archive-the-current-session-with-archive) | Archive the current session and exit Codex. | Remove the current session from active session lists without deleting its transcript. |358| [`/archive`](#archive-the-current-session-with-archive) | Archive the current session and exit Codex. | Remove the current session from active session lists without deleting its transcript. |

359| [`/delete`](#delete-the-current-session-with-delete) | Permanently delete the current session and exit Codex. | Remove the transcript and descendant sessions when archiving isn't enough. |359| [`/delete`](#delete-the-current-session-with-delete) | Permanently delete the current session and exit Codex. | Remove the transcript and descendant sessions when archiving isn't enough. |

360| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |360| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible chat to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |

361| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. You can also press `Ctrl+O`. |361| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. You can also press `Ctrl+O`. |

362| [`/diff`](#review-changes-with-diff) | Show the Git diff, including files Git isn't tracking yet. | Review Codex's edits before you commit or run tests. |362| [`/diff`](#review-changes-with-diff) | Show the Git diff, including files Git isn't tracking yet. | Review Codex's edits before you commit or run tests. |

363| [`/exit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI (same as `/quit`). | Alternative spelling; both commands exit the session. |363| [`/exit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI (same as `/quit`). | Alternative spelling; both commands exit the session. |


370| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |370| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |

371| [`/logout`](#sign-out-with-logout) | Sign out of Codex. | Clear local credentials when using a shared machine. |371| [`/logout`](#sign-out-with-logout) | Sign out of Codex. | Clear local credentials when using a shared machine. |

372| [`/mcp`](#list-mcp-tools-with-mcp) | List configured Model Context Protocol (MCP) tools. | Check which external tools Codex can call during the session; add `verbose` for server details. |372| [`/mcp`](#list-mcp-tools-with-mcp) | List configured Model Context Protocol (MCP) tools. | Check which external tools Codex can call during the session; add `verbose` for server details. |

373| [`/mention`](#highlight-files-with-mention) | Attach a file to the conversation. | Point Codex at specific files or folders you want it to inspect next. |373| [`/mention`](#highlight-files-with-mention) | Attach a file to the chat. | Point Codex at specific files or folders you want it to inspect next. |

374| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between models such as `gpt-5.4-mini` and `gpt-5.5` before running a task. |374| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between models such as `gpt-5.4-mini` and `gpt-5.5` before running a task. |

375| [`/fast`](#toggle-fast-mode-with-fast) | Toggle a Fast service tier when the model catalog exposes one. | Turn the current model's Fast tier on or off and persist the selection. |375| [`/fast`](#toggle-fast-mode-with-fast) | Toggle a Fast service tier when the model catalog exposes one. | Turn the current model's Fast tier on or off and persist the selection. |

376| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |376| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |


378| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |378| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |

379| [`/ps`](#check-background-terminals-with-ps) | Show background terminals and their recent output. | Check long-running commands without leaving the main transcript. |379| [`/ps`](#check-background-terminals-with-ps) | Show background terminals and their recent output. | Check long-running commands without leaving the main transcript. |

380| [`/stop`](#stop-background-terminals-with-stop) | Stop all background terminals. | Cancel background terminal work started by the current session. |380| [`/stop`](#stop-background-terminals-with-stop) | Stop all background terminals. | Cancel background terminal work started by the current session. |

381| [`/fork`](#fork-the-current-conversation-with-fork) | Fork the current task into a new task. | Branch the active session to explore a new approach without losing the current transcript. |381| [`/fork`](#fork-the-current-chat-with-fork) | Fork the current chat into a new chat. | Branch the active session to explore a new approach without losing the current transcript. |

382| [`/app`](#continue-in-the-desktop-app-with-app) | Continue the current session in the ChatGPT desktop app. | Move from the TUI to the desktop app on macOS or Windows. |382| [`/app`](#continue-in-the-desktop-app-with-app) | Continue the current session in the ChatGPT desktop app. | Move from the TUI to the desktop app on macOS or Windows. |

383| [`/side`, `/btw`](#start-a-side-conversation-with-side) | Start an ephemeral side conversation. | Ask a focused follow-up without disrupting the main task's transcript. |383| [`/side`, `/btw`](#start-a-side-chat-with-side) | Start an ephemeral side chat. | Ask a focused follow-up without disrupting the main chat's transcript. |

384| [`/raw`](#toggle-raw-scrollback-with-raw) | Toggle raw scrollback mode. | Make terminal selection and copying less formatted while reviewing long output. |384| [`/raw`](#toggle-raw-scrollback-with-raw) | Toggle raw scrollback mode. | Make terminal selection and copying less formatted while reviewing long output. |

385| [`/resume`](#resume-a-saved-conversation-with-resume) | Resume a saved conversation from your session list. | Continue work from a previous CLI session without starting over. |385| [`/resume`](#resume-a-saved-chat-with-resume) | Resume a saved chat from your session list. | Continue work from a previous CLI session without starting over. |

386| [`/new`](#start-a-new-conversation-with-new) | Start a new task inside the same CLI session. | Reset the task context without leaving the CLI when you want a fresh prompt in the same repo. |386| [`/new`](#start-a-new-chat-with-new) | Start a new chat inside the same CLI session. | Reset the chat context without leaving the CLI when you want a fresh prompt in the same repo. |

387| [`/quit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI. | Leave the session immediately. |387| [`/quit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI. | Leave the session immediately. |

388| [`/review`](#ask-for-a-working-tree-review-with-review) | Ask Codex to review your working tree. | Run after Codex completes work or when you want a second set of eyes on local changes. |388| [`/review`](#ask-for-a-working-tree-review-with-review) | Ask Codex to review your working tree. | Run after Codex completes work or when you want a second set of eyes on local changes. |

389| [`/status`](#inspect-the-session-with-status) | Display session configuration and token usage. | Confirm the active model, approval policy, writable roots, and remaining context capacity. |389| [`/status`](#inspect-the-session-with-status) | Display session configuration and token usage. | Confirm the active model, approval policy, writable roots, and remaining context capacity. |


428 428 

429Use `/personality` to change how Codex communicates without rewriting your prompt.429Use `/personality` to change how Codex communicates without rewriting your prompt.

430 430 

4311. In an active conversation, type `/personality` and press Enter.4311. In an active chat, type `/personality` and press Enter.

4322. Choose a style from the popup.4322. Choose a style from the popup.

433 433 

434Expected: Codex confirms the new style in the transcript and uses it for later434Expected: Codex confirms the new style in the transcript and uses it for later

435responses in the task.435responses in the chat.

436 436 

437Codex supports `friendly`, `pragmatic`, and `none` personalities. Use `none`437Codex supports `friendly`, `pragmatic`, and `none` personalities. Use `none`

438to disable personality instructions.438to disable personality instructions.


441 441 

442### Switch to plan mode with `/plan`442### Switch to plan mode with `/plan`

443 443 

4441. Type `/plan` and press Enter to switch the active conversation into plan4441. Type `/plan` and press Enter to switch the active chat into plan

445 mode.445 mode.

4462. Optional: provide inline prompt text (for example, `/plan Propose a4462. Optional: provide inline prompt text (for example, `/plan Propose a

447migration plan for this service`).447migration plan for this service`).


449 449 

450Expected: Codex enters plan mode and uses your optional inline prompt as the first planning request.450Expected: Codex enters plan mode and uses your optional inline prompt as the first planning request.

451 451 

452While a task is already running, `/plan` is temporarily unavailable.452While Codex is already working, `/plan` is temporarily unavailable.

453 453 

454### Set or view a task goal with `/goal`454### Set or view a task goal with `/goal`

455 455 


4572. Type `/goal` to view the current goal.4572. Type `/goal` to view the current goal.

4583. Use `/goal edit` to revise the objective. Use `/goal pause`, `/goal resume`, or `/goal clear` to pause, resume, or remove it.4583. Use `/goal edit` to revise the objective. Use `/goal pause`, `/goal resume`, or `/goal clear` to pause, resume, or remove it.

459 459 

460Expected: Codex keeps the goal attached to the active task while work continues.460Expected: Codex keeps the goal attached to the active chat while work continues.

461 461 

462Goal objectives must be non-empty and at most 4,000 characters. For longer462Goal objectives must be non-empty and at most 4,000 characters. For longer

463instructions, put the details in a file and point the goal at that file.463instructions, put the details in a file and point the goal at that file.


508in remote sessions, and while connected to the local app-server daemon.508in remote sessions, and while connected to the local app-server daemon.

509 509 

510<a id="clear-the-terminal-and-start-a-new-chat-with-clear"></a>510<a id="clear-the-terminal-and-start-a-new-chat-with-clear"></a>

511<a id="clear-the-terminal-and-start-a-new-task-with-clear"></a>

511 512 

512### Clear the terminal and start a new task with `/clear`513### Clear the terminal and start a new chat with `/clear`

513 514 

5141. Type `/clear` and press Enter.5151. Type `/clear` and press Enter.

515 516 

516Expected: Codex clears the terminal, resets the visible transcript, and starts517Expected: Codex clears the terminal, resets the visible transcript, and starts

517a fresh task in the same CLI session.518a fresh chat in the same CLI session.

518 519 

519Unlike <kbd>Ctrl</kbd>+<kbd>L</kbd>, `/clear` starts a new conversation.520Unlike <kbd>Ctrl</kbd>+<kbd>L</kbd>, `/clear` starts a new chat.

520 521 

521<kbd>Ctrl</kbd>+<kbd>L</kbd> only clears the terminal view and keeps the current522<kbd>Ctrl</kbd>+<kbd>L</kbd> only clears the terminal view and keeps the current

522task. Codex disables both actions while a task is in progress.523chat. Codex disables both actions while a task is in progress.

523 524 

524### Archive the current session with `/archive`525### Archive the current session with `/archive`

525 526 


541interactive TUI. Deletion is permanent and also removes spawned descendant542interactive TUI. Deletion is permanent and also removes spawned descendant

542sessions.543sessions.

543 544 

544`/delete` is unavailable while a task is running or in a side conversation.545`/delete` is unavailable while a chat is running or in a side chat.

545 546 

546### Update permissions with `/permissions`547### Update permissions with `/permissions`

547 548 


615 616 

616### Inspect the session with `/status`617### Inspect the session with `/status`

617 618 

6181. In any conversation, type `/status`.6191. In any chat, type `/status`.

6192. Review the output for the active model, approval policy, writable roots, and6202. Review the output for the active model, approval policy, writable roots, and

620 current token usage. When the TUI connects remotely, the output also621 current token usage. When the TUI connects remotely, the output also

621 shows the remote address and the server version.622 shows the remote address and the server version.


717### Keep transcripts lean with `/compact`718### Keep transcripts lean with `/compact`

718 719 

7191. After a long exchange, type `/compact`.7201. After a long exchange, type `/compact`.

7202. Confirm when Codex offers to summarize the conversation so far.7212. Confirm when Codex offers to summarize the chat so far.

721 722 

722Expected: Codex replaces earlier turns with a concise summary, freeing context723Expected: Codex replaces earlier turns with a concise summary, freeing context

723while keeping critical details.724while keeping critical details.


7351. Type `/mention` followed by a path, for example `/mention src/lib/api.ts`.7361. Type `/mention` followed by a path, for example `/mention src/lib/api.ts`.

7362. Select the matching result from the popup.7372. Select the matching result from the popup.

737 738 

738Expected: Codex adds the file to the conversation, ensuring follow-up turns reference it directly.739Expected: Codex adds the file to the chat, ensuring follow-up turns reference it directly.

739 740 

740### Start a new conversation with `/new`741<a id="start-a-new-conversation-with-new"></a>

742 

743### Start a new chat with `/new`

741 744 

7421. Type `/new` and press Enter.7451. Type `/new` and press Enter.

743 746 

744Expected: Codex starts a fresh conversation in the same CLI session, so you747Expected: Codex starts a fresh chat in the same CLI session, so you

745can switch tasks without leaving your terminal.748can switch chats without leaving your terminal.

746 749 

747Unlike `/clear`, `/new` doesn't clear the current terminal view first.750Unlike `/clear`, `/new` doesn't clear the current terminal view first.

748 751 

749<a id="rename-the-current-chat-with-rename"></a>752<a id="rename-the-current-chat-with-rename"></a>

753<a id="rename-the-current-task-with-rename"></a>

750 754 

751### Rename the current task with `/rename`755### Rename the current chat with `/rename`

752 756 

7531. Type `/rename <name>`, or type `/rename` to open the naming prompt.7571. Type `/rename <name>`, or type `/rename` to open the naming prompt.

7542. Enter a short name that will help you find the task later.7582. Enter a short name that will help you find the chat later.

759 

760Expected: Codex updates the saved chat name without changing its transcript.

755 761 

756Expected: Codex updates the saved task name without changing its transcript.762<a id="resume-a-saved-conversation-with-resume"></a>

757 763 

758### Resume a saved conversation with `/resume`764### Resume a saved chat with `/resume`

759 765 

7601. Type `/resume` and press Enter.7661. Type `/resume` and press Enter.

7612. Choose the session you want from the saved-session picker.7672. Choose the session you want from the saved-session picker.

762 768 

763Expected: Codex reloads the selected conversation's transcript so you can pick769Expected: Codex reloads the selected chat's transcript so you can pick

764up where you left off, keeping the original history intact.770up where you left off, keeping the original history intact.

765 771 

766### Fork the current conversation with `/fork`772<a id="fork-the-current-conversation-with-fork"></a>

773 

774### Fork the current chat with `/fork`

767 775 

7681. Type `/fork` and press Enter.7761. Type `/fork` and press Enter.

769 777 

770Expected: Codex clones the current task into a new task with a fresh778Expected: Codex clones the current chat into a new chat with a fresh

771ID, leaving the original transcript untouched so you can explore an alternative779ID, leaving the original transcript untouched so you can explore an alternative

772approach in parallel.780approach in parallel.

773 781 


780desktop app. If the app isn't installed or running, Codex shows an error asking788desktop app. If the app isn't installed or running, Codex shows an error asking

781you to install or launch it.789you to install or launch it.

782 790 

783Expected: The desktop app opens the same saved task so you can continue there.791Expected: The desktop app opens the same saved chat so you can continue there.

792 

793<a id="start-a-side-conversation-with-side"></a>

784 794 

785### Start a side conversation with `/side`795### Start a side chat with `/side`

786 796 

787Use `/side` to start an ephemeral fork from the current conversation without switching away from the main task.797Use `/side` to start an ephemeral fork from the current chat without switching away from the main chat.

788 798 

7891. Type `/side` to open a side conversation.7991. Type `/side` to open a side chat.

7902. Optionally add inline text, for example `/side Check whether this plan has an obvious risk`.8002. Optionally add inline text, for example `/side Check whether this plan has an obvious risk`.

7913. Return to the parent task after the focused detour finishes.8013. Return to the parent chat after the focused detour finishes.

792 802 

793Expected: Codex opens a side conversation whose transcript is separate from803Expected: Codex opens a side chat whose transcript is separate from

794the parent task. While you are in side mode, the TUI continues to show the804the parent chat. While you are in side mode, the TUI continues to show the

795parent task's status so you can see whether the main task is still running.805parent chat's status so you can see whether the main chat is still running.

796 806 

797`/side` is unavailable inside another side conversation and during review mode.807`/side` is unavailable inside another side chat and during review mode.

798 808 

799### Generate `AGENTS.md` with `/init`809### Generate `AGENTS.md` with `/init`

800 810 

Details

99 99 

100### `codex apply`100### `codex apply`

101 101 

102Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.102Apply the most recent diff from a Codex cloud chat to your local repository. You must authenticate and have access to the chat.

103 103 

104<ConfigTable client:load options={applyOptions} />104<ConfigTable client:load options={applyOptions} />

105 105 


146 146 

147### `codex cloud`147### `codex cloud`

148 148 

149Interact with Codex cloud tasks from the terminal. The default command opens an interactive picker; `codex cloud exec` submits a task directly, and `codex cloud list` returns recent tasks for scripting or quick inspection.149Interact with Codex cloud chats from the terminal. The default command opens an interactive picker; `codex cloud exec` submits a task directly, and `codex cloud list` returns recent chats for scripting or quick inspection.

150 150 

151<ConfigTable client:load options={cloudExecOptions} />151<ConfigTable client:load options={cloudExecOptions} />

152 152 


154 154 

155#### `codex cloud list`155#### `codex cloud list`

156 156 

157List recent cloud tasks with optional filtering and pagination.157List recent cloud chats with optional filtering and pagination.

158 158 

159<ConfigTable client:load options={cloudListOptions} />159<ConfigTable client:load options={cloudListOptions} />

160 160 


265 265 

266### `codex resume`266### `codex resume`

267 267 

268Continue an interactive session by ID or resume the most recent conversation. `codex resume` scopes `--last` to the current working directory unless you pass `--all`. It accepts the same global flags as `codex`, including model and sandbox overrides.268Continue an interactive session by ID or resume the most recent chat. `codex resume` scopes `--last` to the current working directory unless you pass `--all`. It accepts the same global flags as `codex`, including model and sandbox overrides.

269 269 

270<ConfigTable client:load options={resumeOptions} />270<ConfigTable client:load options={resumeOptions} />

271 271 

272### `codex fork`272### `codex fork`

273 273 

274Fork a previous interactive session into a new task. By default, `codex fork` opens the session picker; add `--last` to fork your most recent session instead.274Fork a previous interactive session into a new chat. By default, `codex fork` opens the session picker; add `--last` to fork your most recent session instead.

275 275 

276<ConfigTable client:load options={forkOptions} />276<ConfigTable client:load options={forkOptions} />

277 277 


310- Prefix a line with `!` to run a local shell command under the current approval and sandbox settings.310- Prefix a line with `!` to run a local shell command under the current approval and sandbox settings.

311- Press <kbd>Tab</kbd> while Codex is working to queue a follow-up prompt, slash command, or shell command for the next turn.311- Press <kbd>Tab</kbd> while Codex is working to queue a follow-up prompt, slash command, or shell command for the next turn.

312- Press <kbd>Enter</kbd> while Codex is working to inject new instructions into the current turn.312- Press <kbd>Enter</kbd> while Codex is working to inject new instructions into the current turn.

313- Press <kbd>Esc</kbd> twice with an empty composer to edit the previous user message and fork the conversation from that point.313- Press <kbd>Esc</kbd> twice with an empty composer to edit the previous user message and fork the chat from that point.

314- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or run `/exit` to close the session.314- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or run `/exit` to close the session.

315 315 

316## Related resources316## Related resources


323Slash commands give you fast, keyboard-first control over Codex. Type `/` in323Slash commands give you fast, keyboard-first control over Codex. Type `/` in

324the composer to open the slash popup, choose a command, and Codex will perform324the composer to open the slash popup, choose a command, and Codex will perform

325actions such as switching models, adjusting permissions, or summarizing long325actions such as switching models, adjusting permissions, or summarizing long

326conversations without leaving the terminal.326chats without leaving the terminal.

327 327 

328This guide shows you how to:328This guide shows you how to:

329 329 


336Codex ships with the following commands. Open the slash popup and start typing336Codex ships with the following commands. Open the slash popup and start typing

337the command name to filter the list.337the command name to filter the list.

338 338 

339When a task is already running, you can type a slash command and press `Tab` to339When a chat is already running, you can type a slash command and press `Tab` to

340queue it for the next turn. Codex parses queued slash commands when they run, so340queue it for the next turn. Codex parses queued slash commands when they run, so

341command menus and errors appear after the current turn finishes. Slash341command menus and errors appear after the current turn finishes. Slash

342completion still works before you queue the command.342completion still works before you queue the command.


353| [`/apps`](#browse-apps-with-apps) | Browse apps (connectors) and insert them into your prompt. | Attach an app as `$app-slug` before asking Codex to use it. |353| [`/apps`](#browse-apps-with-apps) | Browse apps (connectors) and insert them into your prompt. | Attach an app as `$app-slug` before asking Codex to use it. |

354| [`/plugins`](#browse-plugins-with-plugins) | Browse installed and discoverable plugins. | Inspect plugin tools, install suggested plugins, or manage plugin availability. |354| [`/plugins`](#browse-plugins-with-plugins) | Browse installed and discoverable plugins. | Inspect plugin tools, install suggested plugins, or manage plugin availability. |

355| [`/hooks`](#view-and-manage-lifecycle-hooks-with-hooks) | View and manage lifecycle hooks. | Inspect configured hooks, trust new or changed hooks, or disable non-managed hooks before they run. |355| [`/hooks`](#view-and-manage-lifecycle-hooks-with-hooks) | View and manage lifecycle hooks. | Inspect configured hooks, trust new or changed hooks, or disable non-managed hooks before they run. |

356| [`/clear`](#clear-the-terminal-and-start-a-new-task-with-clear) | Clear the terminal and start a fresh task. | Reset the visible UI and task context together when you want a fresh start. |356| [`/clear`](#clear-the-terminal-and-start-a-new-chat-with-clear) | Clear the terminal and start a fresh chat. | Reset the visible UI and chat context together when you want a fresh start. |

357| [`/rename`](#rename-the-current-task-with-rename) | Rename the current task. | Give a saved session a recognizable name without leaving the TUI. |357| [`/rename`](#rename-the-current-chat-with-rename) | Rename the current chat. | Give a saved session a recognizable name without leaving the TUI. |

358| [`/archive`](#archive-the-current-session-with-archive) | Archive the current session and exit Codex. | Remove the current session from active session lists without deleting its transcript. |358| [`/archive`](#archive-the-current-session-with-archive) | Archive the current session and exit Codex. | Remove the current session from active session lists without deleting its transcript. |

359| [`/delete`](#delete-the-current-session-with-delete) | Permanently delete the current session and exit Codex. | Remove the transcript and descendant sessions when archiving isn't enough. |359| [`/delete`](#delete-the-current-session-with-delete) | Permanently delete the current session and exit Codex. | Remove the transcript and descendant sessions when archiving isn't enough. |

360| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible conversation to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |360| [`/compact`](#keep-transcripts-lean-with-compact) | Summarize the visible chat to free tokens. | Use after long runs so Codex retains key points without blowing the context window. |

361| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. You can also press `Ctrl+O`. |361| [`/copy`](#copy-the-latest-response-with-copy) | Copy the latest completed Codex output. | Grab the latest finished response or plan text without manually selecting it. You can also press `Ctrl+O`. |

362| [`/diff`](#review-changes-with-diff) | Show the Git diff, including files Git isn't tracking yet. | Review Codex's edits before you commit or run tests. |362| [`/diff`](#review-changes-with-diff) | Show the Git diff, including files Git isn't tracking yet. | Review Codex's edits before you commit or run tests. |

363| [`/exit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI (same as `/quit`). | Alternative spelling; both commands exit the session. |363| [`/exit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI (same as `/quit`). | Alternative spelling; both commands exit the session. |


370| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |370| [`/init`](#generate-agentsmd-with-init) | Generate an `AGENTS.md` scaffold in the current directory. | Capture persistent instructions for the repository or subdirectory you're working in. |

371| [`/logout`](#sign-out-with-logout) | Sign out of Codex. | Clear local credentials when using a shared machine. |371| [`/logout`](#sign-out-with-logout) | Sign out of Codex. | Clear local credentials when using a shared machine. |

372| [`/mcp`](#list-mcp-tools-with-mcp) | List configured Model Context Protocol (MCP) tools. | Check which external tools Codex can call during the session; add `verbose` for server details. |372| [`/mcp`](#list-mcp-tools-with-mcp) | List configured Model Context Protocol (MCP) tools. | Check which external tools Codex can call during the session; add `verbose` for server details. |

373| [`/mention`](#highlight-files-with-mention) | Attach a file to the conversation. | Point Codex at specific files or folders you want it to inspect next. |373| [`/mention`](#highlight-files-with-mention) | Attach a file to the chat. | Point Codex at specific files or folders you want it to inspect next. |

374| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between models such as `gpt-5.4-mini` and `gpt-5.5` before running a task. |374| [`/model`](#set-the-active-model-with-model) | Choose the active model (and reasoning effort, when available). | Switch between models such as `gpt-5.4-mini` and `gpt-5.5` before running a task. |

375| [`/fast`](#toggle-fast-mode-with-fast) | Toggle a Fast service tier when the model catalog exposes one. | Turn the current model's Fast tier on or off and persist the selection. |375| [`/fast`](#toggle-fast-mode-with-fast) | Toggle a Fast service tier when the model catalog exposes one. | Turn the current model's Fast tier on or off and persist the selection. |

376| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |376| [`/plan`](#switch-to-plan-mode-with-plan) | Switch to plan mode and optionally send a prompt. | Ask Codex to propose an execution plan before implementation work starts. |


378| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |378| [`/personality`](#set-a-communication-style-with-personality) | Choose a communication style for responses. | Make Codex more concise, more explanatory, or more collaborative without changing your instructions. |

379| [`/ps`](#check-background-terminals-with-ps) | Show background terminals and their recent output. | Check long-running commands without leaving the main transcript. |379| [`/ps`](#check-background-terminals-with-ps) | Show background terminals and their recent output. | Check long-running commands without leaving the main transcript. |

380| [`/stop`](#stop-background-terminals-with-stop) | Stop all background terminals. | Cancel background terminal work started by the current session. |380| [`/stop`](#stop-background-terminals-with-stop) | Stop all background terminals. | Cancel background terminal work started by the current session. |

381| [`/fork`](#fork-the-current-conversation-with-fork) | Fork the current task into a new task. | Branch the active session to explore a new approach without losing the current transcript. |381| [`/fork`](#fork-the-current-chat-with-fork) | Fork the current chat into a new chat. | Branch the active session to explore a new approach without losing the current transcript. |

382| [`/app`](#continue-in-the-desktop-app-with-app) | Continue the current session in the ChatGPT desktop app. | Move from the TUI to the desktop app on macOS or Windows. |382| [`/app`](#continue-in-the-desktop-app-with-app) | Continue the current session in the ChatGPT desktop app. | Move from the TUI to the desktop app on macOS or Windows. |

383| [`/side`, `/btw`](#start-a-side-conversation-with-side) | Start an ephemeral side conversation. | Ask a focused follow-up without disrupting the main task's transcript. |383| [`/side`, `/btw`](#start-a-side-chat-with-side) | Start an ephemeral side chat. | Ask a focused follow-up without disrupting the main chat's transcript. |

384| [`/raw`](#toggle-raw-scrollback-with-raw) | Toggle raw scrollback mode. | Make terminal selection and copying less formatted while reviewing long output. |384| [`/raw`](#toggle-raw-scrollback-with-raw) | Toggle raw scrollback mode. | Make terminal selection and copying less formatted while reviewing long output. |

385| [`/resume`](#resume-a-saved-conversation-with-resume) | Resume a saved conversation from your session list. | Continue work from a previous CLI session without starting over. |385| [`/resume`](#resume-a-saved-chat-with-resume) | Resume a saved chat from your session list. | Continue work from a previous CLI session without starting over. |

386| [`/new`](#start-a-new-conversation-with-new) | Start a new task inside the same CLI session. | Reset the task context without leaving the CLI when you want a fresh prompt in the same repo. |386| [`/new`](#start-a-new-chat-with-new) | Start a new chat inside the same CLI session. | Reset the chat context without leaving the CLI when you want a fresh prompt in the same repo. |

387| [`/quit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI. | Leave the session immediately. |387| [`/quit`](#exit-the-cli-with-quit-or-exit) | Exit the CLI. | Leave the session immediately. |

388| [`/review`](#ask-for-a-working-tree-review-with-review) | Ask Codex to review your working tree. | Run after Codex completes work or when you want a second set of eyes on local changes. |388| [`/review`](#ask-for-a-working-tree-review-with-review) | Ask Codex to review your working tree. | Run after Codex completes work or when you want a second set of eyes on local changes. |

389| [`/status`](#inspect-the-session-with-status) | Display session configuration and token usage. | Confirm the active model, approval policy, writable roots, and remaining context capacity. |389| [`/status`](#inspect-the-session-with-status) | Display session configuration and token usage. | Confirm the active model, approval policy, writable roots, and remaining context capacity. |


428 428 

429Use `/personality` to change how Codex communicates without rewriting your prompt.429Use `/personality` to change how Codex communicates without rewriting your prompt.

430 430 

4311. In an active conversation, type `/personality` and press Enter.4311. In an active chat, type `/personality` and press Enter.

4322. Choose a style from the popup.4322. Choose a style from the popup.

433 433 

434Expected: Codex confirms the new style in the transcript and uses it for later434Expected: Codex confirms the new style in the transcript and uses it for later

435responses in the task.435responses in the chat.

436 436 

437Codex supports `friendly`, `pragmatic`, and `none` personalities. Use `none`437Codex supports `friendly`, `pragmatic`, and `none` personalities. Use `none`

438to disable personality instructions.438to disable personality instructions.


441 441 

442### Switch to plan mode with `/plan`442### Switch to plan mode with `/plan`

443 443 

4441. Type `/plan` and press Enter to switch the active conversation into plan4441. Type `/plan` and press Enter to switch the active chat into plan

445 mode.445 mode.

4462. Optional: provide inline prompt text (for example, `/plan Propose a4462. Optional: provide inline prompt text (for example, `/plan Propose a

447migration plan for this service`).447migration plan for this service`).


449 449 

450Expected: Codex enters plan mode and uses your optional inline prompt as the first planning request.450Expected: Codex enters plan mode and uses your optional inline prompt as the first planning request.

451 451 

452While a task is already running, `/plan` is temporarily unavailable.452While Codex is already working, `/plan` is temporarily unavailable.

453 453 

454### Set or view a task goal with `/goal`454### Set or view a task goal with `/goal`

455 455 


4572. Type `/goal` to view the current goal.4572. Type `/goal` to view the current goal.

4583. Use `/goal edit` to revise the objective. Use `/goal pause`, `/goal resume`, or `/goal clear` to pause, resume, or remove it.4583. Use `/goal edit` to revise the objective. Use `/goal pause`, `/goal resume`, or `/goal clear` to pause, resume, or remove it.

459 459 

460Expected: Codex keeps the goal attached to the active task while work continues.460Expected: Codex keeps the goal attached to the active chat while work continues.

461 461 

462Goal objectives must be non-empty and at most 4,000 characters. For longer462Goal objectives must be non-empty and at most 4,000 characters. For longer

463instructions, put the details in a file and point the goal at that file.463instructions, put the details in a file and point the goal at that file.


508in remote sessions, and while connected to the local app-server daemon.508in remote sessions, and while connected to the local app-server daemon.

509 509 

510<a id="clear-the-terminal-and-start-a-new-chat-with-clear"></a>510<a id="clear-the-terminal-and-start-a-new-chat-with-clear"></a>

511<a id="clear-the-terminal-and-start-a-new-task-with-clear"></a>

511 512 

512### Clear the terminal and start a new task with `/clear`513### Clear the terminal and start a new chat with `/clear`

513 514 

5141. Type `/clear` and press Enter.5151. Type `/clear` and press Enter.

515 516 

516Expected: Codex clears the terminal, resets the visible transcript, and starts517Expected: Codex clears the terminal, resets the visible transcript, and starts

517a fresh task in the same CLI session.518a fresh chat in the same CLI session.

518 519 

519Unlike <kbd>Ctrl</kbd>+<kbd>L</kbd>, `/clear` starts a new conversation.520Unlike <kbd>Ctrl</kbd>+<kbd>L</kbd>, `/clear` starts a new chat.

520 521 

521<kbd>Ctrl</kbd>+<kbd>L</kbd> only clears the terminal view and keeps the current522<kbd>Ctrl</kbd>+<kbd>L</kbd> only clears the terminal view and keeps the current

522task. Codex disables both actions while a task is in progress.523chat. Codex disables both actions while a task is in progress.

523 524 

524### Archive the current session with `/archive`525### Archive the current session with `/archive`

525 526 


541interactive TUI. Deletion is permanent and also removes spawned descendant542interactive TUI. Deletion is permanent and also removes spawned descendant

542sessions.543sessions.

543 544 

544`/delete` is unavailable while a task is running or in a side conversation.545`/delete` is unavailable while a chat is running or in a side chat.

545 546 

546### Update permissions with `/permissions`547### Update permissions with `/permissions`

547 548 


615 616 

616### Inspect the session with `/status`617### Inspect the session with `/status`

617 618 

6181. In any conversation, type `/status`.6191. In any chat, type `/status`.

6192. Review the output for the active model, approval policy, writable roots, and6202. Review the output for the active model, approval policy, writable roots, and

620 current token usage. When the TUI connects remotely, the output also621 current token usage. When the TUI connects remotely, the output also

621 shows the remote address and the server version.622 shows the remote address and the server version.


717### Keep transcripts lean with `/compact`718### Keep transcripts lean with `/compact`

718 719 

7191. After a long exchange, type `/compact`.7201. After a long exchange, type `/compact`.

7202. Confirm when Codex offers to summarize the conversation so far.7212. Confirm when Codex offers to summarize the chat so far.

721 722 

722Expected: Codex replaces earlier turns with a concise summary, freeing context723Expected: Codex replaces earlier turns with a concise summary, freeing context

723while keeping critical details.724while keeping critical details.


7351. Type `/mention` followed by a path, for example `/mention src/lib/api.ts`.7361. Type `/mention` followed by a path, for example `/mention src/lib/api.ts`.

7362. Select the matching result from the popup.7372. Select the matching result from the popup.

737 738 

738Expected: Codex adds the file to the conversation, ensuring follow-up turns reference it directly.739Expected: Codex adds the file to the chat, ensuring follow-up turns reference it directly.

739 740 

740### Start a new conversation with `/new`741<a id="start-a-new-conversation-with-new"></a>

742 

743### Start a new chat with `/new`

741 744 

7421. Type `/new` and press Enter.7451. Type `/new` and press Enter.

743 746 

744Expected: Codex starts a fresh conversation in the same CLI session, so you747Expected: Codex starts a fresh chat in the same CLI session, so you

745can switch tasks without leaving your terminal.748can switch chats without leaving your terminal.

746 749 

747Unlike `/clear`, `/new` doesn't clear the current terminal view first.750Unlike `/clear`, `/new` doesn't clear the current terminal view first.

748 751 

749<a id="rename-the-current-chat-with-rename"></a>752<a id="rename-the-current-chat-with-rename"></a>

753<a id="rename-the-current-task-with-rename"></a>

750 754 

751### Rename the current task with `/rename`755### Rename the current chat with `/rename`

752 756 

7531. Type `/rename <name>`, or type `/rename` to open the naming prompt.7571. Type `/rename <name>`, or type `/rename` to open the naming prompt.

7542. Enter a short name that will help you find the task later.7582. Enter a short name that will help you find the chat later.

759 

760Expected: Codex updates the saved chat name without changing its transcript.

755 761 

756Expected: Codex updates the saved task name without changing its transcript.762<a id="resume-a-saved-conversation-with-resume"></a>

757 763 

758### Resume a saved conversation with `/resume`764### Resume a saved chat with `/resume`

759 765 

7601. Type `/resume` and press Enter.7661. Type `/resume` and press Enter.

7612. Choose the session you want from the saved-session picker.7672. Choose the session you want from the saved-session picker.

762 768 

763Expected: Codex reloads the selected conversation's transcript so you can pick769Expected: Codex reloads the selected chat's transcript so you can pick

764up where you left off, keeping the original history intact.770up where you left off, keeping the original history intact.

765 771 

766### Fork the current conversation with `/fork`772<a id="fork-the-current-conversation-with-fork"></a>

773 

774### Fork the current chat with `/fork`

767 775 

7681. Type `/fork` and press Enter.7761. Type `/fork` and press Enter.

769 777 

770Expected: Codex clones the current task into a new task with a fresh778Expected: Codex clones the current chat into a new chat with a fresh

771ID, leaving the original transcript untouched so you can explore an alternative779ID, leaving the original transcript untouched so you can explore an alternative

772approach in parallel.780approach in parallel.

773 781 


780desktop app. If the app isn't installed or running, Codex shows an error asking788desktop app. If the app isn't installed or running, Codex shows an error asking

781you to install or launch it.789you to install or launch it.

782 790 

783Expected: The desktop app opens the same saved task so you can continue there.791Expected: The desktop app opens the same saved chat so you can continue there.

792 

793<a id="start-a-side-conversation-with-side"></a>

784 794 

785### Start a side conversation with `/side`795### Start a side chat with `/side`

786 796 

787Use `/side` to start an ephemeral fork from the current conversation without switching away from the main task.797Use `/side` to start an ephemeral fork from the current chat without switching away from the main chat.

788 798 

7891. Type `/side` to open a side conversation.7991. Type `/side` to open a side chat.

7902. Optionally add inline text, for example `/side Check whether this plan has an obvious risk`.8002. Optionally add inline text, for example `/side Check whether this plan has an obvious risk`.

7913. Return to the parent task after the focused detour finishes.8013. Return to the parent chat after the focused detour finishes.

792 802 

793Expected: Codex opens a side conversation whose transcript is separate from803Expected: Codex opens a side chat whose transcript is separate from

794the parent task. While you are in side mode, the TUI continues to show the804the parent chat. While you are in side mode, the TUI continues to show the

795parent task's status so you can see whether the main task is still running.805parent chat's status so you can see whether the main chat is still running.

796 806 

797`/side` is unavailable inside another side conversation and during review mode.807`/side` is unavailable inside another side chat and during review mode.

798 808 

799### Generate `AGENTS.md` with `/init`809### Generate `AGENTS.md` with `/init`

800 810 

cloud.md +2 −2

Details

2 2 

3<CodexSurfaceLanding surface="cloud">3<CodexSurfaceLanding surface="cloud">

4 <div slot="hero-media">4 <div slot="hero-media">

5 <Illustration description="Codex cloud task composer and task list with interactive archiving">5 <Illustration description="Codex cloud chat composer and chat list with interactive archiving">

6 <CodexCloudTasksIllustration ariaLabel="Codex cloud task composer and task list with interactive archiving" />6 <CodexCloudTasksIllustration ariaLabel="Codex cloud chat composer and chat list with interactive archiving" />

7 </Illustration>7 </Illustration>

8 </div>8 </div>

9</CodexSurfaceLanding>9</CodexSurfaceLanding>

Details

1# Cloud environments1# Cloud environments

2 2 

3Use environments to control what Codex installs and runs during cloud tasks. For example, you can add dependencies, install tools like linters and formatters, and set environment variables.3Use environments to control what Codex installs and runs during cloud chats. For example, you can add dependencies, install tools like linters and formatters, and set environment variables.

4 4 

5Configure environments in [Codex settings](https://chatgpt.com/codex/settings/environments).5Configure environments in [Codex settings](https://chatgpt.com/codex/settings/environments).

6 6 

7## How Codex cloud tasks run7<a id="how-codex-cloud-tasks-run"></a>

8 8 

9Here's what happens when you submit a task:9## How Codex cloud chats run

10 

11Here's what happens when you submit a prompt:

10 12 

111. Codex creates a container and checks out your repo at the selected branch or commit SHA.131. Codex creates a container and checks out your repo at the selected branch or commit SHA.

122. Codex runs your setup script, plus an optional maintenance script when a cached container is resumed.142. Codex runs your setup script, plus an optional maintenance script when a cached container is resumed.


28 30 

29## Environment variables and secrets31## Environment variables and secrets

30 32 

31**Environment variables** are set for the full duration of the task (including setup scripts and the agent phase).33**Environment variables** are set for the full duration of the chat (including setup scripts and the agent phase).

32 34 

33**Secrets** are similar to environment variables, except:35**Secrets** are similar to environment variables, except:

34 36 


58 60 

59## Container caching61## Container caching

60 62 

61Codex caches container state for up to 12 hours to speed up new tasks and follow-ups.63Codex caches container state for up to 12 hours to speed up new chats and follow-ups.

62 64 

63When an environment is cached:65When an environment is cached:

64 66 


67 69 

68When a cached container is resumed:70When a cached container is resumed:

69 71 

70- Codex checks out the branch specified for the task.72- Codex checks out the branch specified for the chat.

71- Codex runs the maintenance script (optional). This is useful when the setup script ran on an older commit and dependencies need to be updated.73- Codex runs the maintenance script (optional). This is useful when the setup script ran on an older commit and dependencies need to be updated.

72 74 

73Codex automatically invalidates the cache if you change the setup script, maintenance script, environment variables, or secrets. If your repo changes in a way that makes the cached state incompatible, select **Reset cache** on the environment page.75Codex automatically invalidates the cache if you change the setup script, maintenance script, environment variables, or secrets. If your repo changes in a way that makes the cached state incompatible, select **Reset cache** on the environment page.

code-review.md +4 −4

Details

58 58 

59Review findings appear as inline comments in the review pane.59Review findings appear as inline comments in the review pane.

60 60 

61Reviews run in the current task by default. Under **Settings** > **General** >61Reviews run in the current chat by default. Under **Settings** > **General** >

62**Code review**, choose **Detached** to start a separate review task. See62**Code review**, choose **Detached** to start a separate review chat. See

63[developer settings](https://learn.chatgpt.com/docs/developer-settings?surface=app#app-code-review).63[developer settings](https://learn.chatgpt.com/docs/developer-settings?surface=app#app-code-review).

64 64 

65<CodexScreenshot65<CodexScreenshot


1052. Hover over the line you want to comment on.1052. Hover over the line you want to comment on.

1063. Select the **+** button that appears.1063. Select the **+** button that appears.

1074. Write your feedback and submit it.1074. Write your feedback and submit it.

1085. After you finish leaving feedback, send a message back to the task.1085. After you finish leaving feedback, send a message back to the chat.

109 109 

110Because comments are line-specific, Codex can respond more precisely than with110Because comments are line-specific, Codex can respond more precisely than with

111a general instruction.111a general instruction.


120the pull request branch, the ChatGPT desktop app can help you work through pull120the pull request branch, the ChatGPT desktop app can help you work through pull

121request feedback without leaving the app. The sidebar shows pull request121request feedback without leaving the app. The sidebar shows pull request

122context and feedback from reviewers, and the review pane shows comments122context and feedback from reviewers, and the review pane shows comments

123alongside the diff so you can ask Codex to address issues in the same task.123alongside the diff so you can ask Codex to address issues in the same chat.

124 124 

125Install the GitHub CLI (`gh`) and authenticate it with `gh auth login` so Codex125Install the GitHub CLI (`gh`) and authenticate it with `gh auth login` so Codex

126can load pull request context, review comments, and changed files. If `gh` is126can load pull request context, review comments, and changed files. If `gh` is

computer-use.md +4 −3

Details

1# Computer Use1# Computer Use

2 2 

3In supported regions, Computer Use in the ChatGPT desktop app is available on3In supported regions, Computer Use in the ChatGPT desktop app is available on

4 macOS and Windows in ChatGPT Work and Codex. Install the Computer Use plugin.4 macOS and Windows in Work mode and Codex. Install the Computer Use plugin. On

5 On macOS, grant Screen Recording and Accessibility permissions when prompted.5 macOS, grant Screen Recording and Accessibility permissions when prompted.

6 6 

7With Computer Use, ChatGPT can see and operate graphical user interfaces on macOS7With Computer Use, ChatGPT can see and operate graphical user interfaces on macOS

8or Windows. Use it for tasks where command-line tools or structured integrations8or Windows. Use it for tasks where command-line tools or structured integrations


16 16 

17## Set up Computer Use17## Set up Computer Use

18 18 

19In the ChatGPT desktop app, select Work or Codex. Open **Plugins > Computer19In the ChatGPT desktop app, select ChatGPT and switch to Work mode, or select

20Codex. Open **Plugins > Computer

20Use** and select **Install plugin** if prompted. If ChatGPT shows **Enable**,21Use** and select **Install plugin** if prompted. If ChatGPT shows **Enable**,

21select it. Turn on the Computer Use server and skill toggles, then select **Try22select it. Turn on the Computer Use server and skill toggles, then select **Try

22now** to start.23now** to start.

Details

34- **Repeated mistakes**: If the agent makes the same mistake repeatedly, add a rule.34- **Repeated mistakes**: If the agent makes the same mistake repeatedly, add a rule.

35- **Too much reading**: If it finds the right files but reads too many documents, add routing guidance (which directories/files to prioritize).35- **Too much reading**: If it finds the right files but reads too many documents, add routing guidance (which directories/files to prioritize).

36- **Recurring PR feedback**: If you leave the same feedback more than once, codify it.36- **Recurring PR feedback**: If you leave the same feedback more than once, codify it.

37- **In GitHub**: In a pull request comment, tag `@codex` with a request (for example, `@codex add this to AGENTS.md`) to delegate the update to a cloud task.37- **In GitHub**: In a pull request comment, tag `@codex` with a request (for example, `@codex add this to AGENTS.md`) to delegate the update to a cloud chat.

38- **Automate drift checks**: Use [scheduled tasks](https://learn.chatgpt.com/docs/automations) to run recurring checks (for example, daily) that look for guidance gaps and suggest what to add to `AGENTS.md`.38- **Automate drift checks**: Use [scheduled tasks](https://learn.chatgpt.com/docs/automations) to run recurring checks (for example, daily) that look for guidance gaps and suggest what to add to `AGENTS.md`.

39 39 

40Pair `AGENTS.md` with infrastructure that enforces those rules: pre-commit hooks, linters, and type checkers catch issues before you see them, so the system gets smarter about preventing recurring mistakes.40Pair `AGENTS.md` with infrastructure that enforces those rules: pre-commit hooks, linters, and type checkers catch issues before you see them, so the system gets smarter about preventing recurring mistakes.

Details

1# Sandbox1# Sandbox

2 2 

3The sandbox is the boundary that lets the agent act autonomously without giving it3The sandbox is the boundary that lets the agent act autonomously without giving it

4unrestricted access to your machine. When a local task runs commands in the4unrestricted access to your machine. When a local chat runs commands in the

5**ChatGPT desktop app**, **Codex CLI**, or **IDE extension**, those commands run inside a5**ChatGPT desktop app**, **Codex CLI**, or **IDE extension**, those commands run inside a

6constrained environment instead of running with full access by default.6constrained environment instead of running with full access by default.

7 7 

Details

73also perform read-only checks to gather missing context, but it does so rarely.73also perform read-only checks to gather missing context, but it does so rarely.

74 74 

75Hidden assistant reasoning is not included. Auto-review sees retained75Hidden assistant reasoning is not included. Auto-review sees retained

76conversation items and tool evidence, not private chain-of-thought.76chat items and tool evidence, not private chain-of-thought.

77 77 

78## Denials and failure behavior78## Denials and failure behavior

79 79 

Details

1# Subagents1# Subagents

2 2 

3ChatGPT Work and Codex can run subagent workflows by spawning specialized3Work mode and Codex can run subagent workflows by spawning specialized

4agents in parallel and then collecting their results in one response. This can4agents in parallel and then collecting their results in one response. This can

5be particularly helpful for complex tasks that are highly parallel, such as5be particularly helpful for complex tasks that are highly parallel, such as

6codebase exploration or implementing a multi-step feature plan.6codebase exploration or implementing a multi-step feature plan.


28 28 

29 29 

30 30 

31Ask Codex in an app task to delegate independent parts of the work to31Ask Codex in an app chat to delegate independent parts of the work to

32subagents. Current local Codex releases delegate when you ask directly or when32subagents. Current local Codex releases delegate when you ask directly or when

33applicable `AGENTS.md` or skill instructions request it. The app surfaces each33applicable `AGENTS.md` or skill instructions request it. The app surfaces each

34subagent thread so you can inspect its work and the summary returned to the main34subagent thread so you can inspect its work and the summary returned to the main

35task.35chat.

36 36 

37 37 

38 38 


42 42 

43## Why subagent workflows help43## Why subagent workflows help

44 44 

45Even with large context windows, models have limits. If you flood the main conversation (where you're defining requirements, constraints, and decisions) with noisy intermediate output such as exploration notes, test logs, stack traces, and command output, the session can become less reliable over time.45Even with large context windows, models have limits. If you flood the main chat (where you're defining requirements, constraints, and decisions) with noisy intermediate output such as exploration notes, test logs, stack traces, and command output, the session can become less reliable over time.

46 46 

47This is often described as:47This is often described as:

48 48 

49- **Context pollution**: useful information gets buried under noisy intermediate output.49- **Context pollution**: useful information gets buried under noisy intermediate output.

50- **Context rot**: performance degrades as the conversation fills up with less relevant details.50- **Context rot**: performance degrades as the chat fills up with less relevant details.

51 51 

52For background, see the Chroma writeup on [context rot](https://research.trychroma.com/context-rot).52For background, see the Chroma writeup on [context rot](https://research.trychroma.com/context-rot).

53 53 


186- Ask Codex directly to steer a running subagent, stop it, or close completed186- Ask Codex directly to steer a running subagent, stop it, or close completed

187 subagent threads.187 subagent threads.

188 188 

189<Illustration description="Codex desktop task showing two subagents working in parallel.">189<Illustration description="Codex desktop chat showing two subagents working in parallel.">

190 <SubagentWorkflowIllustration ariaLabel="Codex desktop task showing two subagents working in parallel." />190 <SubagentWorkflowIllustration ariaLabel="Codex desktop chat showing two subagents working in parallel." />

191</Illustration>191</Illustration>

192 192 

193<Illustration description="Codex desktop Subagents panel with no active subagents and three completed audits.">193<Illustration description="Codex desktop Subagents panel with no active subagents and three completed audits.">

Details

224`region` to the supported Bedrock region that should handle requests.224`region` to the supported Bedrock region that should handle requests.

225 225 

226For the full setup flow, authentication options, supported models, and feature226For the full setup flow, authentication options, supported models, and feature

227availability, see [Use Codex with Amazon Bedrock](https://learn.chatgpt.com/docs/amazon-bedrock).227availability, see [Use ChatGPT Work and Codex with Amazon

228Bedrock](https://learn.chatgpt.com/docs/amazon-bedrock).

228 229 

229## OSS mode (local providers)230## OSS mode (local providers)

230 231 

config-basic.md +1 −1

Details

89 89 

90#### Web search mode90#### Web search mode

91 91 

92Codex enables web search by default for local tasks and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://learn.chatgpt.com/docs/agent-approvals-security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:92Codex enables web search by default for local chats and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://learn.chatgpt.com/docs/agent-approvals-security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:

93 93 

94- `"cached"` (default) serves results from the web search cache.94- `"cached"` (default) serves results from the web search cache.

95- `"indexed"` permits external web access only when the search index gates the request.95- `"indexed"` permits external web access only when the search index gates the request.

Details

224`region` to the supported Bedrock region that should handle requests.224`region` to the supported Bedrock region that should handle requests.

225 225 

226For the full setup flow, authentication options, supported models, and feature226For the full setup flow, authentication options, supported models, and feature

227availability, see [Use Codex with Amazon Bedrock](https://learn.chatgpt.com/docs/amazon-bedrock).227availability, see [Use ChatGPT Work and Codex with Amazon

228Bedrock](https://learn.chatgpt.com/docs/amazon-bedrock).

228 229 

229## OSS mode (local providers)230## OSS mode (local providers)

230 231 

Details

89 89 

90#### Web search mode90#### Web search mode

91 91 

92Codex enables web search by default for local tasks and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://learn.chatgpt.com/docs/agent-approvals-security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:92Codex enables web search by default for local chats and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://learn.chatgpt.com/docs/agent-approvals-security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:

93 93 

94- `"cached"` (default) serves results from the web search cache.94- `"cached"` (default) serves results from the web search cache.

95- `"indexed"` permits external web access only when the search index gates the request.95- `"indexed"` permits external web access only when the search index gates the request.

Details

3<CodexDocsOverviewLanding3<CodexDocsOverviewLanding

4 title="Configuration"4 title="Configuration"

5 description="Set defaults, add durable context, and customize how ChatGPT and Codex developer tools work."5 description="Set defaults, add durable context, and customize how ChatGPT and Codex developer tools work."

6 intro="Configuration shapes how ChatGPT and Codex developer tools behave across tasks, repositories, and machines. Durable context, config files, repository guidance, subagents, external connections, and Windows setup work together to keep those workflows consistent for individuals and teams."6 intro="Configuration shapes how ChatGPT and Codex developer tools behave across chats, repositories, and machines. Durable context, config files, repository guidance, subagents, external connections, and Windows setup work together to keep those workflows consistent for individuals and teams."

7 primaryCta={{7 primaryCta={{

8 label: "Explore customization",8 label: "Explore customization",

9 href: "/codex/customization/overview",9 href: "/codex/customization/overview",


17 {17 {

18 title: "Customization",18 title: "Customization",

19 description:19 description:

20 "Adapt the experience and carry useful context between tasks.",20 "Adapt the experience and carry useful context between chats.",

21 pages: [21 pages: [

22 {22 {

23 title: "Customization overview",23 title: "Customization overview",


28 },28 },

29 {29 {

30 title: "Memories",30 title: "Memories",

31 description:31 description: "Let ChatGPT retain useful context across chats.",

32 "Let ChatGPT retain useful context across chats and tasks.",

33 href: "/codex/customization/memories",32 href: "/codex/customization/memories",

34 icon: "threads",33 icon: "threads",

35 },34 },

Details

41- **Named placeholders:** Use uppercase names like `$FILE` or `$TICKET_ID` and supply values as `KEY=value`. Quote values with spaces (for example, `FOCUS="loading state"`).41- **Named placeholders:** Use uppercase names like `$FILE` or `$TICKET_ID` and supply values as `KEY=value`. Quote values with spaces (for example, `FOCUS="loading state"`).

42- **Literal dollar signs:** Write `$$` to emit a single `$` in the expanded prompt.42- **Literal dollar signs:** Write `$$` to emit a single `$` in the expanded prompt.

43 43 

44After editing prompt files, restart Codex or open a new task so the updates load. Codex ignores non-Markdown files in the prompts directory.44After editing prompt files, restart Codex or open a new chat so the updates load. Codex ignores non-Markdown files in the prompts directory.

45 45 

46## Invoke and manage custom commands46## Invoke and manage custom commands

47 47 

Details

783. Turn on **Chronicle** below the Memories setting.783. Turn on **Chronicle** below the Memories setting.

794. Review the consent dialog and choose **Continue**.794. Review the consent dialog and choose **Continue**.

805. Grant macOS Screen Recording and Accessibility permissions when prompted.805. Grant macOS Screen Recording and Accessibility permissions when prompted.

816. When setup completes, choose **Try it out** or start a new task.816. When setup completes, choose **Try it out** or start a new chat.

82 82 

83If macOS reports that Screen Recording or Accessibility permission is denied,83If macOS reports that Screen Recording or Accessibility permission is denied,

84open System Settings &gt; Privacy & Security &gt; Screen Recording or84open System Settings &gt; Privacy & Security &gt; Screen Recording or


94Codex to use as context. To disable Chronicle, return to **Settings &gt;94Codex to use as context. To disable Chronicle, return to **Settings &gt;

95Personalization &gt; Memories** and turn off **Chronicle**.95Personalization &gt; Memories** and turn off **Chronicle**.

96 96 

97You can also control whether memories are used in a given task. [Learn97You can also control whether memories are used in a given chat. [Learn

98more](https://learn.chatgpt.com/docs/customization/memories#control-memories-per-task).98more](https://learn.chatgpt.com/docs/customization/memories#control-memories-per-chat).

99 99 

100## Rate limits100## Rate limits

101 101 

Details

15 15 

16 16 

17 17 

18In the ChatGPT desktop app, use `/memories` to choose whether a task can use18In the ChatGPT desktop app, use `/memories` to choose whether a chat can use

19local memories or contribute to future memories. Manage the feature from19local memories or contribute to future memories. Manage the feature from

20**Settings > Personalization** when you need to turn it on or off.20**Settings > Personalization** when you need to turn it on or off.

21 21 


46## How local Codex memories work46## How local Codex memories work

47 47 

48After you enable memories, Codex can turn useful context from eligible prior48After you enable memories, Codex can turn useful context from eligible prior

49tasks into local memory files. Codex skips active or short-lived sessions,49chats into local memory files. Codex skips active or short-lived sessions,

50redacts secrets from generated memory fields, and updates memories in the50redacts secrets from generated memory fields, and updates memories in the

51background instead of immediately at the end of every task.51background instead of immediately at the end of every chat.

52 52 

53Memories may not update right away when a task ends. Codex waits until a53Memories may not update right away when a chat ends. Codex waits until a

54task has been idle long enough to avoid summarizing work that's still in54chat has been idle long enough to avoid summarizing work that's still in

55progress.55progress.

56 56 

57Memory generation can also skip a background pass when your Codex rate-limit57Memory generation can also skip a background pass when your Codex rate-limit


65for how Codex uses `CODEX_HOME`.65for how Codex uses `CODEX_HOME`.

66 66 

67The main memory files live under `~/.codex/memories/` and include summaries,67The main memory files live under `~/.codex/memories/` and include summaries,

68durable entries, recent inputs, and supporting evidence from prior tasks.68durable entries, recent inputs, and supporting evidence from prior chats.

69 69 

70Treat these files as generated state. You can inspect them when troubleshooting70Treat these files as generated state. You can inspect them when troubleshooting

71or before sharing your Codex home directory, but don't rely on editing them by71or before sharing your Codex home directory, but don't rely on editing them by

72hand as your primary control surface.72hand as your primary control surface.

73 73 

74## Control local memories per task74<a id="control-local-memories-per-task"></a>

75 

76## Control local memories per chat

75 77 

76In the ChatGPT desktop app and Codex TUI, use `/memories` to control memory behavior for78In the ChatGPT desktop app and Codex TUI, use `/memories` to control memory behavior for

77the current task. Task-level choices let you decide whether the current79the current chat. Chat-level choices let you decide whether the current

78task can use existing memories and whether Codex can use the task to80chat can use existing memories and whether Codex can use the chat to

79generate future memories.81generate future memories.

80 82 

81Task-level choices don't change your global memory settings.83Chat-level choices don't change your global memory settings.

82 84 

83## Review local memories85## Review local memories

84 86 


107 109 

108Common memory-specific settings include:110Common memory-specific settings include:

109 111 

110- `memories.generate_memories`: controls whether newly created tasks can be112- `memories.generate_memories`: controls whether newly created chats can be

111 stored as memory-generation inputs.113 stored as memory-generation inputs.

112- `memories.use_memories`: controls whether Codex injects existing memories into114- `memories.use_memories`: controls whether Codex injects existing memories into

113 future sessions.115 future sessions.

114- `memories.disable_on_external_context`: when `true`, keeps tasks that used116- `memories.disable_on_external_context`: when `true`, keeps chats that used

115 external context such as MCP tool calls, web search, or tool search out of117 external context such as MCP tool calls, web search, or tool search out of

116 memory generation. The older `memories.no_memories_if_mcp_or_web_search` key118 memory generation. The older `memories.no_memories_if_mcp_or_web_search` key

117 is still accepted as an alias.119 is still accepted as an alias.

118- `memories.min_rate_limit_remaining_percent`: controls the minimum remaining120- `memories.min_rate_limit_remaining_percent`: controls the minimum remaining

119 Codex rate-limit percentage required before memory generation starts.121 Codex rate-limit percentage required before memory generation starts.

120- `memories.extract_model`: overrides the model used for per-task memory122- `memories.extract_model`: overrides the model used for per-chat memory

121 extraction.123 extraction.

122- `memories.consolidation_model`: overrides the model used for global memory124- `memories.consolidation_model`: overrides the model used for global memory

123 consolidation.125 consolidation.

Details

34- **Repeated mistakes**: If the agent makes the same mistake repeatedly, add a rule.34- **Repeated mistakes**: If the agent makes the same mistake repeatedly, add a rule.

35- **Too much reading**: If it finds the right files but reads too many documents, add routing guidance (which directories/files to prioritize).35- **Too much reading**: If it finds the right files but reads too many documents, add routing guidance (which directories/files to prioritize).

36- **Recurring PR feedback**: If you leave the same feedback more than once, codify it.36- **Recurring PR feedback**: If you leave the same feedback more than once, codify it.

37- **In GitHub**: In a pull request comment, tag `@codex` with a request (for example, `@codex add this to AGENTS.md`) to delegate the update to a cloud task.37- **In GitHub**: In a pull request comment, tag `@codex` with a request (for example, `@codex add this to AGENTS.md`) to delegate the update to a cloud chat.

38- **Automate drift checks**: Use [scheduled tasks](https://learn.chatgpt.com/docs/automations) to run recurring checks (for example, daily) that look for guidance gaps and suggest what to add to `AGENTS.md`.38- **Automate drift checks**: Use [scheduled tasks](https://learn.chatgpt.com/docs/automations) to run recurring checks (for example, daily) that look for guidance gaps and suggest what to add to `AGENTS.md`.

39 39 

40Pair `AGENTS.md` with infrastructure that enforces those rules: pre-commit hooks, linters, and type checkers catch issues before you see them, so the system gets smarter about preventing recurring mistakes.40Pair `AGENTS.md` with infrastructure that enforces those rules: pre-commit hooks, linters, and type checkers catch issues before you see them, so the system gets smarter about preventing recurring mistakes.

developers.md +2 −2

Details

127 },127 },

128 {128 {

129 title: "GitHub Action",129 title: "GitHub Action",

130 description: "Run Codex tasks from GitHub Actions workflows.",130 description: "Run Codex from GitHub Actions workflows.",

131 href: "/codex/github-action",131 href: "/codex/github-action",

132 icon: "github",132 icon: "github",

133 },133 },


153 {153 {

154 title: "Slack",154 title: "Slack",

155 description:155 description:

156 "Start Codex tasks from conversations and return results.",156 "Start Codex chats from external discussions and return results.",

157 href: "/codex/third-party/slack",157 href: "/codex/third-party/slack",

158 icon: "chat",158 icon: "chat",

159 },159 },

Details

8 Codex CLI, and IDE extension.8 Codex CLI, and IDE extension.

9- Codex cloud.9- Codex cloud.

10- Platform API access.10- Platform API access.

11- Plugins and apps.11- Plugins and connector access.

12- Permissions in connected systems.12- Permissions in connected systems.

13 13 

14Complete the steps in order for a new rollout, or use the linked pages to change14Complete the steps in order for a new rollout, or use the linked pages to change


154 154 

155## Step 6: Configure plugins and connected capabilities155## Step 6: Configure plugins and connected capabilities

156 156 

157Review plugin installation, bundled skills, app-backed capabilities, app157Review plugin installation, bundled skills, connector-backed capabilities,

158actions, and source-system authorization as separate decisions. Disabling an158connector actions, and source-system authorization as separate decisions.

159app-backed capability doesn't necessarily uninstall the plugin or its bundled159Disabling a connector-backed capability doesn't necessarily uninstall the

160skills.160plugin or its bundled skills.

161 161 

162Before including a plugin or skill in the rollout:162Before including a plugin or skill in the rollout:

163 163 

1641. Confirm its source, accountable owner, intended audience, and review date.1641. Confirm its source, accountable owner, intended audience, and review date.

1652. Review bundled skills, apps, MCP servers, hooks, and the data and actions1652. Review bundled skills, connectors, MCP servers, hooks, and the data and

166 each capability requires.166 actions each capability requires.

1673. Test it with non-sensitive data and the least access it needs.1673. Test it with non-sensitive data and the least access it needs.

1684. Record who owns re-review and retirement.1684. Record who owns re-review and retirement.

169 169 

170Plugins are available in ChatGPT Work on the web, in ChatGPT Work and Codex in170Plugins are available in Work mode in ChatGPT on the web, in Work mode and Codex

171the ChatGPT desktop app, and through the Codex CLI plugin browser. They aren't171in the ChatGPT desktop app, and through the Codex CLI plugin browser. They aren't

172available in Chat, the IDE extension, or mobile.172available in Chat mode, the IDE extension, or mobile.

173 173 

174See [Plugin controls](https://learn.chatgpt.com/docs/enterprise/apps-and-connectors) and174See [Plugin controls](https://learn.chatgpt.com/docs/enterprise/apps-and-connectors) and

175[Skill controls](https://learn.chatgpt.com/docs/enterprise/skills) for the complete model.175[Skill controls](https://learn.chatgpt.com/docs/enterprise/skills) for the complete model.


214 extension, including sign-in and effective runtime requirements.214 extension, including sign-in and effective runtime requirements.

215- Codex cloud access, environment configuration, and repository permissions.215- Codex cloud access, environment configuration, and repository permissions.

216- Platform API organization and project access for API-key workflows.216- Platform API organization and project access for API-key workflows.

217- Plugin installation, bundled skills, app access, and supported actions.217- Plugin installation, bundled skills, connector access, and supported actions.

218- Connected-system authorization and data access.218- Connected-system authorization and data access.

219- Analytics and compliance access for the responsible administrators.219- Analytics and compliance access for the responsible administrators.

220 220 

Details

5[skills](https://learn.chatgpt.com/docs/skills-and-plugins), and5[skills](https://learn.chatgpt.com/docs/skills-and-plugins), and

6[apps and connectors](https://help.openai.com/en/articles/11487775).6[apps and connectors](https://help.openai.com/en/articles/11487775).

7 7 

8ChatGPT presents connectors as apps. If a plugin includes a connector-backed8When a plugin includes a connector, workspace admins must make the plugin

9capability, workspace admins must enable the corresponding app and configure9available through plugin controls and configure connector access before members

10its access before members can use that part of the plugin.10can use the connector-backed capability.

11 11 

12Plugins are available in ChatGPT Work on the web, in ChatGPT Work and Codex in12Plugins are available in Work mode in ChatGPT on the web, in Work mode and Codex

13the ChatGPT desktop app, and through the Codex CLI plugin browser. Availability13in the ChatGPT desktop app, and through the Codex CLI plugin browser.

14on those surfaces doesn't make plugins available in Chat, the IDE extension,14Availability on those surfaces doesn't make plugins available in Chat mode,

15or mobile.15the IDE extension, or mobile.

16 16 

17For the complete administration model, see17For the complete administration model, see

18[Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions).18[Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions).


22Each layer has a separate scope and control surface:22Each layer has a separate scope and control surface:

23 23 

24| Layer | What it determines | Where to manage it |24| Layer | What it determines | Where to manage it |

25| ------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |25| ------------------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |

26| Plugin availability and installation | Whether the plugin bundle is available to the user | [Workspace settings](https://chatgpt.com/admin/settings) for supported web and desktop surfaces; the CLI plugin browser for CLI |26| Plugin availability and installation | Whether the plugin bundle is available to the user | [Workspace settings](https://chatgpt.com/admin/settings) for supported web and desktop surfaces; the CLI plugin browser for CLI |

27| Bundled skills | Which reusable instructions the installed plugin contributes | The plugin package and [Skill controls](https://learn.chatgpt.com/docs/enterprise/skills) |27| Bundled skills | Which reusable instructions the installed plugin contributes | The plugin package and [Skill controls](https://learn.chatgpt.com/docs/enterprise/skills) |

28| Connector access (Apps) | Whether users can use a connector-backed capability | [Workspace apps](https://chatgpt.com/admin/ca) and [Permissions & roles](https://chatgpt.com/admin/settings) |28| Connector access | Whether users can use a connector-backed capability | [Workspace apps](https://chatgpt.com/admin/ca) and [Permissions & roles](https://chatgpt.com/admin/settings) |

29| Connector actions and app permissions | Which actions users can run and when ChatGPT asks before using the app | The app's Action control and App permissions in [Workspace apps](https://chatgpt.com/admin/ca) |29| Connector actions and permissions | Which actions users can run and when ChatGPT asks before using the connector | The connector's Action control and App permissions in [Workspace apps](https://chatgpt.com/admin/ca) |

30| Source-system authorization | Which external data and actions the authenticated identity can access | The connected service and its identity provider |30| Source-system authorization | Which external data and actions the authenticated identity can access | The connected service and its identity provider |

31| Runtime permissions | What an agent can do after it receives data or a tool | The runtime, sandbox, and approval controls for the active surface |31| Runtime permissions | What an agent can do after it receives data or a tool | The runtime, sandbox, and approval controls for the active surface |

32 32 

33Depending on the workflow, admins can govern plugin availability, connector33Depending on the workflow, admins can govern plugin availability, connector

34access, app actions and permissions, provider authorization, and runtime policy34access, connector actions and permissions, provider authorization, and runtime

35independently.35policy independently.

36 36 

37## Plugin availability controls37## Plugin availability controls

38 38 


43 43 

44## Connector-backed capability controls44## Connector-backed capability controls

45 45 

46In ChatGPT, **Apps** is the product label for connected capabilities, including46In ChatGPT, plugins can include connectors that search, retrieve, sync, or act

47connectors that search, retrieve, sync, or act on external systems. A plugin can47on external systems. Workspace admins configure plugin availability separately

48refer to an app so its workflows can use those connector capabilities.48from the access and actions granted to each connector.

49 49 

50Manage connector-backed capabilities from50Manage connector-backed capabilities from

51[Workspace apps](https://chatgpt.com/admin/ca) and51[Workspace apps](https://chatgpt.com/admin/ca) and

52[Permissions & roles](https://chatgpt.com/admin/settings). Available controls52[Permissions & roles](https://chatgpt.com/admin/settings). Available controls

53let admins:53let admins:

54 54 

55- Enable reviewed apps and assign access by workspace role.55- Enable reviewed connectors and assign access by workspace role.

56- For apps that support Action control, allow read-only actions or an approved56- For connectors that support Action control, allow read-only actions or an

57 custom set, including how the workspace handles newly added actions.57 approved custom set, including how the workspace handles newly added actions.

58- Set app permissions that determine when ChatGPT asks before using an app.58- Set App permissions that determine when ChatGPT asks before using a connector.

59- Keep access within the scopes and permissions granted by each connected59- Keep access within the scopes and permissions granted by each connected

60 service and authenticated user.60 service and authenticated user.

61 61 

62For current availability and procedures, see62For current availability and procedures, see

63[Admin controls, security, and compliance in apps](https://help.openai.com/en/articles/11509118).63[Admin controls, security, and compliance in apps](https://help.openai.com/en/articles/11509118).

64 64 

65## Choose a starting set of apps65<a id="choose-a-starting-set-of-apps"></a>

66 66 

67For a broad initial rollout, consider app categories teams use every day: email,67## Choose a starting set of plugins

68calendar, and file or document systems such as Google Drive or Notion. Use the68 

69[ChatGPT app directory](https://chatgpt.com/apps) to confirm current69For a broad initial rollout, consider plugin categories teams use every day:

70email, calendar, and file or document systems such as Google Drive or Notion.

71Use the [Plugins Directory](https://chatgpt.com/apps) to confirm current

70availability and capabilities.72availability and capabilities.

71 73 

72Start with read actions. Enable write actions only after reviewing the app's74Start with read actions. Enable write actions only after reviewing the plugin's

73owner, requested scopes, data access, external effects, and recovery path.75owner, each connector's requested scopes, data access, external effects, and

76recovery path.

74 77 

75## Understand data flow and security78## Understand data flow and security

76 79 

77When ChatGPT uses a connector-backed app, the app sends a request to the80When ChatGPT uses a connector-backed plugin, the connector sends a request to

78connected service and returns data or action results allowed by the81the connected service and returns data or action results allowed by the

79authenticated user's provider permissions. Custom apps expose these operations82authenticated user's provider permissions. Custom Apps SDK apps expose these

80as tools through Model Context Protocol (MCP).83operations as tools through Model Context Protocol (MCP).

81 84 

82For non-synced app use, ChatGPT processes Chat and deep-research data85For non-synced connector use, ChatGPT processes data from Chat mode and deep

83transiently and doesn't index it. Apps with sync index selected connected86research transiently and doesn't index it. Connectors with sync index selected

84content in advance. This indexing distinction doesn't replace normal87connected content in advance. This indexing distinction doesn't replace normal

85conversation-retention controls; conversations that use apps remain available88chat-retention controls; chats that use plugins remain available through the

86through the Compliance API.89Compliance API.

87 90 

88OpenAI's current app guidance also documents encryption in transit and at rest,91OpenAI's current connector guidance also documents encryption in transit and at

89per-user authorization, role and action controls, restricted network access for92rest, per-user authorization, role and action controls, restricted network

90app conversations, and no model training on information accessed from apps for93access for chats that use plugins, and no model training on information accessed

91Business, Enterprise, and Edu customers. Review the connected service's scopes,94through plugins for Business, Enterprise, and Edu customers. Review the

92retention, and data-residency policies because those policies apply when a95connected service's scopes, retention, and data-residency policies because those

93request reaches that service.96policies apply when a request reaches that service.

94 97 

95See [app security and compliance](https://help.openai.com/en/articles/11509118)98See [app security and compliance](https://help.openai.com/en/articles/11509118)

96and [apps with sync](https://help.openai.com/en/articles/10847137) for the99and [apps with sync](https://help.openai.com/en/articles/10847137) for the

Details

554marketplaces or their plugins at runtime.554marketplaces or their plugins at runtime.

555 555 

556These source restrictions apply only where a local client supports plugin556These source restrictions apply only where a local client supports plugin

557marketplace operations: ChatGPT Work and Codex in the ChatGPT desktop app, and557marketplace operations: Work mode and Codex in the ChatGPT desktop app, and

558Codex CLI. They don't add plugins to Chat, the IDE extension, or mobile.558Codex CLI. They don't add plugins to Chat, the IDE extension, or mobile.

559 559 

560## Managed defaults (`managed_config.toml`)560## Managed defaults (`managed_config.toml`)

Details

20| Local clients | Runtime behavior for covered capabilities in the ChatGPT desktop app, Codex CLI, and IDE extension, including approvals, filesystem and network access, permission profiles, and allowed integrations | A ChatGPT seat, feature or model entitlement, or access to external data | [Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration) and [Permissions](https://learn.chatgpt.com/docs/permissions) |20| Local clients | Runtime behavior for covered capabilities in the ChatGPT desktop app, Codex CLI, and IDE extension, including approvals, filesystem and network access, permission profiles, and allowed integrations | A ChatGPT seat, feature or model entitlement, or access to external data | [Managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration) and [Permissions](https://learn.chatgpt.com/docs/permissions) |

21| Codex cloud | Eligibility to use hosted Codex workflows and the cloud environments made available to the user | Local runtime policy or the repository permissions granted by a source system | [Cloud environments](https://learn.chatgpt.com/docs/environments/cloud-environment) |21| Codex cloud | Eligibility to use hosted Codex workflows and the cloud environments made available to the user | Local runtime policy or the repository permissions granted by a source system | [Cloud environments](https://learn.chatgpt.com/docs/environments/cloud-environment) |

22| Platform API | Organization and project membership, API keys, model access, usage, and billing for API-authenticated work | ChatGPT workspace membership, local-client access, or Codex cloud access | [OpenAI API Platform](https://platform.openai.com/docs/overview) |22| Platform API | Organization and project membership, API keys, model access, usage, and billing for API-authenticated work | ChatGPT workspace membership, local-client access, or Codex cloud access | [OpenAI API Platform](https://platform.openai.com/docs/overview) |

23| Plugins and apps | Plugin availability and installation, bundled skills, app access, and supported app actions | Authorization in the connected service or broader local and cloud runtime permissions | [Plugin controls](https://learn.chatgpt.com/docs/enterprise/apps-and-connectors) |23| Plugins | Plugin availability and installation, bundled skills, connector access, and supported connector actions | Authorization in the connected service or broader local and cloud runtime permissions | [Plugin controls](https://learn.chatgpt.com/docs/enterprise/apps-and-connectors) |

24| Connected systems | Which repositories, files, messages, and actions the authenticated account can access in the source system | ChatGPT workspace, plugin, Codex cloud, or Platform API entitlement | The connected service's administration and access controls |24| Connected systems | Which repositories, files, messages, and actions the authenticated account can access in the source system | ChatGPT workspace, plugin, Codex cloud, or Platform API entitlement | The connected service's administration and access controls |

25 25 

26A request must pass every boundary that applies to it. For example, workspace26A request must pass every boundary that applies to it. For example, workspace

27access can make an app available, but the connected service still decides which27access can make a plugin available, but the connected service still decides which

28data the signed-in account can read. A local permission profile can restrict a28data the signed-in account can read. A local permission profile can restrict a

29run in a supported local client, but it can't grant a workspace feature or29run in a supported local client, but it can't grant a workspace feature or

30model.30model.

Details

8For the complete administration model, see8For the complete administration model, see

9[Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions).9[Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions).

10 10 

11## Distinguish the distribution models11<a id="distinguish-the-distribution-models"></a>

12 

13## Skill distribution and administration

12 14 

13| Distribution model | Use it for | Administration boundary |15| Distribution model | Use it for | Administration boundary |

14| ----------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |16| ----------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |

15| ChatGPT workspace Skill | Sharing or installing an approved workflow through supported ChatGPT workspace features | ChatGPT workspace skill permissions and lifecycle controls |17| ChatGPT workspace Skill | Sharing or installing an approved workflow through supported ChatGPT workspace features | ChatGPT workspace skill permissions and lifecycle controls |

16| Local filesystem skill | Loading an installed workflow from a repository, user, administrator, or bundled system location | Filesystem distribution, local client configuration, and runtime permissions |18| Local filesystem skill | Loading an installed workflow from a repository, user, administrator, or bundled system location | Filesystem distribution, local client configuration, and runtime permissions |

17| Plugin | Packaging one or more skills with optional apps, MCP servers, hooks, and presentation metadata | Plugin availability and installation, plus the separate controls for every bundled capability |19| Plugin | Packaging one or more skills with optional connectors, MCP servers, hooks, and presentation metadata | Plugin availability and installation, plus the separate controls for every bundled capability |

18 20 

19ChatGPT workspace skill distribution, local filesystem skill installation, and21ChatGPT workspace skill distribution, local filesystem skill installation, and

20surface-specific plugin installation are separate paths. Moving a skill doesn't22surface-specific plugin installation are separate paths. Moving a skill doesn't

21transfer ChatGPT workspace ownership, sharing, role assignments, plugin23transfer ChatGPT workspace ownership, sharing, role assignments, plugin

22installation state, or app authorization.24installation state, or connector authorization.

23 25 

24Plugins are available in ChatGPT Work on the web, in ChatGPT Work and Codex in26Plugins are available in Work mode in ChatGPT on the web, in Work mode and Codex

25the ChatGPT desktop app, and through the Codex CLI plugin browser. They aren't27in the ChatGPT desktop app, and through the Codex CLI plugin browser. They aren't

26available in Chat, the IDE extension, or mobile.28available in Chat mode, the IDE extension, or mobile.

27 29 

28## Owning controls30## Owning controls

29 31 


34 36 

35ChatGPT workspace controls don't install local filesystem skills or plugins.37ChatGPT workspace controls don't install local filesystem skills or plugins.

36Filesystem distribution doesn't assign ChatGPT workspace ownership or roles.38Filesystem distribution doesn't assign ChatGPT workspace ownership or roles.

37Plugin installation doesn't grant access to an app, MCP server, or connected39Plugin installation doesn't grant access to a connector, MCP server, or

38service. Configure each capability through the control surface that owns it.40connected service. Configure each capability through the control surface that

41owns it.

39 42 

40## Related docs43## Related docs

41 44 

Details

11| Users install and update their own apps | Use the [web installer](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi). |11| Users install and update their own apps | Use the [web installer](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi). |

12| IT deploys the app and Microsoft update services are available | Deploy the Microsoft Store app through Intune or another management tool. |12| IT deploys the app and Microsoft update services are available | Deploy the Microsoft Store app through Intune or another management tool. |

13| IT controls update timing or blocks Microsoft update services | Redeploy each new version through your software-management process. |13| IT controls update timing or blocks Microsoft update services | Redeploy each new version through your software-management process. |

14| Your network blocks Microsoft app-distribution services | Use the offline MSIX package for restricted networks. |14| Your network blocks Microsoft app-distribution services | Deploy the Store-signed MSIX package for each device architecture. |

15 15 

16## Let users install and update the app16## Let users install and update the app

17 17 


63## Deploy without Microsoft distribution services63## Deploy without Microsoft distribution services

64 64 

65If your environment can't use the standard Microsoft distribution services,65If your environment can't use the standard Microsoft distribution services,

66download [Codex-x64.zip](https://persistent.oaistatic.com/codex-app-prod/Codex-x64.zip)66download the Store-signed MSIX package for each device architecture:

67as an offline deployment option. The archive contains the Store-signed offline67 

68MSIX package and its associated license files. Ingest these files into your MDM68| Device architecture | Package |

69| ------------------- | ---------------------------------------------------------------------------------------- |

70| x64 | [ChatGPT-x64.msix](https://persistent.oaistatic.com/codex-app-prod/ChatGPT-x64.msix) |

71| Arm64 | [ChatGPT-arm64.msix](https://persistent.oaistatic.com/codex-app-prod/ChatGPT-arm64.msix) |

72 

73These stable links point to the latest published Store package. For offline

74deployment workflows that require a license file, also download the

75[offline license (`ChatGPT-License.xml`)](https://persistent.oaistatic.com/codex-app-prod/ChatGPT-License.xml).

76Ingest the appropriate MSIX and, when required, the license file into your MDM

69or software-deployment platform.77or software-deployment platform.

70 78 

71The offline package:79This deployment path:

72 80 

73- Supports deployment in restricted environments.81- Supports deployment in restricted environments.

82- Supports x64 and Arm64 devices.

74- Doesn't provide a standalone MSI or non-Store EXE.83- Doesn't provide a standalone MSI or non-Store EXE.

75- Doesn't let users update the app themselves.84- Doesn't let users update the app themselves.

76- Requires your organization to deploy newer packages when updating the app.85- Requires your organization to deploy newer packages when updating the app.

Details

1# ChatGPT Work Admin FAQ1# Work mode admin FAQ

2 2 

3ChatGPT Work brings the technology behind Codex into ChatGPT for longer,3Work mode brings the technology behind Codex into ChatGPT for longer,

4multi-step tasks. It can gather context from conversations, files, workspace4multi-step tasks. It can gather context from chats, files, workspace

5resources, and connected systems; use approved tools; and create review-ready5resources, and connected systems; use approved tools; and create review-ready

6artifacts. Access, context, actions, network behavior, and credit use vary by6outputs. Access, context, actions, network behavior, and credit use vary by

7plan, workspace settings, source permissions, and surface.7plan, workspace settings, source permissions, and surface.

8 8 

9## Overview9## Overview

10 10 

11Work lets users delegate longer, multi-step tasks to ChatGPT. It can gather11Work mode lets users delegate longer, multi-step tasks to ChatGPT. It can gather

12information from connected sources, reason across steps, create documents,12information from connected sources, reason across steps, create documents,

13presentations, or analyses, and return results for review.13presentations, or analyses, and return results for review.

14 14 

15Work launches July 9, 2026. For Enterprise and Edu, web and mobile access starts15Work mode launched July 9, 2026. For Enterprise and Edu, web and mobile access is

16off by default during a two-week preview. Admins can enable billable usage, and16off by default during a two-week preview. Admins can enable billable usage, and

17explicit opt-outs persist when the default changes. Desktop access remains17explicit opt-outs persist when the default changes. Desktop access remains

18governed separately through Codex Local permissions and managed configuration.18governed separately through Codex Local permissions and managed configuration.

19 19 

20This FAQ explains how admins manage Work in ChatGPT: access and data controls,20This FAQ explains how admins manage Work mode in ChatGPT: access and data controls,

21compliance and visibility, usage and spend, incident response, and rollout21compliance and visibility, usage and spend, incident response, and rollout

22practices.22practices.

23 23 

24## Core administrative controls24## Core administrative controls

25 25 

26Administrators govern Work through several control layers:26Administrators govern Work mode through several control layers:

27 27 

28- **Access to the enterprise workspace:** Identity and access controls manage28- **Access to the enterprise workspace:** Identity and access controls manage

29 authentication and access to the workspace. Depending on the plan and29 authentication and access to the workspace. Depending on the plan and


33 enforce workspace-wide MFA through your identity provider. Manage SSO and33 enforce workspace-wide MFA through your identity provider. Manage SSO and

34 related identity settings in the34 related identity settings in the

35 [Global Admin Console](https://help.openai.com/en/articles/12289294-admin-portal).35 [Global Admin Console](https://help.openai.com/en/articles/12289294-admin-portal).

36- **Access to Work within the workspace:** On web and mobile, admins use the36- **Access to Work mode within the workspace:** On web and mobile, admins use the

37 top-level Work control and role-based access control (RBAC) to decide who can37 Work mode access control and role-based access control (RBAC) to decide who can

38 use it. Enterprise and Edu access starts off during the two-week preview;38 use it. Enterprise and Edu access is off during the two-week preview;

39 admins can enable it, and explicit opt-outs persist when the default changes.39 admins can enable it, and explicit opt-outs persist when the default changes.

40 Desktop access follows separate Codex Local permissions and40 Desktop access follows separate Codex Local permissions and

41 [managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration). Controls41 [managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration). Controls


46 [Groups and provisioning](https://learn.chatgpt.com/docs/enterprise/groups-and-provisioning).46 [Groups and provisioning](https://learn.chatgpt.com/docs/enterprise/groups-and-provisioning).

47- **Workspace and member roles:** Built-in Owner, Admin, and Member roles47- **Workspace and member roles:** Built-in Owner, Admin, and Member roles

48 determine who can administer the workspace. Custom roles and member RBAC48 determine who can administer the workspace. Custom roles and member RBAC

49 separately control end-user access to Work, apps, and other capabilities.49 separately control end-user access to Work mode, plugins, and other capabilities.

50 See50 See

51 [Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions).51 [Roles and workspace permissions](https://learn.chatgpt.com/docs/enterprise/roles-and-workspace-permissions).

52- **Plugins and apps:** Plugin policy governs plugin availability and52- **Plugins and connectors:** Plugin policy governs plugin availability and

53 installation. App access, action controls, and approval behavior are53 installation. Connector access, action controls, and approval behavior are

54 configured separately, and Workspace Agents have additional per-agent54 configured separately, and Workspace Agents have additional per-agent

55 controls. See [Plugin controls](https://learn.chatgpt.com/docs/enterprise/apps-and-connectors),55 controls. See [Plugin controls](https://learn.chatgpt.com/docs/enterprise/apps-and-connectors),

56 [Plugins](https://learn.chatgpt.com/docs/plugins), and the56 [Plugins](https://learn.chatgpt.com/docs/plugins), and the


58- **Source-system permissions:** A user can access only the content and actions58- **Source-system permissions:** A user can access only the content and actions

59 allowed by the account or shared connection in the native application. See59 allowed by the account or shared connection in the native application. See

60 [Admin controls, security, and compliance in apps](https://help.openai.com/en/articles/11509118-admin-controls-security-and-compliance-in-apps-enterprise-edu-and-business).60 [Admin controls, security, and compliance in apps](https://help.openai.com/en/articles/11509118-admin-controls-security-and-compliance-in-apps-enterprise-edu-and-business).

61- **Approval and action restrictions:** For apps that support Action control,61- **Approval and action restrictions:** For connectors that support Action control,

62 admins can allow all actions, read-only actions, or a custom set and decide62 admins can allow all actions, read-only actions, or a custom set and decide

63 how newly added actions are handled. App permissions separately determine63 how newly added actions are handled. App permissions separately determine

64 when ChatGPT asks before using an app.64 when ChatGPT asks before using a connector.

65- **Credits:** ChatGPT Work and Codex share pricing, credits, and usage limits.65- **Credits:** Work mode and Codex share pricing, credits, and usage limits.

66 Eligible Enterprise and Edu admins can set monthly per-user limits through a66 Eligible Enterprise and Edu admins can set monthly per-user limits through a

67 workspace default, group defaults, and individual overrides. Users can67 workspace default, group defaults, and individual overrides. Users can

68 request increases when the workspace allows it. Business follows a separate68 request increases when the workspace allows it. Business follows a separate


79 79 

80### How are access to data, systems, and user actions protected?80### How are access to data, systems, and user actions protected?

81 81 

82Work is governed by the identity, access, and permission controls already82Work mode is governed by the identity, access, and permission controls already

83established in your ChatGPT workspace. Administrators use identity management,83established in your ChatGPT workspace. Administrators use identity management,

84[RBAC](https://help.openai.com/en/articles/11750701-rbac), and workspace roles84[RBAC](https://help.openai.com/en/articles/11750701-rbac), and workspace roles

85to determine who can use Work.85to determine who can use Work mode.

86 86 

87Where supported, access can be synchronized with your identity provider through87Where supported, access can be synchronized with your identity provider through

88[SCIM](https://help.openai.com/en/articles/10011769-openai-platform-scim-integration-faq)88[SCIM](https://help.openai.com/en/articles/10011769-openai-platform-scim-integration-faq)

89and group synchronization. This lets you manage access and permissions centrally89and group synchronization. This lets you manage access and permissions centrally

90as employees join the organization, change roles, or leave.90as employees join the organization, change roles, or leave.

91 91 

92Underlying source systems continue to enforce access to enterprise data. Work92Underlying source systems continue to enforce access to enterprise data. Work mode

93respects the permissions defined in connected applications, so users and agents93respects the permissions defined in connected applications, so users and agents

94can access only files, repositories, channels, records, and actions they are94can access only files, repositories, channels, records, and actions they are

95authorized to use. Work doesn't bypass existing access controls or grant new95authorized to use. Work mode doesn't bypass existing access controls or grant new

96permissions in connected systems.96permissions in connected systems.

97 97 

98### How does Work access data and context?98<a id="how-does-work-access-data-and-context"></a>

99 99 

100Work can use the current conversation, uploaded files, workspace resources, and100### How does Work mode access data and context?

101 

102Work mode can use the current chat, uploaded files, workspace resources, and

101connected systems through plugins. Depending on enabled capabilities and103connected systems through plugins. Depending on enabled capabilities and

102permissions, this can include documents, repositories, tickets, channels,104permissions, this can include documents, repositories, tickets, channels,

103email, and calendars. Artifacts from earlier tasks or memory can be available105email, and calendars. Files from earlier chats or memory can be available

104when included in the current conversation or project, or when applicable106when included in the current chat or project, or when applicable

105workspace and user memory controls are enabled.107workspace and user memory controls are enabled.

106 108 

107Each context source keeps its own controls: users supply conversation context,109Each context source keeps its own controls: users supply chat context,

108admins manage workspace resources, and connected systems enforce authentication110admins manage workspace resources, and connected systems enforce authentication

109and permissions. Work can access only information authorized for the user or an111and permissions. Work mode can access only information authorized for the user or an

110approved shared connection.112approved shared connection.

111 113 

112Work inherits applicable ChatGPT workspace protections. Residency, retention,114Work mode inherits applicable ChatGPT workspace protections. Residency, retention,

113logging, and feature availability vary by plan, region, surface, and connected115logging, and feature availability vary by plan, region, surface, and connected

114system, so confirm coverage for your configuration.116system, so confirm coverage for your configuration.

115 117 


141 143 

142## Compliance144## Compliance

143 145 

144### How does Work support enterprise privacy and data commitments?146<a id="how-does-work-support-enterprise-privacy-and-data-commitments"></a>

147 

148### How does Work mode support enterprise privacy and data commitments?

145 149 

146Work uses the privacy, security, and data commitments applicable to the150Work mode uses the privacy, security, and data commitments applicable to the

147customer's ChatGPT workspace, subject to plan, configuration, surface, feature,151customer's ChatGPT workspace, subject to plan, configuration, surface, feature,

148and region. For ChatGPT Enterprise, this includes152and region. For ChatGPT Enterprise, this includes

149[no training on business data by default](https://help.openai.com/en/articles/8983130-what-if-i-want-to-keep-my-history-on-but-disable-model-training),153[no training on business data by default](https://help.openai.com/en/articles/8983130-what-if-i-want-to-keep-my-history-on-but-disable-model-training),


155[data and inference residency guidance](https://help.openai.com/en/articles/9903489-data-residency-and-inference-residency-for-chatgpt)159[data and inference residency guidance](https://help.openai.com/en/articles/9903489-data-residency-and-inference-residency-for-chatgpt)

156and the customer's agreement for the features and regions in use.160and the customer's agreement for the features and regions in use.

157 161 

158Connected applications have their own retention, logging, access, residency,162Connected services have their own retention, logging, access, residency, and

159and compliance requirements. When Work uses apps, repositories, or third-party163compliance requirements. When Work mode uses plugins, repositories, or third-party

160systems, evaluate both the ChatGPT workspace controls and the connected164systems, evaluate both the ChatGPT workspace controls and the connected

161system's controls.165system's controls.

162 166 


167 171 

168### What data is stored, retained, or deleted?172### What data is stored, retained, or deleted?

169 173 

170Data retention and deletion for Work are governed by the ChatGPT workspace174Data retention and deletion for Work mode are governed by the ChatGPT workspace

171plan, administrative settings, and the capabilities in use. Retention can vary175plan, administrative settings, and the capabilities in use. Retention can vary

172across the information Work accesses. Data stored by ChatGPT follows the176across the information Work mode accesses. Data stored by ChatGPT follows the

173configured workspace retention policies, while connected applications continue177configured workspace retention policies, while connected applications continue

174to manage their own data and lifecycle policies. See178to manage their own data and lifecycle policies. See

175[Chat and file retention policies](https://help.openai.com/en/articles/8983778-chat-and-file-retention-policies-in-chatgpt).179[Chat and file retention policies](https://help.openai.com/en/articles/8983778-chat-and-file-retention-policies-in-chatgpt).

176 180 

177Work can create conversation content, uploaded or generated files, artifacts,181Work mode can create chat content, uploaded or generated files, artifacts,

178and execution metadata. Codex tasks can also create repository or environment182and execution metadata. Codex chats can also create repository or environment

179metadata, command output, diffs, and logs. Check the current product and183metadata, command output, diffs, and logs. Check the current product and

180[Compliance API](https://learn.chatgpt.com/docs/enterprise/compliance-api) documentation for exact data184[Compliance API](https://learn.chatgpt.com/docs/enterprise/compliance-api) documentation for exact data

181classes, retention periods, and deletion paths.185classes, retention periods, and deletion paths.


235 239 

236Governance spans three related but separate layers:240Governance spans three related but separate layers:

237 241 

238- **Work access controls** determine who can use the personal Work agent on242- **Work mode access controls** determine who can use Work mode on

239 each surface.243 each surface.

240- **Workspace Agent controls** determine who can build, publish, share,244- **Workspace Agent controls** determine who can build, publish, share,

241 schedule, or configure reusable agents and shared connections.245 schedule, or configure reusable agents and shared connections.


245 249 

246Managed configuration constrains supported runtime behavior. It doesn't grant250Managed configuration constrains supported runtime behavior. It doesn't grant

247workspace access, replace RBAC, or revoke a user's workspace access. These251workspace access, replace RBAC, or revoke a user's workspace access. These

248layers aren't one uniform Work policy surface. Analytics and compliance logs252layers aren't one uniform Work mode policy surface. Analytics and compliance logs

249provide additional visibility within their documented product and event253provide additional visibility within their documented product and event

250scopes.254scopes.

251 255 


262 266 

263### Can access be scoped by group, role, workspace, or capability?267### Can access be scoped by group, role, workspace, or capability?

264 268 

265Yes. Work capabilities can be scoped with workspace roles, identity groups,269Yes. Work mode capabilities can be scoped with workspace roles, identity groups,

266and administrator-defined permissions. Assign capabilities to groups based on270and administrator-defined permissions. Assign capabilities to groups based on

267business need and organizational policy instead of giving every user identical271business need and organizational policy instead of giving every user identical

268access. See the272access. See the

269[RBAC guide](https://help.openai.com/en/articles/11750701-rbac) and this273[RBAC guide](https://help.openai.com/en/articles/11750701-rbac) and this

270[RBAC walkthrough](https://vimeo.com/1207482321/d1286e4467?share=copy&fl=sv&fe=ci).274[RBAC walkthrough](https://vimeo.com/1207482321/d1286e4467?share=copy&fl=sv&fe=ci).

271 275 

272Organizations can use RBAC to determine which users can access Work, manage276Organizations can use RBAC to determine which users can access Work mode, manage

273workspace settings, configure approved plugins, or build and publish Workspace277workspace settings, configure approved plugins, or build and publish Workspace

274Agents. For eligible Enterprise and Edu workspaces, monthly usage limits can278Agents. For eligible Enterprise and Edu workspaces, monthly usage limits can

275support a phased rollout through a workspace default, group defaults, and user279support a phased rollout through a workspace default, group defaults, and user

276overrides.280overrides.

277 281 

278Access to connected systems remains independently governed. Scope apps, shared282Access to connected systems remains independently governed. Scope plugins, shared

279credentials, repositories, and write-capable actions to the minimum required283credentials, repositories, and write-capable actions to the minimum required

280audience using workspace permissions, app settings, and the source system's284audience using workspace permissions, plugin settings, and the source system's

281controls. For higher-trust environments, use managed policies to restrict285controls. For higher-trust environments, use managed policies to restrict

282runtime capabilities further.286runtime capabilities further.

283 287 

284### How are runtime and network boundaries governed?288### How are runtime and network boundaries governed?

285 289 

286The security boundaries for Work depend on the task. A conversational task, a290The security boundaries for Work mode depend on the task. A chat in Chat mode, a

287connected workflow, a scheduled task, and a Codex task can run in different291connected workflow, a scheduled task, and a Codex chat can run in different

288environments with different permissions, tools, and network access.292environments with different permissions, tools, and network access.

289 293 

290Govern each execution environment through its applicable controls. Work294Govern each execution environment through its applicable controls. Work mode

291permissions on web and mobile govern access to Work and supported browser or295permissions on web and mobile govern access to Work mode and supported browser or

292network capabilities. Search, apps, plugins, Workspace Agents, and296network capabilities. Search, plugins, Workspace Agents, and

293source-system permissions remain separate controls. Desktop and Codex tasks297source-system permissions remain separate controls. Desktop and Codex chats

294follow Codex permissions, managed configuration, MCP policy, sandboxing, and298follow Codex permissions, managed configuration, MCP policy, sandboxing, and

295approval controls. These controls aren't interchangeable.299approval controls. These controls aren't interchangeable.

296 300 

297For Codex activity, local runs in the ChatGPT desktop app, CLI, and IDE execute301For Codex activity, local runs in the ChatGPT desktop app, CLI, and IDE execute

298on the user's machine with operating-system sandboxing and approval policies.302on the user's machine with operating-system sandboxing and approval policies.

299Codex cloud runs tasks in isolated OpenAI-managed environments. Enterprise303Codex cloud runs chats in isolated OpenAI-managed environments. Enterprise

300administrators can use managed requirements to constrain permission profiles,304administrators can use managed requirements to constrain permission profiles,

301approvals, filesystem and network access, MCP servers, hooks, command rules,305approvals, filesystem and network access, MCP servers, hooks, command rules,

302and other supported runtime behavior.306and other supported runtime behavior.

303 307 

304## Usage and cost308## Usage and cost

305 309 

306### How does Work usage translate into spend over time?310<a id="how-does-work-usage-translate-into-spend-over-time"></a>

311 

312### How does Work mode usage translate into spend over time?

307 313 

308[ChatGPT Work and Codex share pricing, credits, and usage limits](https://learn.chatgpt.com/docs/pricing).314[Work mode and Codex share pricing, credits, and usage limits](https://learn.chatgpt.com/docs/pricing).

309Consumption varies with the model and capability, context size, task duration,315Consumption varies with the model and capability, context size, task duration,

310tool use, and output size. Standard Chat usage is separate.316tool use, and output size. Standard Chat usage is separate.

311 317 

312The highest-variance patterns are often workflows that run frequently,318The highest-variance patterns are often workflows that run frequently,

313retrieve or process large amounts of information, call multiple tools or apps,319retrieve or process large amounts of information, call multiple tools or connectors,

314retry after failures, or produce large artifacts. Cost-sensitive examples320retry after failures, or produce large artifacts. Cost-sensitive examples

315include scheduled or recurring work, high-volume triggers, large files, broad321include scheduled or recurring work, high-volume triggers, large files, broad

316retrieval across enterprise sources, repeated app calls, and Codex tasks that322retrieval across enterprise sources, repeated connector calls, and Codex chats that

317process repositories, run commands, or use cloud environments.323process repositories, run commands, or use cloud environments.

318 324 

319Use spend controls, usage analytics, and reporting to monitor these patterns325Use spend controls, usage analytics, and reporting to monitor these patterns


359 365 

360### How can admins stop access or activity?366### How can admins stop access or activity?

361 367 

362Admins can need to stop users, apps, shared credentials, workflows, schedules,368Admins can need to stop users, plugins, shared credentials, workflows, schedules,

363or Codex credentials during user removal or incident review.369or Codex credentials during user removal or incident review.

364 370 

365Revocation paths include:371Revocation paths include:


367- Remove a user's workspace or group access. For SCIM-managed users, remove373- Remove a user's workspace or group access. For SCIM-managed users, remove

368 access at the identity provider; otherwise, a later synchronization can374 access at the identity provider; otherwise, a later synchronization can

369 provision the user again.375 provision the user again.

370- Disable or restrict the relevant app.376- Disable or restrict the relevant plugin or connector.

371- Revoke a shared connection, bot, or service account through its owning377- Revoke a shared connection, bot, or service account through its owning

372 surface. Workspace owners and admins can separately revoke Codex workspace378 surface. Workspace owners and admins can separately revoke Codex workspace

373 access tokens.379 access tokens.


394 400 

395## Recommended admin actions401## Recommended admin actions

396 402 

397- **Confirm who should have access first.** Decide whether to keep Work off,403- **Confirm who should have access first.** Decide whether to keep Work mode off,

398 run a pilot, or roll out broadly. Many organizations start with power users,404 run a pilot, or roll out broadly. Many organizations start with power users,

399 champions, or teams with clear use cases.405 champions, or teams with clear use cases.

400- **Review roles and permissions.** In **Permissions & roles**, confirm which406- **Review roles and permissions.** In **Permissions & roles**, confirm which

401 users or groups can access Work. Match access to business need, readiness,407 users or groups can access Work mode. Match access to business need, readiness,

402 and governance expectations.408 and governance expectations.

403- **Review connected apps and data sources.** Work is most useful with approved409- **Review plugins and data sources.** Work mode is most useful with approved

404 business context such as files, email, calendars, Slack, or CRM. Review410 business context such as files, email, calendars, Slack, or CRM. Review

405 enabled apps, their audiences, and whether app policies still match how users411 enabled plugins, their audiences, and whether connector policies still match how users

406 should delegate work.412 should delegate work.

407- **Set expectations for appropriate use cases.** Position Work for multi-step,413- **Set expectations for appropriate use cases.** Position Work mode for multi-step,

408 higher-value tasks such as research, synthesis, analysis, file creation,414 higher-value tasks such as research, synthesis, analysis, file creation,

409 workflow updates, and reusable outputs. Use Chat for quick questions,415 workflow updates, and reusable outputs. Use Chat mode for quick questions,

410 light rewrites, or brainstorming.416 light rewrites, or brainstorming.

411- **Review credit and usage controls.** Because Work can perform longer-running417- **Review credit and usage controls.** Because Work mode can perform longer-running

412 tasks, it can use more credits than a standard Chat conversation. Review418 tasks, it can use more credits than a standard chat in Chat mode. Review

413 defaults, group defaults, user overrides, and internal guidance about419 defaults, group defaults, user overrides, and internal guidance about

414 matching effort to business value.420 matching effort to business value.

415- **Identify your first high-value workflows.** Start with clear, reviewable421- **Identify your first high-value workflows.** Start with clear, reviewable

Details

1# Cloud environments1# Cloud environments

2 2 

3Use environments to control what Codex installs and runs during cloud tasks. For example, you can add dependencies, install tools like linters and formatters, and set environment variables.3Use environments to control what Codex installs and runs during cloud chats. For example, you can add dependencies, install tools like linters and formatters, and set environment variables.

4 4 

5Configure environments in [Codex settings](https://chatgpt.com/codex/settings/environments).5Configure environments in [Codex settings](https://chatgpt.com/codex/settings/environments).

6 6 

7## How Codex cloud tasks run7<a id="how-codex-cloud-tasks-run"></a>

8 8 

9Here's what happens when you submit a task:9## How Codex cloud chats run

10 

11Here's what happens when you submit a prompt:

10 12 

111. Codex creates a container and checks out your repo at the selected branch or commit SHA.131. Codex creates a container and checks out your repo at the selected branch or commit SHA.

122. Codex runs your setup script, plus an optional maintenance script when a cached container is resumed.142. Codex runs your setup script, plus an optional maintenance script when a cached container is resumed.


28 30 

29## Environment variables and secrets31## Environment variables and secrets

30 32 

31**Environment variables** are set for the full duration of the task (including setup scripts and the agent phase).33**Environment variables** are set for the full duration of the chat (including setup scripts and the agent phase).

32 34 

33**Secrets** are similar to environment variables, except:35**Secrets** are similar to environment variables, except:

34 36 


58 60 

59## Container caching61## Container caching

60 62 

61Codex caches container state for up to 12 hours to speed up new tasks and follow-ups.63Codex caches container state for up to 12 hours to speed up new chats and follow-ups.

62 64 

63When an environment is cached:65When an environment is cached:

64 66 


67 69 

68When a cached container is resumed:70When a cached container is resumed:

69 71 

70- Codex checks out the branch specified for the task.72- Codex checks out the branch specified for the chat.

71- Codex runs the maintenance script (optional). This is useful when the setup script ran on an older commit and dependencies need to be updated.73- Codex runs the maintenance script (optional). This is useful when the setup script ran on an older commit and dependencies need to be updated.

72 74 

73Codex automatically invalidates the cache if you change the setup script, maintenance script, environment variables, or secrets. If your repo changes in a way that makes the cached state incompatible, select **Reset cache** on the environment page.75Codex automatically invalidates the cache if you change the setup script, maintenance script, environment variables, or secrets. If your repo changes in a way that makes the cached state incompatible, select **Reset cache** on the environment page.

Details

1# Worktrees1# Worktrees

2 2 

3In the ChatGPT desktop app, worktrees let Codex run multiple independent tasks in the same project without interfering with each other. For Git repositories, [scheduled tasks](https://learn.chatgpt.com/docs/automations) can run on dedicated background worktrees so they don't conflict with your ongoing work. In non-version-controlled projects, scheduled tasks run directly in the project directory. You can also start tasks in a worktree manually and use Handoff to move a task between Local and Worktree.3In the ChatGPT desktop app, worktrees let Codex run multiple independent chats in the same project without interfering with each other. For Git repositories, [scheduled tasks](https://learn.chatgpt.com/docs/automations) can run on dedicated background worktrees so they don't conflict with your ongoing work. In non-version-controlled projects, scheduled tasks run directly in the project directory. You can also start chats in a worktree manually and use Handoff to move a chat between Local and Worktree.

4 4 

5Worktrees are available only in Codex in the ChatGPT desktop app. Select5Worktrees are available only in Codex in the ChatGPT desktop app. Select

6 **Codex** before you start a task in a worktree.6 **Codex** before you start a chat in a worktree.

7 7 

8## What's a worktree8## What's a worktree

9 9 


13 13 

14- **Local checkout**: The repository that you created. Sometimes just referred to as **Local** in the ChatGPT desktop app.14- **Local checkout**: The repository that you created. Sometimes just referred to as **Local** in the ChatGPT desktop app.

15- **Worktree**: A [Git worktree](https://git-scm.com/docs/git-worktree) that was created from your local checkout in the ChatGPT desktop app.15- **Worktree**: A [Git worktree](https://git-scm.com/docs/git-worktree) that was created from your local checkout in the ChatGPT desktop app.

16- **Handoff**: The flow that moves a task between Local and Worktree. Codex handles the Git operations required to move your work safely between them.16- **Handoff**: The flow that moves a chat between Local and Worktree. Codex handles the Git operations required to move your work safely between them.

17 17 

18## Why use a worktree18## Why use a worktree

19 19 

201. Work in parallel with Codex without disturbing your current Local setup.201. Work in parallel with Codex without disturbing your current Local setup.

212. Queue up background work while you stay focused on the foreground.212. Queue up background work while you stay focused on the foreground.

223. Move a task into Local later when you're ready to inspect, test, or collaborate more directly.223. Move a chat into Local later when you're ready to inspect, test, or collaborate more directly.

23 23 

24## Getting started24## Getting started

25 25 


29 29 

301. Select "Worktree"301. Select "Worktree"

31 31 

32 In the new task view, select **Worktree** under the composer.32 In the new chat view, select **Worktree** under the composer.

33 Optionally, choose a [local environment](https://learn.chatgpt.com/docs/environments/local-environment) to run setup scripts for the worktree.33 Optionally, choose a [local environment](https://learn.chatgpt.com/docs/environments/local-environment) to run setup scripts for the worktree.

34 34 

352. Select the starting branch352. Select the starting branch


42 42 

434. Choose where to keep working434. Choose where to keep working

44 44 

45 When you're ready, you can either keep working directly on the worktree or hand the task off to your local checkout. Handing off to or from Local moves your task _and_ code so you can continue in the other checkout.45 When you're ready, you can either keep working directly on the worktree or hand the chat off to your local checkout. Handing off to or from Local moves your chat _and_ code so you can continue in the other checkout.

46 46 

47</WorkflowSteps>47</WorkflowSteps>

48 48 

49## Working between Local and Worktree49## Working between Local and Worktree

50 50 

51Worktrees look and feel much like your local checkout. The difference is where they fit into your flow. You can think of Local as the foreground and Worktree as the background. Handoff lets you move a task between them.51Worktrees look and feel much like your local checkout. The difference is where they fit into your flow. You can think of Local as the foreground and Worktree as the background. Handoff lets you move a chat between them.

52 52 

53Under the hood, Handoff handles the Git operations required to move work between two checkouts safely. This matters because **Git only allows a branch to be checked out in one place at a time**. If you check out a branch on a worktree, you **can't** check it out in your local checkout at the same time, and vice versa.53Under the hood, Handoff handles the Git operations required to move work between two checkouts safely. This matters because **Git only allows a branch to be checked out in one place at a time**. If you check out a branch on a worktree, you **can't** check it out in your local checkout at the same time, and vice versa.

54 54 

55In practice, there are two common paths:55In practice, there are two common paths:

56 56 

571. [Work exclusively on the worktree](#option-1-working-on-the-worktree). This path works best when you can verify changes directly on the worktree, for example because you have dependencies and tools installed using a [local environment setup script](https://learn.chatgpt.com/docs/environments/local-environment).571. [Work exclusively on the worktree](#option-1-working-on-the-worktree). This path works best when you can verify changes directly on the worktree, for example because you have dependencies and tools installed using a [local environment setup script](https://learn.chatgpt.com/docs/environments/local-environment).

582. [Hand the task off to Local](#option-2-handing-a-task-off-to-local). Use this when you want to bring the task into the foreground, for example because you want to inspect changes in your usual IDE or can run only one instance of your app.582. [Hand the chat off to Local](#option-2-handing-a-chat-off-to-local). Use this when you want to bring the chat into the foreground, for example because you want to inspect changes in your usual IDE or can run only one instance of your app.

59 59 

60### Option 1: Working on the worktree60### Option 1: Working on the worktree

61 61 


63 63 

64<div>64<div>

65 65 

66If you want to stay exclusively on the worktree with your changes, turn your worktree into a branch using the **Create branch here** button in the task header.66If you want to stay exclusively on the worktree with your changes, turn your worktree into a branch using the **Create branch here** button in the chat header.

67 67 

68From here you can commit your changes, push your branch to your remote repository, and open a pull request on GitHub.68From here you can commit your changes, push your branch to your remote repository, and open a pull request on GitHub.

69 69 


72</div>72</div>

73 73 

74<CodexScreenshot74<CodexScreenshot

75 alt="Worktree task view with branch controls and worktree details"75 alt="Worktree chat view with branch controls and worktree details"

76 lightSrc="/images/codex/app/worktree-light.webp"76 lightSrc="/images/codex/app/worktree-light.webp"

77 darkSrc="/images/codex/app/worktree-dark.webp"77 darkSrc="/images/codex/app/worktree-dark.webp"

78 maxHeight="400px"78 maxHeight="400px"


85 85 

86<a id="option-2-handing-a-thread-off-to-local"></a>86<a id="option-2-handing-a-thread-off-to-local"></a>

87<a id="option-2-handing-a-chat-off-to-local"></a>87<a id="option-2-handing-a-chat-off-to-local"></a>

88<a id="option-2-handing-a-task-off-to-local"></a>

88 89 

89### Option 2: Handing a task off to Local90### Option 2: Handing a chat off to Local

90 91 

91<div class="feature-grid">92<div class="feature-grid">

92 93 

93<div>94<div>

94 95 

95If you want to bring a task into the foreground, select **Hand off** in the task header and move it to **Local**.96If you want to bring a chat into the foreground, select **Hand off** in the chat header and move it to **Local**.

96 97 

97This path works well when you want to read the changes in your usual IDE window, run your existing development server, or validate the work in the same environment you already use day to day.98This path works well when you want to read the changes in your usual IDE window, run your existing development server, or validate the work in the same environment you already use day to day.

98 99 

99Codex handles the Git steps required to move the task safely between the worktree and your local checkout.100Codex handles the Git steps required to move the chat safely between the worktree and your local checkout.

100 101 

101Each task keeps the same associated worktree over time. If you hand the task back to a worktree later, Codex returns it to that same background environment so you can pick up where you left off.102Each chat keeps the same associated worktree over time. If you hand the chat back to a worktree later, Codex returns it to that same background environment so you can pick up where you left off.

102 103 

103</div>104</div>

104 105 

105<CodexScreenshot106<CodexScreenshot

106 alt="Handoff dialog moving a task from a worktree to Local"107 alt="Handoff dialog moving a chat from a worktree to Local"

107 lightSrc="/images/codex/app/handoff-light.webp"108 lightSrc="/images/codex/app/handoff-light.webp"

108 darkSrc="/images/codex/app/handoff-dark.webp"109 darkSrc="/images/codex/app/handoff-dark.webp"

109 maxHeight="400px"110 maxHeight="400px"


112 113 

113</div>114</div>

114 115 

115You can also go the other direction. If you're already working in Local and want to free up the foreground, use **Hand off** to move the task to a worktree. This is useful when you want Codex to keep working in the background while you switch your attention back to something else locally.116You can also go the other direction. If you're already working in Local and want to free up the foreground, use **Hand off** to move the chat to a worktree. This is useful when you want Codex to keep working in the background while you switch your attention back to something else locally.

116 117 

117Since Handoff uses Git operations, any files that are part of your `.gitignore` file won't move with the task unless Codex copies them into a local managed worktree with `.worktreeinclude`.118Since Handoff uses Git operations, any files that are part of your `.gitignore` file won't move with the chat unless Codex copies them into a local managed worktree with `.worktreeinclude`.

118 119 

119## Advanced details120## Advanced details

120 121 

121### Codex-managed and permanent worktrees122### Codex-managed and permanent worktrees

122 123 

123By default, tasks use a Codex-managed worktree. These are meant to feel lightweight and disposable. A Codex-managed worktree is typically dedicated to one task, and Codex returns that task to the same worktree if you hand it back there later.124By default, chats use a Codex-managed worktree. These are meant to feel lightweight and disposable. A Codex-managed worktree is typically dedicated to one chat, and Codex returns that chat to the same worktree if you hand it back there later.

124 125 

125If you want a long-lived environment, create a permanent worktree from the three-dot menu on a project in the sidebar. This creates a new permanent worktree as its own project. Permanent worktrees aren't automatically deleted, and you can start multiple tasks from the same worktree.126If you want a long-lived environment, create a permanent worktree from the three-dot menu on a project in the sidebar. This creates a new permanent worktree as its own project. Permanent worktrees aren't automatically deleted, and you can start multiple chats from the same worktree.

126 127 

127### How Codex manages worktrees for you128### How Codex manages worktrees for you

128 129 

129Codex creates worktrees in `$CODEX_HOME/worktrees`. The starting commit is the `HEAD` commit of the branch selected when you start your task. If you chose a branch with local changes, Codex applies the uncommitted changes to the worktree as well. The worktree isn't checked out as a branch. It's in a [detached HEAD](https://git-scm.com/docs/git-checkout#_detached_head) state. This lets Codex create several worktrees without polluting your branches.130Codex creates worktrees in `$CODEX_HOME/worktrees`. The starting commit is the `HEAD` commit of the branch selected when you start your chat. If you chose a branch with local changes, Codex applies the uncommitted changes to the worktree as well. The worktree isn't checked out as a branch. It's in a [detached HEAD](https://git-scm.com/docs/git-checkout#_detached_head) state. This lets Codex create several worktrees without polluting your branches.

130 131 

131### Copy ignored local files into managed worktrees132### Copy ignored local files into managed worktrees

132 133 


155 156 

156To resolve this, you would need to check out another branch instead of `feature/a` on the worktree.157To resolve this, you would need to check out another branch instead of `feature/a` on the worktree.

157 158 

158If you plan on checking out the branch locally, use Handoff to move the task into Local instead of trying to keep the same branch checked out in both places at once.159If you plan on checking out the branch locally, use Handoff to move the chat into Local instead of trying to keep the same branch checked out in both places at once.

159 160 

160<ToggleSection title="Why this limitation exists">161<ToggleSection title="Why this limitation exists">

161Git prevents the same branch from being checked out in more than one worktree at a time because a branch represents a single mutable reference (`refs/heads/<name>`) whose meaning is “the current checked-out state” of a working tree.162Git prevents the same branch from being checked out in more than one worktree at a time because a branch represents a single mutable reference (`refs/heads/<name>`) whose meaning is “the current checked-out state” of a working tree.


174 175 

175Codex tries to avoid deleting worktrees that are still important. Codex-managed worktrees won't be deleted automatically if:176Codex tries to avoid deleting worktrees that are still important. Codex-managed worktrees won't be deleted automatically if:

176 177 

177- A pinned conversation is tied to it178- A pinned chat is tied to it

178- The task is still in progress179- The chat is still in progress

179- The worktree is a permanent worktree180- The worktree is a permanent worktree

180 181 

181Codex-managed worktrees are deleted automatically when:182Codex-managed worktrees are deleted automatically when:

182 183 

183- You archive the associated task184- You archive the associated chat

184- Codex needs to delete older worktrees to stay within your configured limit185- Codex needs to delete older worktrees to stay within your configured limit

185 186 

186Before deleting a Codex-managed worktree, Codex saves a snapshot of the work on it. If you open a conversation after its worktree was deleted, you'll see the option to restore it.187Before deleting a Codex-managed worktree, Codex saves a snapshot of the work on it. If you open a chat after its worktree was deleted, you'll see the option to restore it.

187 188 

188## Frequently asked questions189## Frequently asked questions

189 190 


195 196 

196<a id="can-i-move-a-chat-between-local-and-worktree"></a>197<a id="can-i-move-a-chat-between-local-and-worktree"></a>

197 198 

198<ToggleSection title="Can I move a task between Local and Worktree?">199<ToggleSection title="Can I move a chat between Local and Worktree?">

199 Yes. Use **Hand off** in the task header to move a task between your local200 Yes. Use **Hand off** in the chat header to move a chat between your local

200 checkout and a worktree. Codex handles the Git operations needed to move the201 checkout and a worktree. Codex handles the Git operations needed to move the

201 task safely between environments. If you hand a task back to a worktree later,202 chat safely between environments. If you hand a chat back to a worktree later,

202 Codex returns it to the same associated worktree.203 Codex returns it to the same associated worktree.

203</ToggleSection>204</ToggleSection>

204 205 

205<a id="what-happens-to-chats-if-a-worktree-is-deleted"></a>206<a id="what-happens-to-chats-if-a-worktree-is-deleted"></a>

206 207 

207<ToggleSection title="What happens to tasks if a worktree is deleted?">208<ToggleSection title="What happens to chats if a worktree is deleted?">

208 Tasks can remain in your history even if the underlying worktree directory is209 Chats can remain in your history even if the underlying worktree directory is

209 deleted. For Codex-managed worktrees, Codex saves a snapshot before deleting210 deleted. For Codex-managed worktrees, Codex saves a snapshot before deleting

210 the worktree and offers to restore it if you reopen the associated task.211 the worktree and offers to restore it if you reopen the associated chat.

211 Permanent worktrees are not automatically deleted when you archive their212 Permanent worktrees are not automatically deleted when you archive their

212 tasks.213 chats.

213</ToggleSection>214</ToggleSection>

Details

13 13 

14## Setup scripts14## Setup scripts

15 15 

16Since worktrees run in different directories than your local tasks, your project might not be fully set up and might be missing dependencies or files that aren't checked into your repository. Setup scripts run automatically when Codex creates a new worktree at the start of a new task.16Since worktrees run in different directories than your local chats, your project might not be fully set up and might be missing dependencies or files that aren't checked into your repository. Setup scripts run automatically when Codex creates a new worktree at the start of a new chat.

17 17 

18Use this script to run any command required to configure your environment, such as installing dependencies or running a build process.18Use this script to run any command required to configure your environment, such as installing dependencies or running a build process.

19 19 

Details

1# Codex environments1# Codex environments

2 2 

3In the ChatGPT desktop app, open the ChatGPT dropdown and select **Codex**.3In the ChatGPT desktop app, open the ChatGPT dropdown and select **Codex**.

4When starting a Codex task, choose where it runs:4When starting a Codex chat, choose where it runs:

5 5 

6- **Local**: work directly in your current project directory.6- **Local**: work directly in your current project directory.

7- **Worktree**: isolate changes in a Git worktree. [Learn more](https://learn.chatgpt.com/docs/environments/git-worktrees).7- **Worktree**: isolate changes in a Git worktree. [Learn more](https://learn.chatgpt.com/docs/environments/git-worktrees).

8- **Cloud**: run remotely in a configured cloud environment.8- **Cloud**: run remotely in a configured cloud environment.

9 9 

10Both **Local** and **Worktree** tasks run on your computer.10Both **Local** and **Worktree** chats run on your computer.

11 11 

12For the full glossary and concepts, explore the [concepts section](https://learn.chatgpt.com/docs/prompting).12For the full glossary and concepts, explore the [concepts section](https://learn.chatgpt.com/docs/prompting).

13 13 

14<CodexScreenshot14<CodexScreenshot

15 alt="New task composer with Local, Worktree, and Cloud environment options"15 alt="New chat composer with Local, Worktree, and Cloud environment options"

16 lightSrc="/images/codex/app/modes-light.webp"16 lightSrc="/images/codex/app/modes-light.webp"

17 darkSrc="/images/codex/app/modes-dark.webp"17 darkSrc="/images/codex/app/modes-dark.webp"

18 maxHeight="400px"18 maxHeight="400px"

Details

22 22 

23<WorkflowSteps>23<WorkflowSteps>

24 24 

251. In the ChatGPT desktop app, select ChatGPT Work or Codex and open **Plugins**.251. In the ChatGPT desktop app, select ChatGPT and switch to Work mode, or select Codex. Then open **Plugins**.

262. Open the **+** menu.262. Open the **+** menu.

273. Select **Record a skill**.273. Select **Record a skill**.

284. Review the suggested prompt, give Codex any helpful context, and submit it.284. Review the suggested prompt, give Codex any helpful context, and submit it.


45 45 

46## Replay the workflow46## Replay the workflow

47 47 

48Start a new task and ask Codex to use the generated skill. Give it the48Start a new chat and ask Codex to use the generated skill. Give it the

49values that are different this time, such as the file to upload, the issue to49values that are different this time, such as the file to upload, the issue to

50create, or the date range for the report.50create, or the date range for the report.

51 51 

features.md +7 −7

Details

3<CodexDocsOverviewLanding3<CodexDocsOverviewLanding

4 title="Features"4 title="Features"

5 description="Explore workflows, capabilities, commands, and settings for working in ChatGPT."5 description="Explore workflows, capabilities, commands, and settings for working in ChatGPT."

6 intro="ChatGPT brings projects and long-running tasks together with web browsing, files, images, and plugins. Commands, settings, and troubleshooting references round out these workflows, from choosing the right workflow to giving each task the context and tools it needs."6 intro="ChatGPT brings projects and long-running chats together with web browsing, files, images, and plugins. Commands, settings, and troubleshooting references round out these workflows, from choosing the right workflow to giving each chat the context and tools it needs."

7 primaryCta={{7 primaryCta={{

8 label: "Explore projects and tasks",8 label: "Explore projects and chats",

9 href: "/codex/projects",9 href: "/codex/projects",

10 }}10 }}

11 hero={{11 hero={{

12 illustration: "features-menu",12 illustration: "features-menu",

13 backgroundImage: "/images/codex/codex-wallpaper-1.webp",13 backgroundImage: "/images/codex/codex-wallpaper-1.webp",

14 alt: "Codex sidebar and Add menu for tasks, plugins, and content tools",14 alt: "Codex sidebar and Add menu for chats, plugins, and content tools",

15 }}15 }}

16 sections={[16 sections={[

17 {17 {


19 description: "Ways to organize, delegate, and review work.",19 description: "Ways to organize, delegate, and review work.",

20 pages: [20 pages: [

21 {21 {

22 title: "Projects, chats, and tasks",22 title: "Projects and chats",

23 description: "Keep related chats, tasks, context, and work together.",23 description: "Keep related chats, context, and work together.",

24 href: "/codex/projects",24 href: "/codex/projects",

25 icon: "folder",25 icon: "folder",

26 },26 },


59 },59 },

60 {60 {

61 title: "Pets",61 title: "Pets",

62 description: "Choose an animated companion and follow task activity.",62 description: "Choose an animated companion and follow chat activity.",

63 href: "/codex/pets",63 href: "/codex/pets",

64 icon: "customize",64 icon: "customize",

65 },65 },

66 {66 {

67 title: "Codex Micro",67 title: "Codex Micro",

68 description:68 description:

69 "Monitor and control ChatGPT tasks from a Work Louder keyboard.",69 "Monitor and control ChatGPT chats from a Work Louder keyboard.",

70 href: "/codex/features/codex-micro",70 href: "/codex/features/codex-micro",

71 icon: "key",71 icon: "key",

72 },72 },

Details

4 <div class="min-w-0 [&_p]:!mt-0">4 <div class="min-w-0 [&_p]:!mt-0">

5 5 

6Codex Micro is a limited-run collaboration between Codex and Work Louder. It6Codex Micro is a limited-run collaboration between Codex and Work Louder. It

7works with the ChatGPT desktop app, giving you a quick way to check on tasks,7works with the ChatGPT desktop app, giving you a quick way to check on chats,

8jump between them, use push-to-talk, and trigger common actions or skills8jump between them, use push-to-talk, and trigger common actions or skills

9without leaving the keyboard.9without leaving the keyboard.

10 10 


25 follow the setup that appears when ChatGPT detects it.25 follow the setup that appears when ChatGPT detects it.

263. On macOS, allow **Input Monitoring** when prompted so ChatGPT can respond to263. On macOS, allow **Input Monitoring** when prompted so ChatGPT can respond to

27 key presses.27 key presses.

284. Open **Settings > Codex Micro** to choose which tasks the Agent Keys follow,284. Open **Settings > Codex Micro** to choose which chats the Agent Keys follow,

29 assign actions to the Command Keys and analog directions, and adjust the29 assign actions to the Command Keys and analog directions, and adjust the

30 lighting.30 lighting.

31 31 


36first time. If you want to use the device outside ChatGPT, customize those36first time. If you want to use the device outside ChatGPT, customize those

37controls with [Work Louder Input](https://worklouder.cc/micro-setup).37controls with [Work Louder Input](https://worklouder.cc/micro-setup).

38 38 

39## Read and switch tasks with Agent Keys39<a id="read-and-switch-tasks-with-agent-keys"></a>

40 40 

41Each of the six frosted Agent Keys can follow a task and light up to show its41## Read and switch chats with Agent Keys

42current status. Press an Agent Key once to switch to that task without bringing42 

43ChatGPT forward. Press it twice within 350 milliseconds to switch tasks and43Each of the six frosted Agent Keys can follow a chat and light up to show its

44current status. Press an Agent Key once to switch to that chat without bringing

45ChatGPT forward. Press it twice within 350 milliseconds to switch chats and

44bring the ChatGPT window forward.46bring the ChatGPT window forward.

45 47 

46| Light | Status | Meaning |48| Light | Status | Meaning |

47| ----- | ---------------- | ----------------------------------------- |49| ----- | ---------------- | ----------------------------------------- |

48| White | Idle | The task is idle. |50| White | Idle | The chat is idle. |

49| Blue | Thinking | ChatGPT is working. |51| Blue | Thinking | ChatGPT is working. |

50| Green | Complete | The task completed with an unread update. |52| Green | Complete | The chat completed with an unread update. |

51| Amber | Requires input | ChatGPT needs your approval or response. |53| Amber | Requires input | ChatGPT needs your approval or response. |

52| Red | Error | Something went wrong. |54| Red | Error | Something went wrong. |

53| Off | No assigned task | The key doesn't follow a task. |55| Off | No assigned chat | The key doesn't follow a chat. |

54 56 

55The selected task's key pulses with its status light.57The selected chat's key pulses with its status light.

56 58 

57Out of the box, the keys follow your six most recently updated tasks, whether59Out of the box, the keys follow your six most recently updated chats, whether

58or not they're pinned. You can change **Agent source** in **Settings > Codex60or not they're pinned. You can change **Agent source** in **Settings > Codex

59Micro** to use a different arrangement:61Micro** to use a different arrangement:

60 62 

61- **Most recent tasks**: Follow the six most recently updated tasks, pinned or63- **Most recent chats**: Follow the six most recently updated chats, pinned or

62 unpinned.64 unpinned.

63- **Pinned tasks**: Follow the first six tasks in **Pinned**.65- **Pinned chats**: Follow the first six chats in **Pinned**.

64- **Priority tasks**: Put tasks waiting for input, unread tasks, and active66- **Priority chats**: Put chats waiting for input, unread chats, and active

65 tasks first.67 chats first.

66- **Custom assignments**: Choose the task assigned to each Agent Key. Press an68- **Custom assignments**: Choose the chat assigned to each Agent Key. Press an

67 unassigned Agent Key to open a new task. When you start the task, ChatGPT69 unassigned Agent Key to open a new chat. When you start the chat, ChatGPT

68 assigns it to that key.70 assigns it to that key.

69 71 

70The status colors stay the same. You can decide which tasks the Agent Keys72The status colors stay the same. You can decide which chats the Agent Keys

71follow, but you can't turn them into extra Command Keys.73follow, but you can't turn them into extra Command Keys.

72 74 

73## Use and customize Command Keys75## Use and customize Command Keys


82| <CodexMicroTableKeycap keycapId="FAST" label="Fast" /> | Turn Fast mode on or off. |84| <CodexMicroTableKeycap keycapId="FAST" label="Fast" /> | Turn Fast mode on or off. |

83| <CodexMicroTableKeycap keycapId="APPR" label="Approve" /> | Approve the current request. |85| <CodexMicroTableKeycap keycapId="APPR" label="Approve" /> | Approve the current request. |

84| <CodexMicroTableKeycap keycapId="REJ" label="Decline" /> | Decline the current request. |86| <CodexMicroTableKeycap keycapId="REJ" label="Decline" /> | Decline the current request. |

85| <CodexMicroTableKeycap keycapId="SPLIT" label="Fork" /> | Continue the current task in a new task. |87| <CodexMicroTableKeycap keycapId="SPLIT" label="Fork" /> | Continue the current chat in a new chat. |

86| <CodexMicroTableKeycap keycapId="MIC" label="Mic" /> | Start push-to-talk. |88| <CodexMicroTableKeycap keycapId="MIC" label="Mic" /> | Start push-to-talk. |

87| <CodexMicroTableKeycap keycapId="CODEX" label="Codex" /> | Send the message in the composer. |89| <CodexMicroTableKeycap keycapId="CODEX" label="Codex" /> | Send the message in the composer. |

88 90 

Details

1# Get started with Work1# Get started with Work mode

2 2 

3<VideoPlayer src="https://cdn.openai.com/devhub/superapp-video-v1.mp4" />3<VideoPlayer src="https://cdn.openai.com/devhub/superapp-video-v1.mp4" />

4 4 

5## Introducing ChatGPT Work5<a id="introducing-chatgpt-work"></a>

6 6 

7Work is a way to delegate real work to ChatGPT.7## Introducing Work mode

8 8 

9Use Chat when you want an answer, explanation, brainstorm, or short draft. Use9Work mode is a way to delegate real work to ChatGPT.

10Work when you want ChatGPT to complete a task with a clear outcome, such as a10 

11Use Chat mode when you want an answer, explanation, brainstorm, or short draft.

12Use Work mode when you want ChatGPT to complete a task with a clear outcome, such as a

11brief, deck, analysis, recurring update, workflow, or file you can review and13brief, deck, analysis, recurring update, workflow, or file you can review and

12use. Learn more about [using Chat and Work together](https://learn.chatgpt.com/docs/use-chatgpt).14use. Learn more about [using Chat mode and Work mode together](https://learn.chatgpt.com/docs/use-chatgpt).

13 15 

14Work can use your files, plugins, and approved tools to retrieve information,16Work mode can use your files, plugins, and approved tools to retrieve information,

15create deliverables, run workflows, and complete work that is ready for you to17create deliverables, run workflows, and complete work that is ready for you to

16review. You can follow progress, answer questions, change direction, and18review. You can follow progress, answer questions, change direction, and

17approve important actions.19approve important actions.

18 20 

19On the [desktop app](https://learn.chatgpt.com/docs/app), Work can also use local files, apps, and the21On the [desktop app](https://learn.chatgpt.com/docs/app), Work mode can also use local files, apps, and the

20browser when those tools are available.22browser when those tools are available.

21 23 

22If you have used Codex for non-coding work, you can stay in Codex or switch to24If you have used Codex for non-coding work, you can stay in Codex or switch to

23Work. Work gives you the same core capabilities with an experience designed25Work mode. Work mode gives you the same core capabilities with an experience designed

24for everyday work.26for everyday work.

25 27 

26## What to try first28## What to try first

27 29 

28<VideoPlayer src="https://cdn.openai.com/devhub/videos-learn/selectnoonboarding.mp4" />30<VideoPlayer src="https://cdn.openai.com/devhub/videos-learn/selectnoonboarding.mp4" />

29 31 

30First, make sure you have Work selected in ChatGPT. Then choose your first Work32First, make sure you have Work selected in ChatGPT. Then choose your first

31task. Good tasks have a clear outcome, a few source materials, and an output33task. Good tasks have a clear outcome, a few source materials, and an output

32you can review.34you can review.

33 35 


35 37 

36### Create a presentation38### Create a presentation

37 39 

38Use Work to turn notes, docs, research, or meeting materials into a structured40Use Work mode to turn notes, docs, research, or meeting materials into a structured

39deck.41deck.

40 42 

41<CodexScreenshot43<CodexScreenshot

42 alt="A presentation created in ChatGPT Work"44 alt="A presentation created in Work mode in ChatGPT"

43 lightSrc="/codex/get-started-with-work/create-presentation.webp"45 lightSrc="/codex/get-started-with-work/create-presentation.webp"

44 darkSrc="/codex/get-started-with-work/create-presentation.webp"46 darkSrc="/codex/get-started-with-work/create-presentation.webp"

45 maxHeight={520}47 maxHeight={520}


55 57 

56### Create a comparison spreadsheet58### Create a comparison spreadsheet

57 59 

58Use Work to turn notes, files, or research into a spreadsheet that compares60Use Work mode to turn notes, files, or research into a spreadsheet that compares

59options and helps you make a decision.61options and helps you make a decision.

60 62 

61<CodexScreenshot63<CodexScreenshot

62 alt="A comparison spreadsheet created in ChatGPT Work"64 alt="A comparison spreadsheet created in Work mode in ChatGPT"

63 lightSrc="/codex/get-started-with-work/comparison-spreadsheet.webp"65 lightSrc="/codex/get-started-with-work/comparison-spreadsheet.webp"

64 darkSrc="/codex/get-started-with-work/comparison-spreadsheet.webp"66 darkSrc="/codex/get-started-with-work/comparison-spreadsheet.webp"

65 maxHeight={520}67 maxHeight={520}


75 77 

76### Set up a recurring update78### Set up a recurring update

77 79 

78Use scheduled tasks when you want Work to repeat, monitor, or refresh something80Use scheduled tasks when you want Work mode to repeat, monitor, or refresh something

79over time.81over time.

80 82 

81<CodexScreenshot83<CodexScreenshot

82 alt="A recurring update scheduled in ChatGPT Work"84 alt="A recurring update scheduled in Work mode in ChatGPT"

83 lightSrc="/codex/get-started-with-work/recurring-update.webp"85 lightSrc="/codex/get-started-with-work/recurring-update.webp"

84 darkSrc="/codex/get-started-with-work/recurring-update.webp"86 darkSrc="/codex/get-started-with-work/recurring-update.webp"

85 maxHeight={520}87 maxHeight={520}


95 97 

96Learn more about [scheduled tasks](https://learn.chatgpt.com/docs/automations?surface=app).98Learn more about [scheduled tasks](https://learn.chatgpt.com/docs/automations?surface=app).

97 99 

98## Best practices for using Work100<a id="best-practices-for-using-work"></a>

101 

102## Best practices for using Work mode

99 103 

100Use Work when you want ChatGPT to complete a task, create a file, or manage work104Use Work mode when you want ChatGPT to complete a task, create a file, or manage work

101over time. It is a good fit for tasks that:105over time. It is a good fit for tasks that:

102 106 

103- Use multiple sources, plugins, tools, or steps.107- Use multiple sources, plugins, tools, or steps.


105- Produce an output you will review, edit, or reuse.109- Produce an output you will review, edit, or reuse.

106- Need to be repeated, monitored, or updated over time.110- Need to be repeated, monitored, or updated over time.

107 111 

108To get a better result, tell Work the outcome you need, the sources or plugins112To get a better result, tell ChatGPT the outcome you need, the sources or plugins

109to use, any constraints to follow, what good looks like, and when to stop for113to use, any constraints to follow, what good looks like, and when to stop for

110review or approval.114review or approval.

111 115 


118 prompt={`Review the attached interview notes and survey results. Create an eight-slide presentation for the product leadership meeting. Focus on the three most common customer problems, include supporting evidence, separate findings from recommendations, and flag any claims that are not well supported. Use @Google Drive for the source docs. Return a draft for my review before treating it as final.`}122 prompt={`Review the attached interview notes and survey results. Create an eight-slide presentation for the product leadership meeting. Focus on the three most common customer problems, include supporting evidence, separate findings from recommendations, and flag any claims that are not well supported. Use @Google Drive for the source docs. Return a draft for my review before treating it as final.`}

119/>123/>

120 124 

121Learn more about [prompting for Work](https://learn.chatgpt.com/docs/prompting#prompting-for-work).125Learn more about [prompting for Work mode](https://learn.chatgpt.com/docs/prompting#prompting-for-work).

122 126 

123## Add plugins for more context and better outputs127## Add plugins for more context and better outputs

124 128 

125<CodexScreenshot129<CodexScreenshot

126 alt="The plugins library in ChatGPT Work"130 alt="The plugins library in Work mode in ChatGPT"

127 lightSrc="/codex/get-started-with-work/plugins.webp"131 lightSrc="/codex/get-started-with-work/plugins.webp"

128 darkSrc="/codex/get-started-with-work/plugins.webp"132 darkSrc="/codex/get-started-with-work/plugins.webp"

129 maxHeight={520}133 maxHeight={520}

130 class="my-6 p-4 md:p-8"134 class="my-6 p-4 md:p-8"

131/>135/>

132 136 

133Plugins connect Work to tools your team uses, like Slack, Google Drive,137Plugins connect Work mode to tools your team uses, like Slack, Google Drive,

134SharePoint, email, calendars, CRMs, and project trackers.138SharePoint, email, calendars, CRMs, and project trackers.

135 139 

136- Select **Plugins** in the left sidebar to view the plugins library.140- Select **Plugins** in the left sidebar to view the plugins library.

137- Install the plugins most relevant to your work.141- Install the plugins most relevant to your work.

138- To point Work to a specific tool, type `@` and the plugin name in your prompt.142- To point ChatGPT to a specific tool, type `@` and the plugin name in your prompt.

139 143 

140Learn more about [plugins](https://learn.chatgpt.com/docs/plugins).144Learn more about [plugins](https://learn.chatgpt.com/docs/plugins).

141 145 

142## Use ChatGPT Work efficiently146<a id="use-chatgpt-work-efficiently"></a>

147 

148## Use Work mode efficiently

143 149 

144Work is best for substantial tasks that involve multiple steps, sources, or150Work mode is best for substantial tasks that involve multiple steps, sources, or

145tools, or require a completed deliverable. Longer or more complex tasks may use151tools, or require a completed deliverable. Longer or more complex tasks may use

146more credits because Work is doing more on your behalf. Focus on the value of152more credits because ChatGPT is doing more on your behalf. Focus on the value of

147the completed result, rather than simply the number of prompts.153the completed result, rather than simply the number of prompts.

148 154 

149Keep the task focused by setting useful boundaries. For example: “use only155Keep the task focused by setting useful boundaries. For example: “use only

150these sources,” “compare the top five options,” or “stop before sending156these sources,” “compare the top five options,” or “stop before sending

151anything.”157anything.”

152 158 

153Use Chat instead for quick questions, short rewrites, and decisions where you159Use Chat mode instead for quick questions, short rewrites, and decisions where you

154only need advice.160only need advice.

155 161 

156Learn more about [working efficiently](https://learn.chatgpt.com/docs/prompting#prompting-for-work).162Learn more about [working efficiently](https://learn.chatgpt.com/docs/prompting#prompting-for-work).

157 163 

158## More use cases164## More use cases

159 165 

160Explore practical ChatGPT Work workflows for common teams and tasks.166Explore practical Work mode workflows for common teams and tasks.

161 167 

162<CodexCollectionList168<CodexCollectionList

163 slugs={[169 slugs={[

glossary.md +56 −36

Details

9 emptyStateMessage="No glossary terms match your search."9 emptyStateMessage="No glossary terms match your search."

10 maxVisibleEntries={100}10 maxVisibleEntries={100}

11 options={[11 options={[

12 {

13 key: "Action",

14 href: "/codex/agent-approvals-security",

15 appliesTo: "Desktop app, Web, Mobile, CLI, IDE extension, Cloud",

16 description:

17 "An operation performed by a person, ChatGPT, or Codex, such as editing a file, running a command, or using a connected service.",

18 },

12 {19 {

13 key: "Agent",20 key: "Agent",

14 href: "/codex",21 href: "/codex",


53 href: "/codex/plugins",60 href: "/codex/plugins",

54 appliesTo: "Desktop app, CLI, IDE extension",61 appliesTo: "Desktop app, CLI, IDE extension",

55 description:62 description:

56 "Compatibility name used by Codex configuration and app-server fields for connectors.",63 "Codex configuration and app-server fields that store connector settings under the `apps` name.",

57 },64 },

58 {65 {

59 key: "Appshot",66 key: "Appshot",

60 href: "/codex/appshots",67 href: "/codex/appshots",

61 appliesTo: "Desktop app",68 appliesTo: "Desktop app",

62 description:69 description:

63 "Snapshot of the frontmost app window sent to a Work or Codex task.",70 "Snapshot of the frontmost app window sent to a ChatGPT or Codex chat.",

64 },71 },

65 {72 {

66 key: "Auth cache",73 key: "Auth cache",


79 key: "Scheduled task",86 key: "Scheduled task",

80 href: "/codex/automations",87 href: "/codex/automations",

81 appliesTo: "Desktop app, Web",88 appliesTo: "Desktop app, Web",

82 description: "A scheduled or recurring task in ChatGPT.",89 description:

90 "A prompt ChatGPT runs at a future time or on a recurring schedule, with its own settings and run history.",

83 },91 },

84 {92 {

85 key: "Scheduled run",93 key: "Scheduled run",

86 href: "/codex/automations#managing-tasks",94 href: "/codex/automations#managing-tasks",

87 appliesTo: "Desktop app, Web",95 appliesTo: "Desktop app, Web",

88 description:96 description:

89 "One execution of a scheduled task that may report findings or archive itself.",97 "One execution of a scheduled task, including its status and any resulting findings.",

90 },98 },

91 {99 {

92 key: "Computer Use in the browser",100 key: "Computer Use in the browser",


98 {106 {

99 key: "Chat",107 key: "Chat",

100 href: "/codex/projects#start-a-chat",108 href: "/codex/projects#start-a-chat",

101 appliesTo: "Desktop app, Web, Mobile",109 appliesTo: "Desktop app, Web, Mobile, CLI, IDE extension, Cloud",

102 description:110 description:

103 "An ordinary ChatGPT conversation containing prompts and responses. Quick Chat opens this same conversation type.",111 "A saved space for exchanging messages with ChatGPT or Codex, including shared context, results, and actions. Quick chat starts a ChatGPT chat from Codex.",

104 },112 },

105 {113 {

106 key: "ChatGPT sign-in",114 key: "ChatGPT sign-in",


127 key: "Cloud environment",135 key: "Cloud environment",

128 href: "/codex/environments/cloud-environment",136 href: "/codex/environments/cloud-environment",

129 appliesTo: "Cloud",137 appliesTo: "Cloud",

130 description: "Configured container setup used for Codex cloud tasks.",138 description: "Configured container setup used for Codex cloud chats.",

131 },139 },

132 {140 {

133 key: "Cloud task",141 key: "Cloud chat",

134 href: "/codex/environments/cloud-environment#how-codex-cloud-tasks-run",142 href: "/codex/environments/cloud-environment#how-codex-cloud-tasks-run",

135 appliesTo: "Cloud",143 appliesTo: "Cloud",

136 description:144 description: "A Codex chat that runs remotely in a cloud environment.",

137 "A remotely executed Codex task that runs in a cloud environment.",

138 },145 },

139 {146 {

140 key: "Codex",147 key: "Codex",


147 href: "/codex/app",154 href: "/codex/app",

148 appliesTo: "Desktop",155 appliesTo: "Desktop",

149 description:156 description:

150 "Desktop app with ChatGPT Work, Codex, and a separate Quick Chat window, including projects, file previews, scheduled tasks, and developer tools.",157 "Desktop app with ChatGPT and Codex, including Chat and Work modes, projects, file previews, scheduled tasks, and developer tools.",

151 },158 },

152 {159 {

153 key: "Codex app-server",160 key: "Codex app-server",


195 key: "Codex-managed worktree",202 key: "Codex-managed worktree",

196 href: "/codex/environments/git-worktrees#codex-managed-and-permanent-worktrees",203 href: "/codex/environments/git-worktrees#codex-managed-and-permanent-worktrees",

197 appliesTo: "Desktop app",204 appliesTo: "Desktop app",

198 description: "A temporary worktree Codex creates and manages for a task.",205 description: "A temporary worktree Codex creates and manages for a chat.",

199 },206 },

200 {207 {

201 key: "Compaction",208 key: "Compaction",


229 href: "/codex/remote-connections#what-comes-from-the-connected-host",236 href: "/codex/remote-connections#what-comes-from-the-connected-host",

230 appliesTo: "Desktop app, Mobile",237 appliesTo: "Desktop app, Mobile",

231 description:238 description:

232 "Computer or development environment that provides files, tools, and shell access for Work or Codex tasks opened through Remote.",239 "Computer or development environment that provides files, tools, and shell access for ChatGPT or Codex chats opened through Remote.",

233 },240 },

234 {241 {

235 key: "Connector",242 key: "Connector",

236 href: "/codex/plugins",243 href: "/codex/plugins",

237 appliesTo: "Desktop app (Work, Codex), Web (Work)",244 appliesTo: "Desktop app (Work mode, Codex), Web (Work mode)",

245 description:

246 "A component of a plugin that connects ChatGPT or Codex to data and actions in an external service.",

247 },

248 {

249 key: "Conversation",

250 href: "/codex/projects#start-a-chat",

251 appliesTo: "Desktop app, Web, Mobile, CLI, IDE extension, Cloud",

238 description:252 description:

239 "Connector that lets Work or Codex access external services through a plugin.",253 "The ongoing exchange of messages and shared context between a person and ChatGPT or Codex within a chat.",

240 },254 },

241 {255 {

242 key: "Container cache",256 key: "Container cache",

243 href: "/codex/environments/cloud-environment#container-caching",257 href: "/codex/environments/cloud-environment#container-caching",

244 appliesTo: "Cloud",258 appliesTo: "Cloud",

245 description:259 description:

246 "Saved cloud container state reused to speed up future tasks.",260 "Saved cloud container state reused to speed up future cloud chats.",

247 },261 },

248 {262 {

249 key: "Context",263 key: "Context",


345 key: "Handoff",359 key: "Handoff",

346 href: "/codex/environments/git-worktrees#working-between-local-and-worktree",360 href: "/codex/environments/git-worktrees#working-between-local-and-worktree",

347 appliesTo: "Desktop app",361 appliesTo: "Desktop app",

348 description: "Moving a task and its work between Local and Worktree.",362 description: "Moving a chat and its work between Local and Worktree.",

349 },363 },

350 {364 {

351 key: "Heartbeat",365 key: "Heartbeat",

352 href: "/codex/automations#schedule-work-from-a-task",366 href: "/codex/automations#schedule-a-task-inside-a-chat",

353 appliesTo: "Desktop app",367 appliesTo: "Desktop app",

354 description:368 description:

355 "Shorthand for recurring scheduled work that returns ChatGPT to the same task.",369 "A recurring scheduled task that returns ChatGPT to the same chat.",

356 },370 },

357 {371 {

358 key: "Hook",372 key: "Hook",


393 description: "Mode where Codex works on the user's computer.",407 description: "Mode where Codex works on the user's computer.",

394 },408 },

395 {409 {

396 key: "Local task",410 key: "Local chat",

397 href: "/codex/environments/modes",411 href: "/codex/environments/modes",

398 appliesTo: "Desktop app, CLI, IDE extension",412 appliesTo: "Desktop app, CLI, IDE extension",

399 description: "A Work or Codex task that runs on the user's machine.",413 description: "A ChatGPT or Codex chat that runs on the user's machine.",

400 },414 },

401 {415 {

402 key: "Maintenance script",416 key: "Maintenance script",


505 {519 {

506 key: "Plugin",520 key: "Plugin",

507 href: "/codex/plugins",521 href: "/codex/plugins",

508 appliesTo: "Desktop app (Work, Codex), Web (Work), CLI",522 appliesTo: "Desktop app (Work mode, Codex), Web (Work mode), CLI",

509 description:523 description:

510 "Installable bundle that can distribute skills, tools, and integrations.",524 "An installable bundle of capabilities such as skills, connectors, and tools.",

511 },525 },

512 {526 {

513 key: "Plugin manifest",527 key: "Plugin manifest",

514 href: "/codex/build-plugins#plugin-structure",528 href: "/codex/build-plugins#plugin-structure",

515 appliesTo: "Desktop app, CLI, IDE extension, Plugins",529 appliesTo: "Plugin authoring",

516 description:530 description:

517 "Plugin metadata file that identifies a plugin and points to bundled skills, apps, MCP servers, hooks, and metadata.",531 "Plugin metadata file that identifies a plugin and points to bundled skills, connector mappings, MCP servers, hooks, and metadata.",

518 },532 },

519 {533 {

520 key: "Prefix rule",534 key: "Prefix rule",


541 href: "/codex/projects",555 href: "/codex/projects",

542 appliesTo: "Desktop app",556 appliesTo: "Desktop app",

543 description:557 description:

544 "A group of related chats or tasks and shared sources, or a local folder used for file-based work.",558 "A group of related chats and shared sources, or a local folder used for file-based work.",

545 },559 },

546 {560 {

547 key: "Prompt",561 key: "Prompt",


580 href: "/codex/remote-connections",594 href: "/codex/remote-connections",

581 appliesTo: "Desktop app, Mobile",595 appliesTo: "Desktop app, Mobile",

582 description:596 description:

583 "Connection that lets you access Work or Codex tasks on another device through a connected host.",597 "Connection that lets you access ChatGPT or Codex chats on another device through a connected host.",

584 },598 },

585 {599 {

586 key: "requirements.toml",600 key: "requirements.toml",


668 href: "/codex/automations",682 href: "/codex/automations",

669 appliesTo: "Desktop app, Web",683 appliesTo: "Desktop app, Web",

670 description:684 description:

671 "Scheduled task whose runs each start a new task and report findings in Triage.",685 "Scheduled task whose runs each start a new chat and report findings in Triage.",

672 },686 },

673 {687 {

674 key: "STDIO MCP server",688 key: "STDIO MCP server",


697 description:711 description:

698 "Workflow where Codex runs delegated agents in parallel and combines their results.",712 "Workflow where Codex runs delegated agents in parallel and combines their results.",

699 },713 },

714 {

715 key: "Standalone task",

716 href: "/codex/projects",

717 appliesTo: "Desktop app, CLI, IDE extension, Cloud",

718 description: "A Codex task that isn't grouped within a project.",

719 },

700 {720 {

701 key: "Task",721 key: "Task",

702 href: "/codex/projects",722 href: "/codex/projects",

703 appliesTo: "Desktop app, Web, Mobile, CLI, IDE extension, Cloud",723 appliesTo: "Desktop app, Web, Mobile, CLI, IDE extension, Cloud",

704 description:724 description:

705 "Durable unit of Work or Codex activity containing its context, messages, results, and actions.",725 "A defined outcome ChatGPT or Codex works toward, such as fixing a bug, creating a document, or researching a topic.",

706 },726 },

707 {727 {

708 key: "Thread",728 key: "Thread",

709 href: "/codex/app-server#threads",729 href: "/codex/app-server#threads",

710 appliesTo: "App-server, SDK",730 appliesTo: "App-server, SDK",

711 description:731 description:

712 "Technical conversation object exposed by Codex app-server APIs and protocol fields.",732 "A technical object in Codex app-server APIs that contains turns and stored conversation history.",

713 },733 },

714 {734 {

715 key: "Scheduled work",735 key: "Scheduled task in a chat",

716 href: "/codex/automations#schedule-work-from-a-task",736 href: "/codex/automations#schedule-a-task-inside-a-chat",

717 appliesTo: "Desktop app, Web",737 appliesTo: "Desktop app, Web",

718 description:738 description:

719 "Work scheduled from an existing task that returns to the same task context on each scheduled run.",739 "A scheduled task that uses an existing chat's context and returns each run's results to that chat.",

720 },740 },

721 {741 {

722 key: "Thread fork",742 key: "Thread fork",


730 href: "/codex/app-server#core-primitives",750 href: "/codex/app-server#core-primitives",

731 appliesTo: "Desktop app, CLI, IDE extension, Cloud, SDK",751 appliesTo: "Desktop app, CLI, IDE extension, Cloud, SDK",

732 description:752 description:

733 "One exchange in a chat or task, usually a user prompt plus the agent's response and actions.",753 "One exchange in a chat, usually a user prompt plus the agent's response and actions.",

734 },754 },

735 {755 {

736 key: "Universal image",756 key: "Universal image",


747 "Pre-indexed search results Codex can use without live browsing.",767 "Pre-indexed search results Codex can use without live browsing.",

748 },768 },

749 {769 {

750 key: "Work",770 key: "Work mode",

751 href: "/codex/get-started-with-work",771 href: "/codex/get-started-with-work",

752 appliesTo: "Desktop app, Web",772 appliesTo: "Desktop app, Web",

753 description:773 description:

754 "ChatGPT Work is an agent for research, analysis, and creating documents, presentations, spreadsheets, and other finished work.",774 "Mode in ChatGPT for research, analysis, and creating documents, presentations, spreadsheets, and other finished work.",

755 },775 },

756 {776 {

757 key: "Worktree",777 key: "Worktree",

hooks.md +80 −32

Details

3Hooks are an extensibility framework for Codex. They allow3Hooks are an extensibility framework for Codex. They allow

4you to inject your own scripts into the agentic loop, enabling features such as:4you to inject your own scripts into the agentic loop, enabling features such as:

5 5 

6- Send the conversation to a custom logging/analytics engine6- Send the chat to a custom logging/analytics engine

7- Scan your team's prompts to block accidentally pasting API keys7- Scan your team's prompts to block accidentally pasting API keys

8- Summarize conversations to create persistent memories automatically8- Summarize chats to create persistent memories automatically

9- Run a custom validation check when a conversation turn stops, enforcing standards9- Run a custom validation check when a chat turn stops, enforcing standards

10- Customize prompting when in a certain directory10- Customize prompting when in a certain directory

11 11 

12Runtime behavior to keep in mind:12Runtime behavior to keep in mind:


81 81 

82```json82```json

83{83{

84 "description": "Optional lifecycle hooks for this workspace.",

84 "hooks": {85 "hooks": {

85 "SessionStart": [86 "SessionStart": [

86 {87 {


157 158 

158Notes:159Notes:

159 160 

161- `description` is optional top-level metadata for a `hooks.json` file. It

162 doesn't change which hooks run.

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

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

162- `statusMessage` is optional.165- `statusMessage` is optional.


295| Event | What `matcher` filters | Notes |298| Event | What `matcher` filters | Notes |

296| ------------------- | ---------------------- | ------------------------------------------------------------ |299| ------------------- | ---------------------- | ------------------------------------------------------------ |

297| `PermissionRequest` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |300| `PermissionRequest` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |

298| `PostToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |301| `PostToolUse` | tool name | See [Tool coverage](#tool-coverage) |

299| `PostCompact` | compaction trigger | Values are `manual` or `auto` |302| `PostCompact` | compaction trigger | Values are `manual` or `auto` |

300| `PreCompact` | compaction trigger | Values are `manual` or `auto` |303| `PreCompact` | compaction trigger | Values are `manual` or `auto` |

301| `PreToolUse` | tool name | Support includes `Bash`, `apply_patch`\*, and MCP tool names |304| `PreToolUse` | tool name | See [Tool coverage](#tool-coverage) |

302| `SessionStart` | start source | Values are `startup`, `resume`, `clear`, and `compact` |305| `SessionStart` | start source | Values are `startup`, `resume`, `clear`, and `compact` |

303| `SubagentStart` | subagent type | Values depend on the subagent that starts |306| `SubagentStart` | subagent type | Values depend on the subagent that starts |

304| `SubagentStop` | subagent type | Values depend on the subagent that stops |307| `SubagentStop` | subagent type | Values depend on the subagent that stops |


317- `startup|resume|clear|compact`320- `startup|resume|clear|compact`

318- `manual|auto`321- `manual|auto`

319 322 

323### Tool coverage

324 

325`PreToolUse` and `PostToolUse` can observe more than shell and MCP calls. Most

326local function tools use the same hook path, so you can match their tool name,

327inspect their JSON arguments, and, for `PreToolUse`, block or rewrite the call.

328 

329| Tool path | `PreToolUse` | `PostToolUse` | Notes |

330| --------------------------------- | ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------ |

331| Shell commands | Yes | Yes | Match as `Bash`. |

332| Unified exec (`exec_command`) | Yes | Yes | Match as `Bash`. A later `write_stdin` poll can deliver the original command's `PostToolUse` when that command finishes. |

333| `apply_patch` | Yes | Yes | Match as `apply_patch`, `Edit`, or `Write`. |

334| MCP tools | Yes | Yes | Match the MCP tool name, such as `mcp__filesystem__read_file`. |

335| Other local function tools | Yes | Yes | Match the function tool name, such as `update_plan`. `spawn_agent` also matches `Agent`. |

336| Hosted tools, such as `WebSearch` | No | No | These don't use the local function-tool hook path. |

337 

338`write_stdin` is transport for an existing unified-exec session. It doesn't run

339`PreToolUse` again when it sends input or polls a command that already passed

340`PreToolUse`.

341 

342Some specialized tool paths can opt out of the default hook path. Treat tool

343hooks as a useful guardrail, not a complete enforcement boundary.

344 

320## Common input fields345## Common input fields

321 346 

322Every command hook receives one JSON object on `stdin`.347Every command hook receives one JSON object on `stdin`.


339`permission_mode`, which describes the current permission mode as `default`,364`permission_mode`, which describes the current permission mode as `default`,

340`acceptEdits`, `plan`, `dontAsk`, or `bypassPermissions`.365`acceptEdits`, `plan`, `dontAsk`, or `bypassPermissions`.

341 366 

342`transcript_path` points to a conversation transcript for convenience, but the367`transcript_path` points to a chat transcript for convenience, but the

343transcript format isn't a stable interface for hooks and may change over time.368transcript format isn't a stable interface for hooks and may change over time.

344 369 

345If you need the full wire format, see [Schemas](#schemas).370If you need the full wire format, see [Schemas](#schemas).


377`PostToolUse` supports `systemMessage`, `continue: false`, and `stopReason`.402`PostToolUse` supports `systemMessage`, `continue: false`, and `stopReason`.

378`suppressOutput` is parsed but not currently supported for that event.403`suppressOutput` is parsed but not currently supported for that event.

379 404 

405### Large hook output

406 

407Codex limits each model-visible hook-output message to roughly 2,500 tokens.

408If a hook returns more, Codex saves the full text under

409`<temp_dir>/hook_outputs/<session_id>/<uuid>.txt` and gives the model a

410head-and-tail preview with the saved-file path. If the file can't be written,

411the model still receives a truncated preview.

412 

413This applies to additional context from `SessionStart`, `SubagentStart`,

414`PreToolUse`, `PostToolUse`, and `UserPromptSubmit`, feedback from

415`PostToolUse`, and continuation prompts from `Stop` and `SubagentStop`. The

416limit applies to each additional-context entry or continuation prompt. For

417`PostToolUse` feedback, Codex combines feedback from all matching hooks and

418applies the limit to the combined message.

419 

420Because oversized output can be written to disk, avoid returning secrets or

421other sensitive data in hook output.

422 

380## Hooks423## Hooks

381 424 

382### SessionStart425### SessionStart


438### PreToolUse481### PreToolUse

439 482 

440`PreToolUse` can intercept Bash, file edits performed through `apply_patch`,483`PreToolUse` can intercept Bash, file edits performed through `apply_patch`,

441and MCP tool calls. It's still a guardrail rather than a complete enforcement484MCP tool calls, and other local function tools. See [Tool

442boundary because Codex can often perform equivalent work through another485coverage](#tool-coverage) for the supported paths and exceptions.

443supported tool path.

444 

445This doesn't intercept all shell calls yet, only the simple ones. The newer

446 `unified_exec` mechanism allows richer streaming stdin/stdout handling of

447 shell, but interception is incomplete. Similarly, this doesn't intercept

448 `WebSearch` or other non-shell, non-MCP tool calls.

449 486 

450`matcher` is applied to `tool_name` and matcher aliases. For file edits through487`matcher` is applied to `tool_name` and matcher aliases. For file edits through

451`apply_patch`, `matcher` values can use `apply_patch`, `Edit`, or `Write`; hook input488`apply_patch`, `matcher` values can use `apply_patch`, `Edit`, or `Write`; hook input


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

455 492 

456| Field | Type | Meaning |493| Field | Type | Meaning |

457| ------------- | ------------ | ---------------------------------------------------------------------------------------------------------- |494| ------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- |

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

459| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |496| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |

460| `tool_use_id` | `string` | Tool-call id for this invocation |497| `tool_use_id` | `string` | Tool-call id for this invocation |

461| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all arguments. |498| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command`. MCP and other local function tools send their arguments. |

462 499 

463Plain text on `stdout` is ignored.500Plain text on `stdout` is ignored.

464 501 


514```551```

515 552 

516For Bash commands and `apply_patch`, `updatedInput` must include a string553For Bash commands and `apply_patch`, `updatedInput` must include a string

517`command` field. For MCP tools, `updatedInput` is the replacement arguments554`command` field. For MCP and other local function tools, `updatedInput` is the

518object. Return `updatedInput` only with `permissionDecision: "allow"`; other555replacement arguments object. Return `updatedInput` only with

519`updatedInput` shapes are reported as errors.556`permissionDecision: "allow"`; other `updatedInput` shapes are reported as

557errors.

520 558 

521`permissionDecision: "ask"`, legacy `decision: "approve"`, `continue: false`,559`permissionDecision: "ask"`, legacy `decision: "approve"`, `continue: false`,

522`stopReason`, and `suppressOutput` are parsed but not supported yet. Codex marks560`stopReason`, and `suppressOutput` are parsed but not supported yet. Codex marks


585### PostToolUse623### PostToolUse

586 624 

587`PostToolUse` runs after supported tools produce output, including Bash,625`PostToolUse` runs after supported tools produce output, including Bash,

588`apply_patch`, and MCP tool calls. For Bash, it also runs after commands that626`apply_patch`, MCP tool calls, and other local function tools. For Bash, it

589exit with a non-zero status. It can't undo side effects from the tool that627also runs after commands that exit with a non-zero status. It can't undo side

590already ran.628effects from a tool that already ran. See [Tool coverage](#tool-coverage) for

591 629the supported paths and exceptions.

592This doesn't intercept all shell calls yet, only the simple ones. The newer

593 `unified_exec` mechanism allows richer streaming stdin/stdout handling of

594 shell, but interception is incomplete. Similarly, this doesn't intercept

595 `WebSearch` or other non-shell, non-MCP tool calls.

596 630 

597`matcher` is applied to `tool_name` and matcher aliases. For file edits through631`matcher` is applied to `tool_name` and matcher aliases. For file edits through

598`apply_patch`, `matcher` values can use `apply_patch`, `Edit`, or `Write`; hook input632`apply_patch`, `matcher` values can use `apply_patch`, `Edit`, or `Write`; hook input


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

602 636 

603| Field | Type | Meaning |637| Field | Type | Meaning |

604| --------------- | ------------ | ---------------------------------------------------------------------------------------------------------- |638| --------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- |

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

606| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |640| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |

607| `tool_use_id` | `string` | Tool-call id for this invocation |641| `tool_use_id` | `string` | Tool-call id for this invocation |

608| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all arguments. |642| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command`. MCP and other local function tools send their arguments. |

609| `tool_response` | `JSON value` | Tool-specific output. For MCP tools, this is the MCP call result. |643| `tool_response` | `JSON value` | Tool-specific output. MCP tools send the MCP call result. Other local function tools normally send their model-facing output. |

610 644 

611Plain text on `stdout` is ignored.645Plain text on `stdout` is ignored.

612 646 


639Codex marks the hook run as failed, reports the error, and continues normal673Codex marks the hook run as failed, reports the error, and continues normal

640processing of the tool result.674processing of the tool result.

641 675 

676#### Tool calls from code mode

677 

678When a model uses code mode to call a tool from JavaScript, hook decisions apply

679to that nested call. `PreToolUse` can stop the tool before it runs or rewrite

680its input. A blocking `PostToolUse` can't undo the tool's side effects, but it

681can keep the original result from reaching the running script.

682 

683| Hook result | What code mode sees |

684| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |

685| `PreToolUse` blocks | The tool promise rejects before the tool runs. |

686| `PreToolUse` returns `updatedInput` | The tool runs with the rewritten input and the promise resolves with that result. |

687| `PostToolUse` returns `decision: "block"` or exits with code `2` | The tool runs, then the promise rejects with the hook reason. |

688| `PostToolUse` returns `continue: false` | Codex uses the hook feedback for the model-visible result, but doesn't reject the nested tool promise. |

689 

642### PreCompact690### PreCompact

643 691 

644`PreCompact` runs before Codex compacts the conversation. `matcher` is applied692`PreCompact` runs before Codex compacts the chat. `matcher` is applied

645to `trigger`, whose values are `manual` and `auto`.693to `trigger`, whose values are `manual` and `auto`.

646 694 

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


659 707 

660### PostCompact708### PostCompact

661 709 

662`PostCompact` runs after Codex compacts the conversation. `matcher` is applied710`PostCompact` runs after Codex compacts the chat. `matcher` is applied

663to `trigger`, whose values are `manual` and `auto`.711to `trigger`, whose values are `manual` and `auto`.

664 712 

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

ide/commands.md +15 −15

Details

15 15 

16| Command | Default key binding | Description |16| Command | Default key binding | Description |

17| ------------------------- | ------------------------------------------ | ------------------------------------------------------- |17| ------------------------- | ------------------------------------------ | ------------------------------------------------------- |

18| `chatgpt.addToThread` | - | Add selected text range as context for the current task |18| `chatgpt.addToThread` | - | Add selected text range as context for the current chat |

19| `chatgpt.addFileToThread` | - | Add the entire file as context for the current task |19| `chatgpt.addFileToThread` | - | Add the entire file as context for the current chat |

20| `chatgpt.newChat` | macOS: `Cmd+N`<br/>Windows/Linux: `Ctrl+N` | Create a new task |20| `chatgpt.newChat` | macOS: `Cmd+N`<br/>Windows/Linux: `Ctrl+N` | Create a new chat |

21| `chatgpt.newCodexPanel` | - | Create a new Codex panel |21| `chatgpt.newCodexPanel` | - | Create a new Codex panel |

22| `chatgpt.openCommandMenu` | - | Open the Codex command menu |22| `chatgpt.openCommandMenu` | - | Open the Codex command menu |

23| `chatgpt.openSidebar` | - | Open the Codex sidebar panel |23| `chatgpt.openSidebar` | - | Open the Codex sidebar panel |


35| Slash command | Description |35| Slash command | Description |

36| -------------------- | --------------------------------------------------------------------------------------- |36| -------------------- | --------------------------------------------------------------------------------------- |

37| `/approve` | Approve one retry of a recent automatic-review denial, when automatic review is active. |37| `/approve` | Approve one retry of a recent automatic-review denial, when automatic review is active. |

38| `/cloud` | Run the task in the cloud, when cloud execution is available. |38| `/cloud` | Run the chat in the cloud, when cloud execution is available. |

39| `/cloud-environment` | Choose the cloud environment for the task. |39| `/cloud-environment` | Choose the cloud environment for the chat. |

40| `/compact` | Compact the current task's context. |40| `/compact` | Compact the current chat's context. |

41| `/fast` | Turn a catalog-provided Fast service tier on or off, when available. |41| `/fast` | Turn a catalog-provided Fast service tier on or off, when available. |

42| `/feedback` | Open the feedback dialog to submit feedback and optionally include logs. |42| `/feedback` | Open the feedback dialog to submit feedback and optionally include logs. |

43| `/fork` | Copy a local task into a new local task. |43| `/fork` | Copy a local chat into a new local chat. |

44| `/goal` | Set a persistent goal for Codex to work toward. |44| `/goal` | Set a persistent goal for Codex to work toward. |

45| `/ide-context` | Turn automatic IDE context on or off. |45| `/ide-context` | Turn automatic IDE context on or off. |

46| `/init` | Generate an `AGENTS.md` scaffold for the current project. |46| `/init` | Generate an `AGENTS.md` scaffold for the current project. |

47| `/local` | Run the task in your local workspace. |47| `/local` | Run the chat in your local workspace. |

48| `/mcp` | Open MCP status to view connected servers. |48| `/mcp` | Open MCP status to view connected servers. |

49| `/memories` | Configure whether the task can use or generate memories, when Memories is available. |49| `/memories` | Configure whether the chat can use or generate memories, when Memories is available. |

50| `/model` | Choose the model for the current task. |50| `/model` | Choose the model for the current chat. |

51| `/personality` | Choose how Codex responds, when the current model supports personalities. |51| `/personality` | Choose how Codex responds, when the current model supports personalities. |

52| `/plan` | Toggle plan mode for multi-step planning. |52| `/plan` | Toggle plan mode for multi-step planning. |

53| `/project` | Choose a project for new tasks. |53| `/project` | Choose a project for new chats. |

54| `/reasoning` | Choose the reasoning effort for the current task. |54| `/reasoning` | Choose the reasoning effort for the current chat. |

55| `/review` | Start code review mode to review uncommitted changes or compare against a base branch. |55| `/review` | Start code review mode to review uncommitted changes or compare against a base branch. |

56| `/side` | Start a temporary side conversation without interrupting the main task. |56| `/side` | Start a temporary side chat without interrupting the main chat. |

57| `/status` | Show the task ID, context usage, and rate limits. |57| `/status` | Show the chat ID, context usage, and rate limits. |

58| `/worktree` | Run the task in a new Git worktree. |58| `/worktree` | Run the chat in a new Git worktree. |

ide/settings.md +4 −4

Details

272. Search for `@ext:openai.chatgpt`, `Codex`, or the setting name.272. Search for `@ext:openai.chatgpt`, `Codex`, or the setting name.

283. Update the value.283. Update the value.

29 29 

30The extension also honors VS Code's built-in chat font settings for Codex conversation surfaces.30The extension also honors VS Code's built-in chat font settings for Codex chat surfaces.

31 31 

32## Editor settings reference32## Editor settings reference

33 33 


37| `chatgpt.openOnStartup` | `false` | Focus the Codex sidebar when the extension finishes starting. |37| `chatgpt.openOnStartup` | `false` | Focus the Codex sidebar when the extension finishes starting. |

38| `chatgpt.followUpQueueMode` | `queue` | Choose whether messages sent during a run wait for the next run (`queue`) or steer the current run (`steer`). The extension treats the legacy `interrupt` value as `steer`. Press <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Enter</kbd> to invert the behavior for one message. |38| `chatgpt.followUpQueueMode` | `queue` | Choose whether messages sent during a run wait for the next run (`queue`) or steer the current run (`steer`). The extension treats the legacy `interrupt` value as `steer`. Press <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Enter</kbd> to invert the behavior for one message. |

39| `chatgpt.composerEnterBehavior` | `enter` | Choose whether <kbd>Enter</kbd> always sends (`enter`), <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>Enter</kbd> sends multiline prompts (`cmdIfMultiline`), or the modifier is always required (`cmdAlways`). |39| `chatgpt.composerEnterBehavior` | `enter` | Choose whether <kbd>Enter</kbd> always sends (`enter`), <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>Enter</kbd> sends multiline prompts (`cmdIfMultiline`), or the modifier is always required (`cmdAlways`). |

40| `chatgpt.reviewDelivery` | `inline` | Run `/review` in the current task when possible (`inline`) or start a separate review task (`detached`). |40| `chatgpt.reviewDelivery` | `inline` | Run `/review` in the current chat when possible (`inline`) or start a separate review chat (`detached`). |

41| `chatgpt.localeOverride` | Auto | Set the preferred language for the Codex UI. Leave empty to detect it automatically. |41| `chatgpt.localeOverride` | Auto | Set the preferred language for the Codex UI. Leave empty to detect it automatically. |

42| `chatgpt.runCodexInWindowsSubsystemForLinux` | `false` | Windows only: Run Codex in WSL when WSL is available. Use this when your repositories and tooling live in WSL2 or when you need Linux-native tooling. Changing this setting reloads VS Code. |42| `chatgpt.runCodexInWindowsSubsystemForLinux` | `false` | Windows only: Run Codex in WSL when WSL is available. Use this when your repositories and tooling live in WSL2 or when you need Linux-native tooling. Changing this setting reloads VS Code. |

43| `chatgpt.cliExecutable` | Unset | Development only: Set the path to the Codex CLI executable. You don't need this setting unless you're developing the Codex CLI; manually overriding the bundled executable can prevent parts of the extension from working. |43| `chatgpt.cliExecutable` | Unset | Development only: Set the path to the Codex CLI executable. You don't need this setting unless you're developing the Codex CLI; manually overriding the bundled executable can prevent parts of the extension from working. |

44| `chat.fontSize` | Editor default | Control chat text in the Codex sidebar, including conversation content and the composer. |44| `chat.fontSize` | Editor default | Control chat text in the Codex sidebar, including chat content and the composer. |

45| `chat.editor.fontSize` | Editor default | Control code-rendered content in Codex conversations, including code snippets and diffs. |45| `chat.editor.fontSize` | Editor default | Control code-rendered content in Codex chats, including code snippets and diffs. |

46 46 

47The `chatgpt.*` keys above belong to the IDE extension and don't go in47The `chatgpt.*` keys above belong to the IDE extension and don't go in

48`config.toml`. For shared agent settings, use [Config48`config.toml`. For shared agent settings, use [Config

Details

15 15 

16| Command | Default key binding | Description |16| Command | Default key binding | Description |

17| ------------------------- | ------------------------------------------ | ------------------------------------------------------- |17| ------------------------- | ------------------------------------------ | ------------------------------------------------------- |

18| `chatgpt.addToThread` | - | Add selected text range as context for the current task |18| `chatgpt.addToThread` | - | Add selected text range as context for the current chat |

19| `chatgpt.addFileToThread` | - | Add the entire file as context for the current task |19| `chatgpt.addFileToThread` | - | Add the entire file as context for the current chat |

20| `chatgpt.newChat` | macOS: `Cmd+N`<br/>Windows/Linux: `Ctrl+N` | Create a new task |20| `chatgpt.newChat` | macOS: `Cmd+N`<br/>Windows/Linux: `Ctrl+N` | Create a new chat |

21| `chatgpt.newCodexPanel` | - | Create a new Codex panel |21| `chatgpt.newCodexPanel` | - | Create a new Codex panel |

22| `chatgpt.openCommandMenu` | - | Open the Codex command menu |22| `chatgpt.openCommandMenu` | - | Open the Codex command menu |

23| `chatgpt.openSidebar` | - | Open the Codex sidebar panel |23| `chatgpt.openSidebar` | - | Open the Codex sidebar panel |


35| Slash command | Description |35| Slash command | Description |

36| -------------------- | --------------------------------------------------------------------------------------- |36| -------------------- | --------------------------------------------------------------------------------------- |

37| `/approve` | Approve one retry of a recent automatic-review denial, when automatic review is active. |37| `/approve` | Approve one retry of a recent automatic-review denial, when automatic review is active. |

38| `/cloud` | Run the task in the cloud, when cloud execution is available. |38| `/cloud` | Run the chat in the cloud, when cloud execution is available. |

39| `/cloud-environment` | Choose the cloud environment for the task. |39| `/cloud-environment` | Choose the cloud environment for the chat. |

40| `/compact` | Compact the current task's context. |40| `/compact` | Compact the current chat's context. |

41| `/fast` | Turn a catalog-provided Fast service tier on or off, when available. |41| `/fast` | Turn a catalog-provided Fast service tier on or off, when available. |

42| `/feedback` | Open the feedback dialog to submit feedback and optionally include logs. |42| `/feedback` | Open the feedback dialog to submit feedback and optionally include logs. |

43| `/fork` | Copy a local task into a new local task. |43| `/fork` | Copy a local chat into a new local chat. |

44| `/goal` | Set a persistent goal for Codex to work toward. |44| `/goal` | Set a persistent goal for Codex to work toward. |

45| `/ide-context` | Turn automatic IDE context on or off. |45| `/ide-context` | Turn automatic IDE context on or off. |

46| `/init` | Generate an `AGENTS.md` scaffold for the current project. |46| `/init` | Generate an `AGENTS.md` scaffold for the current project. |

47| `/local` | Run the task in your local workspace. |47| `/local` | Run the chat in your local workspace. |

48| `/mcp` | Open MCP status to view connected servers. |48| `/mcp` | Open MCP status to view connected servers. |

49| `/memories` | Configure whether the task can use or generate memories, when Memories is available. |49| `/memories` | Configure whether the chat can use or generate memories, when Memories is available. |

50| `/model` | Choose the model for the current task. |50| `/model` | Choose the model for the current chat. |

51| `/personality` | Choose how Codex responds, when the current model supports personalities. |51| `/personality` | Choose how Codex responds, when the current model supports personalities. |

52| `/plan` | Toggle plan mode for multi-step planning. |52| `/plan` | Toggle plan mode for multi-step planning. |

53| `/project` | Choose a project for new tasks. |53| `/project` | Choose a project for new chats. |

54| `/reasoning` | Choose the reasoning effort for the current task. |54| `/reasoning` | Choose the reasoning effort for the current chat. |

55| `/review` | Start code review mode to review uncommitted changes or compare against a base branch. |55| `/review` | Start code review mode to review uncommitted changes or compare against a base branch. |

56| `/side` | Start a temporary side conversation without interrupting the main task. |56| `/side` | Start a temporary side chat without interrupting the main chat. |

57| `/status` | Show the task ID, context usage, and rate limits. |57| `/status` | Show the chat ID, context usage, and rate limits. |

58| `/worktree` | Run the task in a new Git worktree. |58| `/worktree` | Run the chat in a new Git worktree. |

Details

2 2 

3Ask ChatGPT to generate or edit images. Use image generation for UI assets,3Ask ChatGPT to generate or edit images. Use image generation for UI assets,

4banners, backgrounds, illustrations, sprite sheets, and placeholders you want4banners, backgrounds, illustrations, sprite sheets, and placeholders you want

5to create alongside code or in a ChatGPT conversation.5to create alongside code or in a ChatGPT chat.

6 6 

7 7 

8 8 

import.md +2 −2

Details

293. Choose the agents you want to import from, then select **Continue**.293. Choose the agents you want to import from, then select **Continue**.

304. On **Select items to import**, select **Continue** to import everything or **Customize** to choose specific items.304. On **Select items to import**, select **Continue** to import everything or **Customize** to choose specific items.

315. If you customize the import, select the items to bring over, then select **Confirm**.315. If you customize the import, select the items to bring over, then select **Confirm**.

326. After the import finishes, open an imported project or task to continue working.326. After the import finishes, open an imported project or chat to continue working.

33 33 

34</WorkflowSteps>34</WorkflowSteps>

35 35 


67| Skills | [Skills](https://learn.chatgpt.com/docs/build-skills) |67| Skills | [Skills](https://learn.chatgpt.com/docs/build-skills) |

68| Plugins | Plugins |68| Plugins | Plugins |

69| Existing project folders | Projects using the same folders |69| Existing project folders | Projects using the same folders |

70| Chats from the last 30 days | ChatGPT tasks |70| Chats from the last 30 days | ChatGPT chats |

71| MCP server configuration | [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp) |71| MCP server configuration | [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp) |

72| Hooks | [Codex hooks](https://learn.chatgpt.com/docs/hooks) |72| Hooks | [Codex hooks](https://learn.chatgpt.com/docs/hooks) |

73| Slash commands | [Skills](https://learn.chatgpt.com/docs/build-skills) |73| Slash commands | [Skills](https://learn.chatgpt.com/docs/build-skills) |

Details

1# Integrated terminal1# Integrated terminal

2 2 

3Each task in the ChatGPT desktop app includes a terminal scoped to its current project or3Each chat in the ChatGPT desktop app includes a terminal scoped to its current project or

4worktree. Open it from the terminal icon in the top-right corner of the app, or4worktree. Open it from the terminal icon in the top-right corner of the app, or

5press <kbd>Ctrl</kbd>+<kbd>`</kbd>.5press <kbd>Ctrl</kbd>+<kbd>`</kbd>.

6 6 

7<CodexScreenshot7<CodexScreenshot

8 alt="Integrated terminal drawer open beneath a ChatGPT task"8 alt="Integrated terminal drawer open beneath a ChatGPT chat"

9 lightSrc="/images/codex/app/integrated-terminal-light.webp"9 lightSrc="/images/codex/app/integrated-terminal-light.webp"

10 darkSrc="/images/codex/app/integrated-terminal-dark.webp"10 darkSrc="/images/codex/app/integrated-terminal-dark.webp"

11 maxHeight="400px"11 maxHeight="400px"

Details

96@codex fix the P1 issue96@codex fix the P1 issue

97```97```

98 98 

99Codex starts a cloud task with the pull request as context and can push a fix99Codex starts a cloud chat with the pull request as context and can push a fix

100back to the branch when it has permission to do so.100back to the branch when it has permission to do so.

101 101 

102## Give Codex other tasks102## Give Codex other tasks

103 103 

104If you mention `@codex` in a comment with anything other than `review`, Codex starts a [cloud task](https://learn.chatgpt.com/docs/cloud) using your pull request as context.104If you mention `@codex` in a comment with anything other than `review`, Codex starts a [cloud chat](https://learn.chatgpt.com/docs/cloud) using your pull request as context.

105 105 

106```md106```md

107@codex fix the CI failures107@codex fix the CI failures

Details

1# Use Codex in Linear1# Use Codex in Linear

2 2 

3Use Codex in Linear to delegate work from issues. Assign an issue to Codex or mention `@Codex` in a comment, and Codex creates a cloud task and replies with progress and results.3Use Codex in Linear to delegate work from issues. Assign an issue to Codex or mention `@Codex` in a comment, and Codex creates a cloud chat and replies with progress and results.

4 4 

5Codex in Linear is available on paid plans (see [Pricing](https://learn.chatgpt.com/docs/pricing)).5Codex in Linear is available on paid plans (see [Pricing](https://learn.chatgpt.com/docs/pricing)).

6 6 

7If you're on an Enterprise plan, ask your ChatGPT workspace admin to turn on Codex cloud tasks in [workspace settings](https://chatgpt.com/admin/settings) and enable **Codex for Linear** in [connector settings](https://chatgpt.com/admin/ca).7If you're on an Enterprise plan, ask your ChatGPT workspace admin to turn on Codex cloud chats in [workspace settings](https://chatgpt.com/admin/settings) and enable **Codex for Linear** in [connector settings](https://chatgpt.com/admin/ca).

8 8 

9## Set up the Linear integration9## Set up the Linear integration

10 10 

111. Set up [Codex cloud tasks](https://learn.chatgpt.com/docs/cloud) by connecting GitHub in [Codex](https://chatgpt.com/codex) and creating an [environment](https://learn.chatgpt.com/docs/environments/cloud-environment) for the repository you want Codex to work in.111. Set up [Codex cloud chats](https://learn.chatgpt.com/docs/cloud) by connecting GitHub in [Codex](https://chatgpt.com/codex) and creating an [environment](https://learn.chatgpt.com/docs/environments/cloud-environment) for the repository you want Codex to work in.

122. Go to [Codex settings](https://chatgpt.com/codex/settings/connectors) and install **Codex for Linear** for your workspace.122. Go to [Codex settings](https://chatgpt.com/codex/settings/connectors) and install **Codex for Linear** for your workspace.

133. Link your Linear account by mentioning `@Codex` in a comment thread on a Linear issue.133. Link your Linear account by mentioning `@Codex` in a comment thread on a Linear issue.

14 14 


33 33 

34### Mention `@Codex` in comments34### Mention `@Codex` in comments

35 35 

36You can also mention `@Codex` in comment threads to delegate work or ask questions. After Codex replies, follow up in the thread to continue the same task.36You can also mention `@Codex` in comment threads to delegate work or ask questions. After Codex replies, follow up in the thread to continue the same chat.

37 37 

38<div class="not-prose max-w-3xl mr-auto my-4">38<div class="not-prose max-w-3xl mr-auto my-4">

39 <img src="https://developers.openai.com/images/codex/integrations/linear-comment-light.webp"39 <img src="https://developers.openai.com/images/codex/integrations/linear-comment-light.webp"


52To track progress:52To track progress:

53 53 

54- Open **Activity** on the issue to see progress updates.54- Open **Activity** on the issue to see progress updates.

55- Open the task link to follow along in more detail.55- Open the chat link to follow along in more detail.

56 56 

57When the task finishes, Codex posts a summary and a link to the completed task so you can create a pull request.57When Codex finishes, it posts a summary and a link to the completed chat so you can create a pull request.

58 58 

59### How Codex chooses an environment and repo59### How Codex chooses an environment and repo

60 60 

61- Linear suggests a repository based on the issue context. Codex selects the environment that best matches that suggestion. If the request is ambiguous, it falls back to the environment you used most recently.61- Linear suggests a repository based on the issue context. Codex selects the environment that best matches that suggestion. If the request is ambiguous, it falls back to the environment you used most recently.

62- The task runs against the default branch of the first repository listed in that environment’s repo map. Update the repo map in Codex if you need a different default or more repositories.62- The chat runs against the default branch of the first repository listed in that environment’s repo map. Update the repo map in Codex if you need a different default or more repositories.

63- If no suitable environment or repository is available, Codex will reply in Linear with instructions on how to fix the issue before retrying.63- If no suitable environment or repository is available, Codex will reply in Linear with instructions on how to fix the issue before retrying.

64 64 

65## Automatically assign issues to Codex65## Automatically assign issues to Codex


724. In **Triage rules**, create a rule and choose **Delegate** > **Codex** (and any other properties you want to set).724. In **Triage rules**, create a rule and choose **Delegate** > **Codex** (and any other properties you want to set).

73 73 

74Linear assigns new issues that enter triage to Codex automatically.74Linear assigns new issues that enter triage to Codex automatically.

75When you use triage rules, Codex runs tasks using the account of the issue creator.75When you use triage rules, Codex runs chats using the account of the issue creator.

76 76 

77<div class="not-prose max-w-3xl mr-auto my-4">77<div class="not-prose max-w-3xl mr-auto my-4">

78 <img src="https://developers.openai.com/images/codex/integrations/linear-triage-rule-light.webp"78 <img src="https://developers.openai.com/images/codex/integrations/linear-triage-rule-light.webp"


87 87 

88## Data usage, privacy, and security88## Data usage, privacy, and security

89 89 

90When you mention `@Codex` or assign an issue to it, Codex receives your issue content to understand your request and create a task.90When you mention `@Codex` or assign an issue to it, Codex receives your issue content to understand your request and create a chat.

91Data handling follows OpenAI's [Privacy Policy](https://openai.com/privacy), [Terms of Use](https://openai.com/terms/), and other applicable [policies](https://openai.com/policies).91Data handling follows OpenAI's [Privacy Policy](https://openai.com/privacy), [Terms of Use](https://openai.com/terms/), and other applicable [policies](https://openai.com/policies).

92For more on security, see the [Codex security documentation](https://learn.chatgpt.com/docs/agent-approvals-security).92For more on security, see the [Codex security documentation](https://learn.chatgpt.com/docs/agent-approvals-security).

93 93 


100- **Wrong part of the code**: Add more context in the issue, or give explicit instructions in your `@Codex` comment.100- **Wrong part of the code**: Add more context in the issue, or give explicit instructions in your `@Codex` comment.

101- **More help**: See the [OpenAI Help Center](https://help.openai.com/).101- **More help**: See the [OpenAI Help Center](https://help.openai.com/).

102 102 

103## Connect Linear for local tasks (MCP)103<a id="connect-linear-for-local-tasks-mcp"></a>

104 

105## Connect Linear for local work (MCP)

104 106 

105If you're using the ChatGPT desktop app, Codex CLI, or IDE extension and want it to access Linear issues locally, configure the Linear Model Context Protocol (MCP) server.107If you're using the ChatGPT desktop app, Codex CLI, or IDE extension and want it to access Linear issues locally, configure the Linear Model Context Protocol (MCP) server.

106 108 

Details

1# Use Codex in Slack1# Use Codex in Slack

2 2 

3Use Codex in Slack to kick off coding tasks from channels and threads. Mention `@Codex` with a prompt, and Codex creates a cloud task and replies with the results.3Use Codex in Slack to kick off coding work from channels and threads. Mention `@Codex` with a prompt, and Codex creates a cloud chat and replies with the results.

4 4 

5<div class="not-prose max-w-3xl mr-auto">5<div class="not-prose max-w-3xl mr-auto">

6 <img src="https://developers.openai.com/images/codex/integrations/slack-example.png"6 <img src="https://developers.openai.com/images/codex/integrations/slack-example.png"


13 13 

14## Set up the Slack app14## Set up the Slack app

15 15 

161. Set up [Codex cloud tasks](https://learn.chatgpt.com/docs/cloud). You need a Plus, Pro, Business, Enterprise, or Edu plan (see [ChatGPT pricing](https://chatgpt.com/pricing)), a connected GitHub account, and at least one [environment](https://learn.chatgpt.com/docs/environments/cloud-environment).161. Set up [Codex cloud chats](https://learn.chatgpt.com/docs/cloud). You need a Plus, Pro, Business, Enterprise, or Edu plan (see [ChatGPT pricing](https://chatgpt.com/pricing)), a connected GitHub account, and at least one [environment](https://learn.chatgpt.com/docs/environments/cloud-environment).

172. Go to [Codex settings](https://chatgpt.com/codex/settings/connectors) and install the Slack app for your workspace. Depending on your Slack workspace policies, an admin may need to approve the install.172. Go to [Codex settings](https://chatgpt.com/codex/settings/connectors) and install the Slack app for your workspace. Depending on your Slack workspace policies, an admin may need to approve the install.

183. Add `@Codex` to a channel. If you haven't added it yet, Slack prompts you when you mention it.183. Add `@Codex` to a channel. If you haven't added it yet, Slack prompts you when you mention it.

19 19 

20## Start a task20<a id="start-a-task"></a>

21 

22## Start a chat

21 23 

221. In a channel or thread, mention `@Codex` and include your prompt. Codex can reference earlier messages in the thread, so you often don't need to restate context.241. In a channel or thread, mention `@Codex` and include your prompt. Codex can reference earlier messages in the thread, so you often don't need to restate context.

232. (Optional) Specify an environment or repository in your prompt, for example: `@Codex fix the above in openai/codex`.252. (Optional) Specify an environment or repository in your prompt, for example: `@Codex fix the above in openai/codex`.

243. Wait for Codex to react (👀) and reply with a link to the task. When it finishes, Codex posts the result and, depending on your settings, an answer in the thread.263. Wait for Codex to react (👀) and reply with a link to the chat. When it finishes, Codex posts the result and, depending on your settings, an answer in the thread.

25 27 

26### How Codex chooses an environment and repo28### How Codex chooses an environment and repo

27 29 

28- Codex reviews the environments you have access to and selects the one that best matches your request. If the request is ambiguous, it falls back to the environment you used most recently.30- Codex reviews the environments you have access to and selects the one that best matches your request. If the request is ambiguous, it falls back to the environment you used most recently.

29- The task runs against the default branch of the first repository listed in that environment’s repo map. Update the repo map in Codex if you need a different default or more repositories.31- The chat runs against the default branch of the first repository listed in that environment’s repo map. Update the repo map in Codex if you need a different default or more repositories.

30- If no suitable environment or repository is available, Codex will reply in Slack with instructions on how to fix the issue before retrying.32- If no suitable environment or repository is available, Codex will reply in Slack with instructions on how to fix the issue before retrying.

31 33 

32### Enterprise data controls34### Enterprise data controls

33 35 

34By default, Codex replies in the thread with an answer, which can include information from the environment it ran in.36By default, Codex replies in the thread with an answer, which can include information from the environment it ran in.

35To prevent this, an Enterprise admin can clear **Allow Codex Slack app to post answers on task completion** in [ChatGPT workspace settings](https://chatgpt.com/admin/settings). When an admin turns off answers, Codex replies only with a link to the task.37To prevent this, an Enterprise admin can clear **Allow Codex Slack app to post answers on task completion** in [ChatGPT workspace settings](https://chatgpt.com/admin/settings). When an admin turns off answers, Codex replies only with a link to the chat.

36 38 

37### Data usage, privacy, and security39### Data usage, privacy, and security

38 40 

39When you mention `@Codex`, Codex receives your message and thread history to understand your request and create a task.41When you mention `@Codex`, Codex receives your message and thread history to understand your request and create a chat.

40Data handling follows OpenAI's [Privacy Policy](https://openai.com/privacy), [Terms of Use](https://openai.com/terms/), and other applicable [policies](https://openai.com/policies).42Data handling follows OpenAI's [Privacy Policy](https://openai.com/privacy), [Terms of Use](https://openai.com/terms/), and other applicable [policies](https://openai.com/policies).

41For more on security, see the Codex [security documentation](https://learn.chatgpt.com/docs/agent-approvals-security).43For more on security, see the Codex [security documentation](https://learn.chatgpt.com/docs/agent-approvals-security).

42 44 


47- **Missing connections**: If Codex can't confirm your Slack or GitHub connection, it replies with a link to reconnect.49- **Missing connections**: If Codex can't confirm your Slack or GitHub connection, it replies with a link to reconnect.

48- **Unexpected environment choice**: Reply in the thread with the environment you want (for example, `Please run this in openai/openai (applied)`), then mention `@Codex` again.50- **Unexpected environment choice**: Reply in the thread with the environment you want (for example, `Please run this in openai/openai (applied)`), then mention `@Codex` again.

49- **Long or complex threads**: Summarize key details in your latest message so Codex doesn't miss context buried earlier in the thread.51- **Long or complex threads**: Summarize key details in your latest message so Codex doesn't miss context buried earlier in the thread.

50- **Workspace posting**: Some Enterprise workspaces restrict posting final answers. In those cases, open the task link to view progress and results.52- **Workspace posting**: Some Enterprise workspaces restrict posting final answers. In those cases, open the chat link to view progress and results.

51- **More help**: See the [OpenAI Help Center](https://help.openai.com/).53- **More help**: See the [OpenAI Help Center](https://help.openai.com/).

Details

1# Long-running work1# Long-running work

2 2 

3For work that may take many steps, give ChatGPT a clear outcome, constraints,3For work that may take many steps, give ChatGPT a clear outcome, constraints,

4and definition of done. Keep related work in the same task or conversation so4and definition of done. Keep related work in the same chat so

5ChatGPT can use the same context to choose the next step and decide when the5ChatGPT can use the same context to choose the next step and decide when the

6work is complete.6work is complete.

7 7 


79pause or resume work, edit the goal, or clear it. You can also send follow-up79pause or resume work, edit the goal, or clear it. You can also send follow-up

80messages while the goal runs to add context or adjust constraints.80messages while the goal runs to add context or adjust constraints.

81 81 

82Use a side conversation when you want a status recap or an explanation without82Use a side chat when you want a status recap or an explanation without

83interrupting the main task. Pause the goal before you expect to lose83interrupting the main chat. Pause the goal before you expect to lose

84connectivity, then resume it when you're ready for ChatGPT to continue.84connectivity, then resume it when you're ready for ChatGPT to continue.

85 85 

86 86 


105 105 

106## Run goals in parallel106## Run goals in parallel

107 107 

108Each task keeps its own context, messages, results, and goal. Run tasks108Each chat keeps its own context, messages, results, and goal. Run chats

109concurrently, but avoid letting two tasks change the same files. Use109concurrently, but avoid letting two chats change the same files. Use

110[worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees) to give parallel coding tasks separate110[worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees) to give parallel coding chats separate

111checkouts.111checkouts.

112 112 

113 113 


116 116 

117For local work, turn on **Prevent sleep while running** in settings so your Mac117For local work, turn on **Prevent sleep while running** in settings so your Mac

118stays awake. Use [Pets](https://learn.chatgpt.com/docs/pets?surface=app) or [system118stays awake. Use [Pets](https://learn.chatgpt.com/docs/pets?surface=app) or [system

119notifications](https://learn.chatgpt.com/docs/notifications?surface=app) to see when a task needs input119notifications](https://learn.chatgpt.com/docs/notifications?surface=app) to see when a chat needs input

120or is ready for review.120or is ready for review.

121 121 

122 122 


125 125 

126## Related docs126## Related docs

127 127 

128- [Projects, chats, and tasks](https://learn.chatgpt.com/docs/projects)128- [Projects and chats](https://learn.chatgpt.com/docs/projects)

129- [Goal mode and prompting](https://learn.chatgpt.com/docs/prompting#goal-mode)129- [Goal mode and prompting](https://learn.chatgpt.com/docs/prompting#goal-mode)

130- [Git worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees)130- [Git worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees)

memories.md +15 −13

Details

15 15 

16 16 

17 17 

18In the ChatGPT desktop app, use `/memories` to choose whether a task can use18In the ChatGPT desktop app, use `/memories` to choose whether a chat can use

19local memories or contribute to future memories. Manage the feature from19local memories or contribute to future memories. Manage the feature from

20**Settings > Personalization** when you need to turn it on or off.20**Settings > Personalization** when you need to turn it on or off.

21 21 


46## How local Codex memories work46## How local Codex memories work

47 47 

48After you enable memories, Codex can turn useful context from eligible prior48After you enable memories, Codex can turn useful context from eligible prior

49tasks into local memory files. Codex skips active or short-lived sessions,49chats into local memory files. Codex skips active or short-lived sessions,

50redacts secrets from generated memory fields, and updates memories in the50redacts secrets from generated memory fields, and updates memories in the

51background instead of immediately at the end of every task.51background instead of immediately at the end of every chat.

52 52 

53Memories may not update right away when a task ends. Codex waits until a53Memories may not update right away when a chat ends. Codex waits until a

54task has been idle long enough to avoid summarizing work that's still in54chat has been idle long enough to avoid summarizing work that's still in

55progress.55progress.

56 56 

57Memory generation can also skip a background pass when your Codex rate-limit57Memory generation can also skip a background pass when your Codex rate-limit


65for how Codex uses `CODEX_HOME`.65for how Codex uses `CODEX_HOME`.

66 66 

67The main memory files live under `~/.codex/memories/` and include summaries,67The main memory files live under `~/.codex/memories/` and include summaries,

68durable entries, recent inputs, and supporting evidence from prior tasks.68durable entries, recent inputs, and supporting evidence from prior chats.

69 69 

70Treat these files as generated state. You can inspect them when troubleshooting70Treat these files as generated state. You can inspect them when troubleshooting

71or before sharing your Codex home directory, but don't rely on editing them by71or before sharing your Codex home directory, but don't rely on editing them by

72hand as your primary control surface.72hand as your primary control surface.

73 73 

74## Control local memories per task74<a id="control-local-memories-per-task"></a>

75 

76## Control local memories per chat

75 77 

76In the ChatGPT desktop app and Codex TUI, use `/memories` to control memory behavior for78In the ChatGPT desktop app and Codex TUI, use `/memories` to control memory behavior for

77the current task. Task-level choices let you decide whether the current79the current chat. Chat-level choices let you decide whether the current

78task can use existing memories and whether Codex can use the task to80chat can use existing memories and whether Codex can use the chat to

79generate future memories.81generate future memories.

80 82 

81Task-level choices don't change your global memory settings.83Chat-level choices don't change your global memory settings.

82 84 

83## Review local memories85## Review local memories

84 86 


107 109 

108Common memory-specific settings include:110Common memory-specific settings include:

109 111 

110- `memories.generate_memories`: controls whether newly created tasks can be112- `memories.generate_memories`: controls whether newly created chats can be

111 stored as memory-generation inputs.113 stored as memory-generation inputs.

112- `memories.use_memories`: controls whether Codex injects existing memories into114- `memories.use_memories`: controls whether Codex injects existing memories into

113 future sessions.115 future sessions.

114- `memories.disable_on_external_context`: when `true`, keeps tasks that used116- `memories.disable_on_external_context`: when `true`, keeps chats that used

115 external context such as MCP tool calls, web search, or tool search out of117 external context such as MCP tool calls, web search, or tool search out of

116 memory generation. The older `memories.no_memories_if_mcp_or_web_search` key118 memory generation. The older `memories.no_memories_if_mcp_or_web_search` key

117 is still accepted as an alias.119 is still accepted as an alias.

118- `memories.min_rate_limit_remaining_percent`: controls the minimum remaining120- `memories.min_rate_limit_remaining_percent`: controls the minimum remaining

119 Codex rate-limit percentage required before memory generation starts.121 Codex rate-limit percentage required before memory generation starts.

120- `memories.extract_model`: overrides the model used for per-task memory122- `memories.extract_model`: overrides the model used for per-chat memory

121 extraction.123 extraction.

122- `memories.consolidation_model`: overrides the model used for global memory124- `memories.consolidation_model`: overrides the model used for global memory

123 consolidation.125 consolidation.

Details

783. Turn on **Chronicle** below the Memories setting.783. Turn on **Chronicle** below the Memories setting.

794. Review the consent dialog and choose **Continue**.794. Review the consent dialog and choose **Continue**.

805. Grant macOS Screen Recording and Accessibility permissions when prompted.805. Grant macOS Screen Recording and Accessibility permissions when prompted.

816. When setup completes, choose **Try it out** or start a new task.816. When setup completes, choose **Try it out** or start a new chat.

82 82 

83If macOS reports that Screen Recording or Accessibility permission is denied,83If macOS reports that Screen Recording or Accessibility permission is denied,

84open System Settings &gt; Privacy & Security &gt; Screen Recording or84open System Settings &gt; Privacy & Security &gt; Screen Recording or


94Codex to use as context. To disable Chronicle, return to **Settings &gt;94Codex to use as context. To disable Chronicle, return to **Settings &gt;

95Personalization &gt; Memories** and turn off **Chronicle**.95Personalization &gt; Memories** and turn off **Chronicle**.

96 96 

97You can also control whether memories are used in a given task. [Learn97You can also control whether memories are used in a given chat. [Learn

98more](https://learn.chatgpt.com/docs/customization/memories#control-memories-per-task).98more](https://learn.chatgpt.com/docs/customization/memories#control-memories-per-chat).

99 99 

100## Rate limits100## Rate limits

101 101 

models.md +3 −3

Details

251Use the lowest reasoning effort that produces the result you need. Increase it251Use the lowest reasoning effort that produces the result you need. Increase it

252for tasks that need more planning, analysis, or checking.252for tasks that need more planning, analysis, or checking.

253 253 

254- **Light** in the Codex app, ChatGPT Work, and IDE extension, or **Low** in the254- **Light** in the ChatGPT desktop app, Work mode on the web, and IDE extension, or **Low** in the

255 CLI, suits quick, well-scoped tasks.255 CLI, suits quick, well-scoped tasks.

256- **Medium** balances speed and depth for tasks that need more planning.256- **Medium** balances speed and depth for tasks that need more planning.

257- **High** and **Extra High** suit difficult work with multiple steps, sources,257- **High** and **Extra High** suit difficult work with multiple steps, sources,


378```378```

379 379 

380 380 

381## Choose a model for cloud tasks381## Choose a model for cloud chats

382 382 

383Currently, you can't change the default model for Codex cloud tasks.383Currently, you can't change the default model for Codex cloud chats.

Details

13operating system may ask you to grant notification permission to the ChatGPT13operating system may ask you to grant notification permission to the ChatGPT

14desktop app.14desktop app.

15 15 

16### Follow task activity with a pet16<a id="follow-task-activity-with-a-pet"></a>

17 17 

18In the ChatGPT desktop app, a floating pet is another way to follow task18### Follow chat activity with a pet

19activity while you work in other apps. It can show when a task is **Running**,19 

20In the ChatGPT desktop app, a floating pet is another way to follow chat

21activity while you work in other apps. It can show when a chat is **Running**,

20**Needs input**, **Ready**, or **Blocked**.22**Needs input**, **Ready**, or **Blocked**.

21 23 

22See [Pets](https://learn.chatgpt.com/docs/pets?surface=app) to choose a pet, understand its status, or24See [Pets](https://learn.chatgpt.com/docs/pets?surface=app) to choose a pet, understand its status, or

Details

22**Auto&#45;review** in settings) or **Full access** to the permissions menu, open22**Auto&#45;review** in settings) or **Full access** to the permissions menu, open

23**Settings > General** in the ChatGPT desktop app, then turn on the mode under23**Settings > General** in the ChatGPT desktop app, then turn on the mode under

24**Permissions**. Enabling a mode makes it available in the menu; it doesn't24**Permissions**. Enabling a mode makes it available in the menu; it doesn't

25select the mode or change an existing conversation.25select the mode or change an existing chat.

26 26 

27<Illustration description="Permission visibility controls showing Default permissions, automatic review, and Full access.">27<Illustration description="Permission visibility controls showing Default permissions, automatic review, and Full access.">

28 <PermissionModeSettingsIllustration ariaLabel="Permission visibility controls showing Default permissions, automatic review, and Full access." />28 <PermissionModeSettingsIllustration ariaLabel="Permission visibility controls showing Default permissions, automatic review, and Full access." />

permissions.md +1 −1

Details

21rules, which define what commands can read or write, with network rules, which21rules, which define what commands can read or write, with network rules, which

22define which destinations commands can reach.22define which destinations commands can reach.

23 23 

24Use profiles to give Codex enough access for the current task without granting24Use profiles to give Codex enough access for the current chat without granting

25broad access to your machine or network. For example, a read-only profile can25broad access to your machine or network. For example, a read-only profile can

26let Codex inspect a project without editing it, while a write-capable profile26let Codex inspect a project without editing it, while a write-capable profile

27can limit edits to selected workspace roots.27can limit edits to selected workspace roots.

personalize.md +2 −2

Details

13## Add custom instructions13## Add custom instructions

14 14 

15Use custom instructions for preferences you want ChatGPT to follow across15Use custom instructions for preferences you want ChatGPT to follow across

16chats and tasks, such as your preferred response style. In Codex, these personal16chats, such as your preferred response style. In Codex, these personal

17instructions are stored in your global `AGENTS.md` file. Projects and17instructions are stored in your global `AGENTS.md` file. Projects and

18repositories can also provide their own instructions.18repositories can also provide their own instructions.

19 19 


21 21 

22## Carry context forward with memories22## Carry context forward with memories

23 23 

24[Memories](https://learn.chatgpt.com/docs/customization/memories) let ChatGPT carry useful context from earlier chats and tasks24[Memories](https://learn.chatgpt.com/docs/customization/memories) let ChatGPT carry useful context from earlier chats

25into future work. They can include stable preferences, recurring workflows,25into future work. They can include stable preferences, recurring workflows,

26project conventions, and other context you would otherwise need to repeat.26project conventions, and other context you would otherwise need to repeat.

27 27 

pets.md +10 −10

Details

14## Use a floating pet14## Use a floating pet

15 15 

16In the ChatGPT desktop app, a pet can float above other app windows and help16In the ChatGPT desktop app, a pet can float above other app windows and help

17you follow activity across your tasks.17you follow activity across your chats.

18 18 

19### Choose and wake a pet19### Choose and wake a pet

20 20 


33 33 

34| Status | Meaning |34| Status | Meaning |

35| --------------- | -------------------------------------------------------- |35| --------------- | -------------------------------------------------------- |

36| **Running** | A task is actively working. |36| **Running** | A chat is actively working. |

37| **Needs input** | A task needs your approval, answer, or another decision. |37| **Needs input** | A chat needs your approval, answer, or another decision. |

38| **Ready** | A task has completed and has unread activity. |38| **Ready** | A chat has completed and has unread activity. |

39| **Blocked** | A task failed or encountered a system error. |39| **Blocked** | A chat failed or encountered a system error. |

40 40 

41When more than one task has activity, the pet prioritizes tasks that need41When more than one chat has activity, the pet prioritizes chats that need

42input, followed by blocked, ready, and running tasks. Open the activity tray to42input, followed by blocked, ready, and running chats. Open the activity tray to

43choose a task.43choose a chat.

44 44 

45Select the pet to return to ChatGPT, or select an activity to open its task.45Select the pet to return to ChatGPT, or select an activity to open its chat.

46The activity tray is separate from [system46The activity tray is separate from [system

47notifications](https://learn.chatgpt.com/docs/notifications?surface=app).47notifications](https://learn.chatgpt.com/docs/notifications?surface=app).

48 48 


55 55 

561. Open **Settings > Pets** and select **Create your own pet**.561. Open **Settings > Pets** and select **Create your own pet**.

572. The app installs the bundled `hatch-pet` skill, reloads skills, and opens a572. The app installs the bundled `hatch-pet` skill, reloads skills, and opens a

58 new task.58 new chat.

593. Describe the pet you want and send the prompt.593. Describe the pet you want and send the prompt.

604. When the task finishes, return to **Settings > Pets**, select **Refresh**,604. When the task finishes, return to **Settings > Pets**, select **Refresh**,

61 and choose your new pet.61 and choose your new pet.

plugins.md +24 −21

Details

2 2 

3## Overview3## Overview

4 4 

5Plugins bundle capabilities into reusable workflows in ChatGPT. They5Plugins bundle capabilities into reusable workflows in ChatGPT. They can

6can include skills, an MCP-backed app, or both. Plugins are6include skills, connectors, or both. Plugins are available in Work mode in

7available in ChatGPT Work on the web and in Work or Codex in the ChatGPT7ChatGPT on the web and in Work mode or Codex in the ChatGPT desktop app. Codex

8desktop app. Codex CLI and the IDE extension can also browse and install8CLI also has a plugin browser for Codex environments. Plugins aren't available

9plugins for a Codex environment.9in Chat mode, the IDE extension, or mobile.

10 10 

11 11 

12 12 

13In the ChatGPT desktop app, open **Plugins** from Work or Codex to browse,13In the ChatGPT desktop app, select ChatGPT and switch to Work mode, or select

14install, and use plugins. Installed plugins can add skills, connectors, and MCP14Codex. Then open **Plugins** to browse, install, and use plugins. Installed

15tools to new chats.15plugins can add skills, connectors, and MCP tools to new chats.

16 16 

17 17 

18 18 


36- **Skills:** reusable instructions for specific kinds of work. ChatGPT can load36- **Skills:** reusable instructions for specific kinds of work. ChatGPT can load

37 them when needed so it follows the right steps and uses the right references37 them when needed so it follows the right steps and uses the right references

38 or helper scripts for a task.38 or helper scripts for a task.

39- **Apps:** connections to tools like GitHub, Slack, or Google39- **Connectors:** connections to tools like GitHub, Slack, or Google Drive, so

40 Drive, so ChatGPT can read information from those tools and take actions in40 ChatGPT can read information from those tools and take actions in them.

41 them. Apps expose tools and can optionally include custom ChatGPT UI.41 Connectors expose tools and can optionally include custom ChatGPT UI.

42- **MCP servers:** services that give ChatGPT access to more tools or shared42- **MCP servers:** services that give ChatGPT access to more tools or shared

43 information, often from systems outside your local project. They're also the services behind apps. They define tools, enforce auth, return structured data, and perform actions against external systems.43 information, often from systems outside your local project. They're also the

44 services behind connectors. They define tools, enforce auth, return structured

45 data, and perform actions against external systems.

44- **Browser extensions:** browser capabilities that a plugin needs for its46- **Browser extensions:** browser capabilities that a plugin needs for its

45 workflow.47 workflow.

46- **Hooks:** commands that run at configured lifecycle points. Review and trust48- **Hooks:** commands that run at configured lifecycle points. Review and trust


53for marketplace setup, packaging, and distribution guidance.55for marketplace setup, packaging, and distribution guidance.

54 56 

55If you are building an integration, start with [Build an app](https://learn.chatgpt.com/docs/build-app).57If you are building an integration, start with [Build an app](https://learn.chatgpt.com/docs/build-app).

56If the app needs custom ChatGPT UI, use the [Apps SDK](https://developers.openai.com/apps-sdk) for that58If the app needs custom ChatGPT UI, use the

57optional UI layer.59[Apps SDK](https://developers.openai.com/apps-sdk) for that optional UI layer.

58 60 

59## Use and install plugins61## Use and install plugins

60 62 


66 68 

67To browse and install curated plugins:69To browse and install curated plugins:

68 70 

69- On the web, select Work and open **Plugins**.71- On the web, switch to Work mode and open **Plugins**.

70- In the ChatGPT desktop app, select Work or Codex and open **Plugins**.72- In the ChatGPT desktop app, select ChatGPT and switch to Work mode, or select

73 Codex. Then open **Plugins**.

71 74 

72 75 

73 76 

74 77 

75 78 

76<CodexScreenshot79<CodexScreenshot

77 alt="Plugins page in the ChatGPT desktop app"80 alt="Plugins Directory in the ChatGPT desktop app"

78 lightSrc="/images/codex/plugins/directory.webp"81 lightSrc="/images/codex/plugins/directory.webp"

79 darkSrc="/images/codex/plugins/directory-dark.webp"82 darkSrc="/images/codex/plugins/directory-dark.webp"

80/>83/>


83 86 

84 87 

85 88 

86The plugin directory organizes plugins into tabs:89The Plugins Directory organizes plugins into tabs:

87 90 

88- **OpenAI:** plugins built by OpenAI.91- **OpenAI:** plugins built by OpenAI.

89- **Your workspace name:** plugins provided by your workspace.92- **Your workspace name:** plugins provided by your workspace.


94 97 

95### Install and use a plugin in ChatGPT98### Install and use a plugin in ChatGPT

96 99 

97Once you open the plugin directory:100Once you open the Plugins Directory:

98 101 

99<WorkflowSteps>102<WorkflowSteps>

100 103 


1033. If the plugin needs a connector, connect it when prompted. Some plugins1063. If the plugin needs a connector, connect it when prompted. Some plugins

104 ask you to authenticate during install. Others wait until the first time you107 ask you to authenticate during install. Others wait until the first time you

105 use them.108 use them.

1064. After installation, start a new task and ask ChatGPT to use the plugin.1094. After installation, start a new chat and ask ChatGPT to use the plugin.

107 110 

108</WorkflowSteps>111</WorkflowSteps>

109 112 


179 180 

180### Remove a plugin181### Remove a plugin

181 182 

182To remove a plugin, reopen it from the plugin browser and select183To remove a plugin, open it from a supported plugin browser and select

183**Uninstall plugin** when that action is available. Workspace-installed or184**Uninstall plugin** when that action is available. Workspace-installed or

184default plugins may not offer that action; your workspace administrator controls185default plugins may not offer that action; your workspace administrator controls

185them instead.186them instead.

plugins/build.md +27 −26

Details

1# Build plugins1# Build plugins

2 2 

3This page is for plugin authors. If you want to browse, install, and use3This page is for plugin authors. If you want to browse, install, and use

4plugins in ChatGPT Work on the web or in Work or Codex in the ChatGPT desktop app, see4plugins in Work mode in ChatGPT on the web or in Work mode or Codex in the

5[Plugins](https://learn.chatgpt.com/docs/plugins). If you are still iterating on one repo or one personal5ChatGPT desktop app, see [Plugins](https://learn.chatgpt.com/docs/plugins). If you are still iterating on

6workflow, start with a local skill. Build a plugin when you want to share that6one repo or one personal workflow, start with a local skill. Build a plugin when

7workflow across teams, bundle connectors or MCP config, package lifecycle hooks,7you want to share that workflow across teams, bundle connectors or MCP config,

8or publish a stable package.8package lifecycle hooks, or publish a stable package.

9 9 

10A plugin can include skills, an MCP-backed app, or both. If your plugin needs10A plugin can include skills, an MCP-backed app, or both. If your plugin needs

11to connect to a service or expose tools through an MCP server, see11to connect to a service or expose tools through an MCP server, see


39 39 

40### Create and test a plugin locally that points to an MCP-server-backed dev-mode app40### Create and test a plugin locally that points to an MCP-server-backed dev-mode app

41 41 

42You can also use `$plugin-creator` if you want to test a plugin locally that42You can also use the plugin-creator skill if you want to test a plugin locally

43includes an MCP-server backed app. The plugin still needs a local plugin folder43that includes an MCP-server backed app. The plugin still needs a local plugin

44and manifest, but the app itself starts in ChatGPT developer mode.44folder and manifest, but the app itself starts in ChatGPT developer mode.

45 45 

46First, enable developer mode in ChatGPT:46First, enable developer mode in ChatGPT:

47 47 


584. After ChatGPT creates it, copy the app ID from the browser URL. It starts584. After ChatGPT creates it, copy the app ID from the browser URL. It starts

59 with `plugin_asdk_app`.59 with `plugin_asdk_app`.

60 60 

61Give that `plugin_asdk_app...` ID to `$plugin-creator` in ChatGPT or Codex. For61Give that `plugin_asdk_app...` ID to `@plugin-creator` in Work mode in ChatGPT

62example:62or `$plugin-creator` in Codex. For example, in Work mode:

63 63 

64<div class="not-prose my-6 overflow-hidden rounded-xl border border-subtle bg-surface shadow-sm">64<div class="not-prose my-6 overflow-hidden rounded-xl border border-subtle bg-surface shadow-sm">

65 <div class="border-b border-subtle bg-surface-secondary px-4 py-3">65 <div class="border-b border-subtle bg-surface-secondary px-4 py-3">


68 </span>68 </span>

69 </div>69 </div>

70 <div class="overflow-x-auto p-4 font-mono text-sm leading-6 text-primary">70 <div class="overflow-x-auto p-4 font-mono text-sm leading-6 text-primary">

71 <code class="whitespace-pre-wrap break-words">{`$plugin-creator create a Codex plugin for my ChatGPT app.71 <code class="whitespace-pre-wrap break-words">{`@plugin-creator create a Codex plugin for my ChatGPT app.

72Use plugin_asdk_app_6a4c0062f3b88191855c0a80eac5d53d and name it Acme Support.72Use plugin_asdk_app_6a4c0062f3b88191855c0a80eac5d53d and name it Acme Support.

73Include a personal marketplace entry so I can test it locally.`}</code>73Include a personal marketplace entry so I can test it locally.`}</code>

74 </div>74 </div>

75</div>75</div>

76 76 

77`$plugin-creator` will create the plugin folder, create the required77The plugin-creator skill will create the plugin folder, create the required

78`.codex-plugin/plugin.json`, and add app wiring for the ChatGPT app. If you ask78`.codex-plugin/plugin.json`, and add app wiring for the ChatGPT app. If you ask

79it to create a personal marketplace entry, the plugin appears in your local79it to create a personal marketplace entry, the plugin appears under your local

80plugin directory for testing.80source in the Plugins Directory for testing.

81 81 

82After `$plugin-creator` creates the plugin:82After the plugin-creator skill creates the plugin:

83 83 

841. Review `.app.json` and confirm it points at the correct841. Review `.app.json` and confirm it points at the correct

85 `plugin_asdk_app...` ID.85 `plugin_asdk_app...` ID.


87 `./.app.json`.87 `./.app.json`.

883. Add any bundled skills under `skills/` if the plugin should include883. Add any bundled skills under `skills/` if the plugin should include

89 repeatable workflows alongside the app.89 repeatable workflows alongside the app.

904. If `$plugin-creator` created a personal marketplace entry, refresh ChatGPT904. If the skill created a personal marketplace entry, refresh ChatGPT

91 and install the plugin from your local plugin directory. Then test it in a91 and install the plugin from your local source in the Plugins Directory. Then

92 new task.92 test it in a new chat.

93 93 

94For the manifest shape and file layout, see [Plugin structure](#plugin-structure)94For the manifest shape and file layout, see [Plugin structure](#plugin-structure)

95and [Path rules](#path-rules).95and [Path rules](#path-rules).


100for a single plugin, and you can keep adding entries to that same marketplace100for a single plugin, and you can keep adding entries to that same marketplace

101to build your own curated list for a repo, team, or personal workflow.101to build your own curated list for a repo, team, or personal workflow.

102 102 

103In Work or Codex in the ChatGPT desktop app, each marketplace appears as a103In Work mode or Codex in the ChatGPT desktop app, each marketplace appears as a

104selectable source in the plugin directory. Use104selectable source in the Plugins Directory. Use

105`$REPO_ROOT/.agents/plugins/marketplace.json` for a repo-scoped list or105`$REPO_ROOT/.agents/plugins/marketplace.json` for a repo-scoped list or

106`~/.agents/plugins/marketplace.json` for a personal list. Add one entry per106`~/.agents/plugins/marketplace.json` for a personal list. Add one entry per

107plugin under `plugins[]`, point each `source.path` at the plugin folder with a107plugin under `plugins[]`, point each `source.path` at the plugin folder with a

108`./`-prefixed path relative to the marketplace root, and set108`./`-prefixed path relative to the marketplace root, and set

109`interface.displayName` to the label you want the app to show in the marketplace109`interface.displayName` to the label you want the app to show in the marketplace

110picker. Then restart the ChatGPT desktop app. After that, open the plugin110picker. Then restart the ChatGPT desktop app. After that, open the Plugins

111directory, choose your marketplace, and browse or install the plugins in that111Directory, choose your marketplace, and browse or install the plugins in that

112curated list.112curated list.

113 113 

114You don't need a separate marketplace per plugin. One marketplace can expose a114You don't need a separate marketplace per plugin. One marketplace can expose a


116you add more plugins.116you add more plugins.

117 117 

118<CodexScreenshot118<CodexScreenshot

119 alt="custom local marketplace in the plugin directory"119 alt="custom local marketplace in the Plugins Directory"

120 lightSrc="/images/codex/plugins/codex-local-plugin-light.png"120 lightSrc="/images/codex/plugins/codex-local-plugin-light.png"

121 darkSrc="/images/codex/plugins/codex-local-plugin.png"121 darkSrc="/images/codex/plugins/codex-local-plugin.png"

122/>122/>


294 294 

295### Share a local plugin with your workspace295### Share a local plugin with your workspace

296 296 

297After you create a plugin and add it to Work or Codex, you can share it with297After you create a plugin, add it from the ChatGPT desktop app. Select ChatGPT

298other members of your ChatGPT workspace from the ChatGPT desktop app.298and switch to Work mode, or select Codex, then open **Plugins**. You can then

299share it with other members of your ChatGPT workspace.

299 300 

3001. Open **Plugins** in the ChatGPT desktop app.3011. Open **Plugins** in the ChatGPT desktop app.

3012. Go to **Created by you** and open the plugin details page.3022. Go to **Created by you** and open the plugin details page.


3045. Choose who has access, then send the invitation or link.3055. Choose who has access, then send the invitation or link.

305 306 

306People you share with can find the plugin under **Shared with you** in the307People you share with can find the plugin under **Shared with you** in the

307plugin directory. Sharing a local plugin with your workspace doesn't publish308Plugins Directory. Sharing a local plugin with your workspace doesn't publish

308it to the public Plugins Directory. Shared plugins stay within your workspace309it to the public Plugins Directory. Shared plugins stay within your workspace

309and organization boundary; accounts that aren't signed in to that workspace310and organization boundary; accounts that aren't signed in to that workspace

310can't access them. Use groups when a team or role should share the same plugin311can't access them. Use groups when a team or role should share the same plugin

projects.md +37 −31

Details

1# Projects, chats, and tasks1# Projects and chats

2 2 

3Use a project to organize related tasks and give ChatGPT the context it needs.3Use a project to organize related chats and give ChatGPT the context it needs.

4The **Projects** view in the ChatGPT desktop app includes ChatGPT projects and4The **Projects** view in the ChatGPT desktop app includes ChatGPT projects and

5local projects that connect to folders on your computer.5local projects that connect to folders on your computer.

6 6 

7## Choose a project or start without one7## Choose a project or start without one

8 8 

9Create a project when work will continue over time, produce more than one9Create a project when work will continue over time, produce more than one

10output, or depend on the same files and sources. Start a task without a project10output, or depend on the same files and sources. Start a chat without a project

11when the work is self-contained and doesn't need shared project context.11when the work is self-contained and doesn't need shared project context.

12 12 

13 13 


25## Work in a project25## Work in a project

26 26 

27The **Projects** view brings ChatGPT projects and local projects into one place.27The **Projects** view brings ChatGPT projects and local projects into one place.

28ChatGPT projects carry project files and context across related tasks. A local28ChatGPT projects carry project files and context across related chats. A local

29project gives tasks access to one or more folders on your computer, such as a29project gives chats access to one or more folders on your computer, such as a

30collection of source files or a codebase.30collection of source files or a codebase.

31 31 

32Start a separate task for each distinct outcome so its messages and results stay32Start a separate chat for each distinct outcome so its messages and results stay

33focused while the project keeps related work organized.33focused while the project keeps related work organized.

34 34 

35<CodexScreenshot35<CodexScreenshot

36 alt="ChatGPT desktop app showing multiple projects in the sidebar and tasks in the main pane"36 alt="ChatGPT desktop app showing multiple projects in the sidebar and chats in the main pane"

37 lightSrc="/images/codex/app/multitask-light.webp"37 lightSrc="/images/codex/app/multitask-light.webp"

38 darkSrc="/images/codex/app/multitask-dark.webp"38 darkSrc="/images/codex/app/multitask-dark.webp"

39 maxHeight="400px"39 maxHeight="400px"


53 53 

54 54 

55 55 

56## Organize projects and tasks56<a id="organize-projects-and-tasks"></a>

57 

58## Organize projects and chats

57 59 

58Keep active work visible and move finished work out of the way:60Keep active work visible and move finished work out of the way:

59 61 

60- **Pin a project** to keep it near the top of the sidebar. You can also pin it62- **Pin a project** to keep it near the top of the sidebar. You can also pin it

61 from the Projects view.63 from the Projects view.

62- **Pin a task** when you return to it often, even if newer tasks appear in the64- **Pin a chat** when you return to it often, even if newer chats appear in the

63 project.65 project.

64- **Rename a task** with a short title that describes its outcome, such as “Q366- **Rename a chat** with a short title that describes its outcome, such as “Q3

65 launch brief” or “Checkout accessibility review.”67 launch brief” or “Checkout accessibility review.”

66- **Search projects** from the Projects view. Press68- **Search projects** from the Projects view. Press

67 <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>G</kbd> to search past tasks when you69 <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>+<kbd>G</kbd> to search past chats when you

68 remember a phrase or branch name but not the title.70 remember a phrase or branch name but not the title.

69- **Archive a task** when you finish the work. From a project's menu, select71- **Archive a chat** when you finish the work. From a project's menu, select

70 **Archive tasks** to archive its tasks together.72 **Archive chats** to archive its chats together.

71 73 

72Pinning doesn't add context or change what ChatGPT can access. It only changes74Pinning doesn't add context or change what ChatGPT can access. It only changes

73where the project or task appears in the sidebar.75where the project or chat appears in the sidebar.

74 76 

75Restore archived tasks from **Settings > Archived tasks**.77Restore archived chats from **Settings > Archived chats**.

76 78 

77 79 

78 80 


88 90 

89Add a local project when ChatGPT needs to read or change files in a folder on91Add a local project when ChatGPT needs to read or change files in a folder on

90your computer. For a codebase, the project folder becomes the working directory92your computer. For a codebase, the project folder becomes the working directory

91for Codex tasks.93for Codex chats.

92 94 

93If a repository contains more than one app or package, use distinct local95If a repository contains more than one app or package, use distinct local

94projects when each task should access only one part of the repository. This96projects when each chat should access only one part of the repository. This

95keeps the working context focused. Use [local environments](https://learn.chatgpt.com/docs/environments/local-environment)97keeps the working context focused. Use [local environments](https://learn.chatgpt.com/docs/environments/local-environment)

96to define setup actions and common commands for a project.98to define setup actions and common commands for a project.

97 99 

98When you want to isolate code changes from your current checkout, select Codex100When you want to isolate code changes from your current checkout, select Codex

99and start the task in a [worktree](https://learn.chatgpt.com/docs/environments/git-worktrees). Projects and worktrees organize work,101and start the chat in a [worktree](https://learn.chatgpt.com/docs/environments/git-worktrees). Projects and worktrees organize work,

100but the [sandbox](https://learn.chatgpt.com/docs/sandboxing) enforces what local commands can102but the [sandbox](https://learn.chatgpt.com/docs/sandboxing) enforces what local commands can

101read, change, or access over the network.103read, change, or access over the network.

102 104 


105<a id="start-without-a-project"></a>107<a id="start-without-a-project"></a>

106 108 

107 109 

108## Start a task without a project110<a id="start-a-task-without-a-project"></a>

111 

112## Start a chat without a project

109 113 

110Select **New task** when the work is self-contained and doesn't need shared114Select **New chat** when the work is self-contained and doesn't need shared

111project files, instructions, or folder access. Create a project first when115project files, instructions, or folder access. Create a project first when

112several tasks will depend on the same context.116several chats will depend on the same context.

113 117 

114 118 

115 119 


119<a id="start-a-standalone-chat"></a>123<a id="start-a-standalone-chat"></a>

120 124 

121 125 

122## Use Quick Chat for a quick conversation126<a id="use-quick-chat-for-a-quick-conversation"></a>

127 

128## Use Quick chat for a quick question

129 

130Quick chat opens an ordinary ChatGPT chat. ChatGPT chats don't appear in the

131Codex sidebar, which contains your Codex chats and projects.

123 132 

124Quick Chat opens an ordinary ChatGPT chat, separate from Work and Codex tasks.133Point to **New chat**, then select the **Quick chat** icon on its right. You can

125Use it for quick questions and ideas that don't need a project or durable task134also press

126context.

127 135 

128Select **Chat** in the sidebar. You can also press <kbd>Cmd+Option+N</kbd> on136<kbd>Cmd+Option+N</kbd> on macOS or <kbd>Ctrl+Alt+N</kbd> on Windows. From **New

129macOS or <kbd>Ctrl+Alt+N</kbd> on Windows. If a conversation becomes part of137chat**, you can open an existing ChatGPT chat and add it to a Codex chat.

130larger work, select **Add to task** to bring it into the current task. Open

131**Recent chats** from Quick Chat to return to an earlier conversation.

132 138 

133 139 

134 140 


136 142 

137 143 

138 144 

139- Attach files or [image inputs](https://learn.chatgpt.com/docs/image-inputs) directly to a task145- Attach files or [image inputs](https://learn.chatgpt.com/docs/image-inputs) directly to a chat

140 when they apply only to that request.146 when they apply only to that request.

141- Install [plugins](https://learn.chatgpt.com/docs/plugins) to bring in context and actions from other147- Install [plugins](https://learn.chatgpt.com/docs/plugins) to bring in context and actions from other

142 services.148 services.

143- Configure [MCP](https://learn.chatgpt.com/docs/extend/mcp) servers when your organization or developer setup149- Configure [MCP](https://learn.chatgpt.com/docs/extend/mcp) servers when your organization or developer setup

144 exposes tools through Model Context Protocol.150 exposes tools through Model Context Protocol.

145- Use [memories](https://learn.chatgpt.com/docs/customization/memories), where available, to carry useful context from151- Use [memories](https://learn.chatgpt.com/docs/customization/memories), where available, to carry useful context from

146 past work into future tasks.152 past work into future chats.

147 153 

148 154 

149 155 

prompting.md +19 −15

Details

49 relying on the image alone.49 relying on the image alone.

50- Ask ChatGPT to use [web search](https://learn.chatgpt.com/docs/web-search) when the answer depends on50- Ask ChatGPT to use [web search](https://learn.chatgpt.com/docs/web-search) when the answer depends on

51 current information, and ask for sources when you need to check the result.51 current information, and ask for sources when you need to check the result.

52- Use a [project](https://learn.chatgpt.com/docs/projects) when related chats or tasks should share files,52- Use a [project](https://learn.chatgpt.com/docs/projects) when related chats should share files,

53 sources, or a local folder.53 sources, or a local folder.

54 54 

55### Use connected sources55### Use connected sources


81 81 

82### Personalize ChatGPT82### Personalize ChatGPT

83 83 

84Put preferences that should apply across chats and tasks in **Settings > Personalization**84Put preferences that should apply across chats in **Settings > Personalization**

85as custom instructions. Keep details that matter only to the current task in the85as custom instructions. Keep details that matter only to the current chat in the

86prompt.86prompt.

87 87 

88[<IconItem title="Review personalization settings" className="mt-4">88[<IconItem title="Review personalization settings" className="mt-4">


229ingredients across meals, and finish with one consolidated shopping list.229ingredients across meals, and finish with one consolidated shopping list.

230```230```

231 231 

232## Prompting for Work232<a id="prompting-for-work"></a>

233 233 

234Use Chat for quick questions, short rewrites, brainstorming, and lightweight234## Prompting in Work mode

235drafts. Use Work for tasks that draw on different sources or tools, involve a235 

236Use Chat mode for quick questions, short rewrites, brainstorming, and lightweight

237drafts. Use Work mode for tasks that draw on different sources or tools, involve a

236sequence of steps, make changes, or produce a larger deliverable.238sequence of steps, make changes, or produce a larger deliverable.

237 239 

238For Work tasks, describe the result you need, provide the source material, name240In Work mode, describe the result you need, provide the source material, name

239the audience, and explain how you'll review the work. Ask ChatGPT to plan,241the audience, and explain how you'll review the work. Ask ChatGPT to plan,

240gather the needed information, create files, and check them before it finishes.242gather the needed information, create files, and check them before it finishes.

241 243 

242### Use Work efficiently244<a id="use-work-efficiently"></a>

245 

246### Use Work mode efficiently

243 247 

244Work is useful for time-consuming or recurring tasks, or for finished files you248Work mode is useful for time-consuming or recurring tasks, or for finished files you

245can reuse. A task that uses more credits can still be worthwhile if it saves249can reuse. A task that uses more credits can still be worthwhile if it saves

246time, improves quality, or helps you make an important decision.250time, improves quality, or helps you make an important decision.

247 251 


285for launch day. Flag any missing decisions before producing the final files.289for launch day. Flag any missing decisions before producing the final files.

286```290```

287 291 

288For recurring work, first refine the prompt in a normal task. After the output is292For recurring work, first refine the prompt in a normal chat. After the output is

289reliable, [schedule work from that task](https://learn.chatgpt.com/docs/automations#schedule-work-from-a-task).293reliable, [schedule a task inside that chat](https://learn.chatgpt.com/docs/automations#schedule-a-task-inside-a-chat).

290Create a standalone scheduled task instead when each scheduled run should start294Create a standalone scheduled task instead when each scheduled run should start

291a new task.295a new chat.

292 296 

293<a id="use-editor-context"></a>297<a id="use-editor-context"></a>

294 298 


528 532 

529<WorkflowSteps>533<WorkflowSteps>

530 534 

5311. Attach the image in the Codex task (drag-and-drop or paste).5351. Attach the image in the Codex chat (drag-and-drop or paste).

5322. Prompt Codex:5362. Prompt Codex:

533 537 

534 ```text538 ```text


592 596 

593### Delegate refactor to the cloud597### Delegate refactor to the cloud

594 598 

595Use this when you want to design an approach with local context, then delegate the long implementation to a cloud task that can run in parallel.599Use this when you want to design an approach with local context, then delegate the long implementation to a cloud chat that can run in parallel.

596 600 

597#### Local planning (IDE)601#### Local planning (IDE)

598 602 


635 639 

6361. If you haven't already done so, set up a [Codex cloud environment](https://learn.chatgpt.com/docs/environments/cloud-environment).6401. If you haven't already done so, set up a [Codex cloud environment](https://learn.chatgpt.com/docs/environments/cloud-environment).

6372. Click on the cloud icon beneath the prompt composer and select your cloud environment.6412. Click on the cloud icon beneath the prompt composer and select your cloud environment.

6383. When you enter the next prompt, Codex creates a new task in the cloud that carries over the existing task context (including the plan and any local source changes).6423. When you enter the next prompt, Codex creates a new chat in the cloud that carries over the existing chat context (including the plan and any local source changes).

639 643 

640 ```text644 ```text

641 Implement Milestone 1 from the plan.645 Implement Milestone 1 from the plan.

quickstart.md +11 −8

Details

28>28>

29 <div slot="app">29 <div slot="app">

30The ChatGPT desktop app is available for Windows and macOS. Use it for projects,30The ChatGPT desktop app is available for Windows and macOS. Use it for projects,

31local files, longer tasks, and quick conversations.31local files, longer tasks, and quick chats.

32 32 

33<WorkflowSteps variant="headings">33<WorkflowSteps variant="headings">

341. <h3 id="setup-app-install">Install the ChatGPT desktop app</h3>341. <h3 id="setup-app-install">Install the ChatGPT desktop app</h3>


45 45 

463. <h3 id="setup-app-select-workspace">Select where ChatGPT should work</h3>463. <h3 id="setup-app-select-workspace">Select where ChatGPT should work</h3>

47 47 

48 Start a task, create a project, or open a folder. ChatGPT can read and modify48 Start a chat, create a project, or open a folder. ChatGPT can read and modify

49 files in the folder you choose. [Learn more about tasks and projects](https://learn.chatgpt.com/docs/projects).49 files in the folder you choose. [Learn more about chats and projects](https://learn.chatgpt.com/docs/projects).

50 50 

514. <h3 id="setup-app-start-task">Start your task</h3>514. <h3 id="setup-app-start-task">Start a chat</h3>

52 52 

53 <div class="grid gap-5 md:grid-cols-[minmax(0,1fr)_minmax(17rem,20rem)] md:items-start">53 <div class="grid gap-5 md:grid-cols-[minmax(0,1fr)_minmax(17rem,20rem)] md:items-start">

54 54 

55 <div>55 <div>

56 56 

57 - For research, analysis, or deliverables such as documents, presentations,57 - For research, analysis, or deliverables such as documents, presentations,

58 spreadsheets, and Sites, select **ChatGPT Work** from the ChatGPT dropdown.58 spreadsheets, and Sites, select **ChatGPT**, then select **Work** from the mode

59 toggle at the top of the new chat page, above the composer.

59 - For software development with codebase context and developer tools, select60 - For software development with codebase context and developer tools, select

60 **Codex** from the ChatGPT dropdown.61 **Codex** from the ChatGPT dropdown.

61 - For a quick question or conversation, open **Chat** separately.62 - For a quick question or chat, select **ChatGPT**, then select **Chat**

63 from the mode toggle at the top of the new chat page, above the composer. In

64 Codex, point to **New chat**, then select the **Quick chat** icon on its right.

62 65 

63 Learn more about [using ChatGPT](https://learn.chatgpt.com/docs/use-chatgpt).66 Learn more about [using ChatGPT](https://learn.chatgpt.com/docs/use-chatgpt).

64 67 


102 </div>105 </div>

103 106 

104 <div slot="web">107 <div slot="web">

105ChatGPT is available on the web and includes Chat and ChatGPT Work.108ChatGPT is available on the web and includes Chat mode and Work mode.

106 109 

107<WorkflowSteps variant="headings">110<WorkflowSteps variant="headings">

1081. <h3 id="setup-web-sign-in">Open ChatGPT and sign in</h3>1111. <h3 id="setup-web-sign-in">Open ChatGPT and sign in</h3>

109 112 

110Go to [chatgpt.com](https://chatgpt.com) and sign in with your ChatGPT account.113Go to [chatgpt.com](https://chatgpt.com) and sign in with your ChatGPT account.

111 114 

1122. <h3 id="setup-web-start-task">Start your task</h3>1152. <h3 id="setup-web-start-task">Start a chat</h3>

113 116 

114 <div class="grid gap-5 md:grid-cols-[minmax(0,1fr)_minmax(17rem,20rem)] md:items-stretch">117 <div class="grid gap-5 md:grid-cols-[minmax(0,1fr)_minmax(17rem,20rem)] md:items-stretch">

115 118 

Details

22 22 

23<WorkflowSteps>23<WorkflowSteps>

24 24 

251. In the ChatGPT desktop app, select ChatGPT Work or Codex and open **Plugins**.251. In the ChatGPT desktop app, select ChatGPT and switch to Work mode, or select Codex. Then open **Plugins**.

262. Open the **+** menu.262. Open the **+** menu.

273. Select **Record a skill**.273. Select **Record a skill**.

284. Review the suggested prompt, give Codex any helpful context, and submit it.284. Review the suggested prompt, give Codex any helpful context, and submit it.


45 45 

46## Replay the workflow46## Replay the workflow

47 47 

48Start a new task and ask Codex to use the generated skill. Give it the48Start a new chat and ask Codex to use the generated skill. Give it the

49values that are different this time, such as the file to upload, the issue to49values that are different this time, such as the file to upload, the issue to

50create, or the date range for the report.50create, or the date range for the report.

51 51 

Details

20 20 

21To remove a project from the sidebar, hover over the name of your project, click21To remove a project from the sidebar, hover over the name of your project, click

22the three dots and choose "Remove." To restore it, re-add the22the three dots and choose "Remove." To restore it, re-add the

23project using the **Add new project** button next to **Tasks** or using23project using the **Add new project** button next to **Chats** or using

24 24 

25<kbd>Cmd</kbd>+<kbd>O</kbd>.25<kbd>Cmd</kbd>+<kbd>O</kbd>.

26 26 

27<a id="find-archived-threads"></a>27<a id="find-archived-threads"></a>

28<a id="find-archived-chats"></a>28<a id="find-archived-tasks"></a>

29 29 

30### Find archived tasks30### Find archived chats

31 31 

32Archived tasks can be found in [Settings](codex://settings). When you unarchive32Archived chats can be found in [Settings](codex://settings). When you unarchive

33a task, it reappears in its original sidebar location.33a chat, it reappears in its original sidebar location.

34 34 

35<a id="only-some-threads-appear-in-the-sidebar"></a>35<a id="only-some-threads-appear-in-the-sidebar"></a>

36<a id="only-some-chats-appear-in-the-sidebar"></a>36<a id="only-some-tasks-appear-in-the-sidebar"></a>

37 37 

38### Only some tasks appear in the sidebar38### Only some chats appear in the sidebar

39 39 

40The sidebar lets you filter tasks based on the state of a project. If you're40The sidebar lets you filter chats based on the state of a project. If you're

41missing tasks, select the filter icon next to **Tasks**, then select41missing chats, select the filter icon next to **Chats**, then select

42**Chronological**. If you still don't see the task, open42**Chronological**. If you still don't see the chat, open

43[Settings](codex://settings) and check **Archived tasks**.43[Settings](codex://settings) and check **Archived chats**.

44 44 

45### Code doesn't run on a worktree45### Code doesn't run on a worktree

46 46 


76 76 

77### Recover a prompt after selecting the wrong target77### Recover a prompt after selecting the wrong target

78 78 

79If you started a task with the wrong target (**Local**, **Worktree**, or **Cloud**) by accident, you can cancel the current run and recover your previous prompt by pressing the up arrow key in the composer.79If you started a chat with the wrong target (**Local**, **Worktree**, or **Cloud**) by accident, you can cancel the current run and recover your previous prompt by pressing the up arrow key in the composer.

80 80 

81### Feature is working in the Codex CLI but not in the ChatGPT desktop app81### Feature is working in the Codex CLI but not in the ChatGPT desktop app

82 82 


100## Feedback and logs100## Feedback and logs

101 101 

102Type <kbd>/</kbd> into the message composer to provide feedback for the team. If102Type <kbd>/</kbd> into the message composer to provide feedback for the team. If

103you trigger feedback in an existing conversation, you can choose to share the103you trigger feedback in an existing chat, you can choose to share the

104existing session along with your feedback. After submitting your feedback,104existing session along with your feedback. After submitting your feedback,

105you'll receive a session ID that you can share with the team.105you'll receive a session ID that you can share with the team.

106 106 


120 120 

121## Stuck states and recovery patterns121## Stuck states and recovery patterns

122 122 

123If a task appears stuck:123If a chat appears stuck:

124 124 

1251. Check whether Codex is waiting for an approval.1251. Check whether Codex is waiting for an approval.

1262. Open the terminal and run a basic command like `git status`.1262. Open the terminal and run a basic command like `git status`.

1273. Start a new task with a smaller, more focused prompt.1273. Start a new chat with a smaller, more focused prompt.

128 128 

129If you cancel worktree creation by mistake and lose your prompt, press the up129If you cancel worktree creation by mistake and lose your prompt, press the up

130arrow key in the composer to recover it.130arrow key in the composer to recover it.


140If commands behave differently than expected, validate the current directory and140If commands behave differently than expected, validate the current directory and

141branch in the terminal first.141branch in the terminal first.

142 142 

143If it continues to be stuck, wait until your active tasks are complete and restart the app.143If it continues to be stuck, wait until your active chats are complete and restart the app.

144 144 

145**Fonts aren't rendering correctly**145**Fonts aren't rendering correctly**

146 146 

Details

1# Remote connections1# Remote connections

2 2 

3Remote connections let you access work running on another device or machine.3Remote connections let you access work running on another device or machine.

4In the ChatGPT mobile app, open **Remote** to work with ChatGPT Work or Codex tasks on4In the ChatGPT mobile app, open **Remote** to work with ChatGPT or Codex chats on

5a connected Mac or Windows device. You can also continue work from another5a connected Mac or Windows device. You can also continue work from another

6supported device running the ChatGPT desktop app or connect the app to projects6supported device running the ChatGPT desktop app or connect the app to projects

7on an SSH host.7on an SSH host.

8 8 

9Remote access uses the connected host's projects, tasks, files, credentials,9Remote access uses the connected host's projects, chats, files, credentials,

10permissions, plugins, Computer Use, browser setup, and local tools.10permissions, plugins, Computer Use, browser setup, and local tools.

11 11 

12## What you can do remotely12## What you can do remotely

13 13 

14- Start new tasks in projects on the host, or continue existing ones.14- Start new chats in projects on the host, or continue existing ones.

15- Send follow-up instructions, answer questions, and steer active work.15- Send follow-up instructions, answer questions, and steer active work.

16- Approve commands and other actions.16- Approve commands and other actions.

17- Review outputs, diffs, test results, terminal output, and screenshots.17- Review outputs, diffs, test results, terminal output, and screenshots.

18- Get notified when ChatGPT completes a task or needs your attention.18- Get notified when ChatGPT completes a task or needs your attention.

19- Switch between connected hosts and tasks.19- Switch between connected hosts and chats.

20 20 

21The next sections cover opening **Remote** in the ChatGPT mobile app to access a21The next sections cover opening **Remote** in the ChatGPT mobile app to access a

22desktop host. To connect Codex to a project on an SSH host, see22desktop host. To connect Codex to a project on an SSH host, see


111### <span class="not-prose inline-flex items-center gap-3 align-middle"><span class="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-surface-secondary text-secondary"><Desktop width={17} height={17} /></span><span>Your laptop or desktop</span></span>111### <span class="not-prose inline-flex items-center gap-3 align-middle"><span class="inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-surface-secondary text-secondary"><Desktop width={17} height={17} /></span><span>Your laptop or desktop</span></span>

112 112 

113Connect the Mac or Windows PC where the desktop app is already installed. This113Connect the Mac or Windows PC where the desktop app is already installed. This

114gives remote access to the same projects, tasks, credentials, plugins, and local114gives remote access to the same projects, chats, credentials, plugins, and local

115setup you already use.115setup you already use.

116 116 

117If that computer sleeps, loses network access, or closes the app, remote access117If that computer sleeps, loses network access, or closes the app, remote access


172 172 

173You can continue work from another signed-in device running the ChatGPT desktop173You can continue work from another signed-in device running the ChatGPT desktop

174app and supporting remote control. For example, if your laptop is unavailable, you can174app and supporting remote control. For example, if your laptop is unavailable, you can

175start a task from your phone on an always-on host, then later open the app on175start a chat from your phone on an always-on host, then later open the app on

176your laptop and continue that same task there.176your laptop and continue that same chat there.

177 177 

178On a Mac or Windows device where the feature is available, use **Settings >178On a Mac or Windows device where the feature is available, use **Settings >

179Connections > Control other devices** to add the other host. A device can allow179Connections > Control other devices** to add the other host. A device can allow


188 188 

189## Connect to an SSH host189## Connect to an SSH host

190 190 

191In the ChatGPT desktop app, add remote projects from an SSH host and run tasks191In the ChatGPT desktop app, add remote projects from an SSH host and run chats

192against the remote filesystem and shell. Remote project tasks run commands,192against the remote filesystem and shell. Remote project chats run commands,

193read files, and write changes on the remote host.193read files, and write changes on the remote host.

194 194 

195Keep the remote host configured with the same security expectations you use for195Keep the remote host configured with the same security expectations you use for


236 236 

237<a id="hand-off-a-thread-between-hosts"></a>237<a id="hand-off-a-thread-between-hosts"></a>

238<a id="hand-off-a-chat-between-hosts"></a>238<a id="hand-off-a-chat-between-hosts"></a>

239<a id="hand-off-a-task-between-hosts"></a>

239 240 

240## Hand off a task between hosts241## Hand off a chat between hosts

241 242 

242Handoff moves an existing task and its Git state between your local computer243Handoff moves an existing chat and its Git state between your local computer

243and a connected remote host. Use it to start work locally, continue in a244and a connected remote host. Use it to start work locally, continue in a

244worktree on a remote computer, and bring the task back later.245worktree on a remote computer, and bring the chat back later.

245 246 

246Before you hand off a task, connect the destination host and save a project247Before you hand off a chat, connect the destination host and save a project

247for the same Git repository on that host. If the project is a subdirectory of248for the same Git repository on that host. If the project is a subdirectory of

248the repository, save the same subdirectory on both hosts. Codex only shows249the repository, save the same subdirectory on both hosts. Codex only shows

249destinations with a matching saved project.250destinations with a matching saved project.

250 251 

251To hand off a task:252To hand off a chat:

252 253 

2531. Open the task in the desktop app.2541. Open the chat in the desktop app.

2542. In the task footer, select the current run location, then select the2552. In the chat footer, select the current run location, then select the

255 destination host. Select **This computer** when handing a remote task back256 destination host. Select **This computer** when handing a remote chat back

256 to your local computer.257 to your local computer.

2573. Review the destination and branch, then select **Hand off**.2583. Review the destination and branch, then select **Hand off**.

258 259 

259Codex creates or reuses a worktree on the destination host, transfers the260Codex creates or reuses a worktree on the destination host, transfers the

260task and Git state, and switches the task to that host. If the task is261chat and Git state, and switches the chat to that host. If the chat is

261running, handoff interrupts the current response before transferring it.262running, handoff interrupts the current response before transferring it.

262 263 

263You can also ask Codex in another task to hand off a named task to a264You can also ask Codex in another chat to hand off a named chat to a

264connected host. Codex can't hand off the task making the request, and handoff265connected host. Codex can't hand off the chat making the request, and handoff

265to a Codex cloud environment isn't supported.266to a Codex cloud environment isn't supported.

266 267 

267## Authentication and network exposure268## Authentication and network exposure

sandboxing.md +1 −1

Details

1# Sandbox1# Sandbox

2 2 

3The sandbox is the boundary that lets the agent act autonomously without giving it3The sandbox is the boundary that lets the agent act autonomously without giving it

4unrestricted access to your machine. When a local task runs commands in the4unrestricted access to your machine. When a local chat runs commands in the

5**ChatGPT desktop app**, **Codex CLI**, or **IDE extension**, those commands run inside a5**ChatGPT desktop app**, **Codex CLI**, or **IDE extension**, those commands run inside a

6constrained environment instead of running with full access by default.6constrained environment instead of running with full access by default.

7 7 

Details

73also perform read-only checks to gather missing context, but it does so rarely.73also perform read-only checks to gather missing context, but it does so rarely.

74 74 

75Hidden assistant reasoning is not included. Auto-review sees retained75Hidden assistant reasoning is not included. Auto-review sees retained

76conversation items and tool evidence, not private chain-of-thought.76chat items and tool evidence, not private chain-of-thought.

77 77 

78## Denials and failure behavior78## Denials and failure behavior

79 79 

security.md +4 −2

Details

18- [Triage a backlog](https://learn.chatgpt.com/docs/security/plugin/triage-backlog) when you have existing security findings to review.18- [Triage a backlog](https://learn.chatgpt.com/docs/security/plugin/triage-backlog) when you have existing security findings to review.

19- [Fix and verify findings](https://learn.chatgpt.com/docs/security/plugin/fix-findings) with bounded patches for approved findings.19- [Fix and verify findings](https://learn.chatgpt.com/docs/security/plugin/fix-findings) with bounded patches for approved findings.

20- [Export or track findings](https://learn.chatgpt.com/docs/security/plugin/export-findings) as portable artifacts or approval-gated tracking destinations.20- [Export or track findings](https://learn.chatgpt.com/docs/security/plugin/export-findings) as portable artifacts or approval-gated tracking destinations.

21- [Write vulnerability reports](https://learn.chatgpt.com/docs/security/plugin/vulnerability-reports) from supplied findings, disclosure notes, source, and PoCs.

22- [Propose security hardening](https://learn.chatgpt.com/docs/security/plugin/security-hardening) from scan results or other security evidence.

21- [See what's new](https://learn.chatgpt.com/docs/security/plugin/changelog) in the Codex Security plugin.23- [See what's new](https://learn.chatgpt.com/docs/security/plugin/changelog) in the Codex Security plugin.

22 24 

23The plugin runs in your Codex task. Codex Security cloud scans connected25The plugin runs in your Codex chat. Codex Security cloud scans connected

24 GitHub repositories through Codex cloud. For Codex sandboxing, approvals,26 GitHub repositories through Codex cloud. For Codex sandboxing, approvals,

25 network controls, and admin settings, see [Agent approvals &27 network controls, and admin settings, see [Agent approvals &

26 security](https://learn.chatgpt.com/docs/agent-approvals-security).28 security](https://learn.chatgpt.com/docs/agent-approvals-security).


58- [Codex Security plugin quickstart](https://learn.chatgpt.com/docs/security/plugin) walks through installation and a first local scan.60- [Codex Security plugin quickstart](https://learn.chatgpt.com/docs/security/plugin) walks through installation and a first local scan.

59- [Codex Security cloud setup](https://learn.chatgpt.com/docs/security/setup) details setup, scanning, and findings review.61- [Codex Security cloud setup](https://learn.chatgpt.com/docs/security/setup) details setup, scanning, and findings review.

60- [Improving the threat model](https://learn.chatgpt.com/docs/security/threat-model) explains how to tune scope, attack surface, and criticality assumptions.62- [Improving the threat model](https://learn.chatgpt.com/docs/security/threat-model) explains how to tune scope, attack surface, and criticality assumptions.

61- [FAQ](https://learn.chatgpt.com/docs/security/faq) covers common product questions.63- [Codex Security cloud FAQ](https://learn.chatgpt.com/docs/security/faq) covers common cloud product questions.

Details

48 },48 },

49 {49 {

50 title: "Internet access",50 title: "Internet access",

51 description: "Control which domains cloud tasks can reach.",51 description: "Control which domains cloud chats can reach.",

52 href: "/codex/cloud/internet-access",52 href: "/codex/cloud/internet-access",

53 icon: "webSearch",53 icon: "webSearch",

54 },54 },


66 icon: "shieldCheck",66 icon: "shieldCheck",

67 },67 },

68 {68 {

69 title: "FAQ",69 title: "Codex Security cloud FAQ",

70 description:70 description:

71 "Get answers about scans, findings, privacy, and access.",71 "Get answers about cloud scans, findings, privacy, and access.",

72 href: "/codex/security/faq",72 href: "/codex/security/faq",

73 icon: "chat",73 icon: "chat",

74 },74 },

security/faq.md +10 −1

Details

1# FAQ1# Codex Security cloud FAQ

2 

3This FAQ covers Codex Security cloud. For local scans and workflows that run in

4a Codex task, see the [Codex Security plugin quickstart](https://learn.chatgpt.com/docs/security/plugin).

5 

6{/* vale Microsoft.Auto = NO */}

7{/* vale Vale.Spelling = NO */}

2 8 

3## Getting started9## Getting started

4 10 


102### What happens if validation fails?108### What happens if validation fails?

103 109 

104The finding remains unvalidated. Logs and reports still capture what was attempted so engineers can retry, investigate further, or adjust the reproduction steps.110The finding remains unvalidated. Logs and reports still capture what was attempted so engineers can retry, investigate further, or adjust the reproduction steps.

111 

112{/* vale Microsoft.Auto = YES */}

113{/* vale Vale.Spelling = YES */}

Details

8This quickstart takes you through one recommended first run: an ordinary,8This quickstart takes you through one recommended first run: an ordinary,

9read-only scan of a local repository in Codex.9read-only scan of a local repository in Codex.

10 10 

11This page covers the plugin that runs in a local Codex task. To scan a11This page covers the plugin that runs in a local Codex chat. To scan a

12 connected GitHub repository in Codex cloud, see [Codex Security cloud12 connected GitHub repository in Codex cloud, see [Codex Security cloud

13 setup](https://learn.chatgpt.com/docs/security/setup).13 setup](https://learn.chatgpt.com/docs/security/setup).

14 14 


33 </ButtonLink>33 </ButtonLink>

34 </div>34 </div>

35 35 

363. Start a new task in Codex for that repository (don't continue in a task that363. Start a new chat in Codex for that repository (don't continue in a chat that

37 was already open).37 was already open).

38 38 

39 39 


58 58 

591. Ask for an ordinary scan591. Ask for an ordinary scan

60 60 

61 Send this prompt in the new task:61 Send this prompt in the new chat:

62 62 

63 ```text63 ```text

64 Run a Codex Security scan on this repository.64 Run a Codex Security scan on this repository.


93 93 

943. Let the scan finish943. Let the scan finish

95 95 

96 The scan can take time. Keep the task running until the workspace reports96 The scan can take time. Keep the scan running until the workspace reports

97 completion. If Codex identifies a configuration limitation, review the exact97 completion. If Codex identifies a configuration limitation, review the exact

98 limitation and proposed change before allowing it to update your98 limitation and proposed change before allowing it to update your

99 configuration.99 configuration.

100 100 

1014. Review the result1014. Review the result

102 102 

103 Use the UI to browse findings or open the generated report for a complete,103 Use the UI to browse findings, or open `report.md` as the entry point to the

104 portable review.104 complete scan directory.

105 105 

106 <figure className="not-prose my-6">106 <figure className="not-prose my-6">

107 <div className="overflow-hidden rounded-xl border border-subtle bg-surface">107 <div className="overflow-hidden rounded-xl border border-subtle bg-surface">


139 139 

140 140 

141 141 

142- `report.md`, a complete portable report for sharing or archiving.142- `report.md`, the primary readable entry point to the scan results.

143- `findings/<slug>/`, with one detailed vulnerability report per reportable

144 finding and supporting proof-of-concept files when available.

145- `hardening/`, with a structural hardening portfolio and supporting proposals

146 or diagrams when the scan has reportable findings.

143- Structured scan data in `scan-manifest.json`, `findings.json`, and147- Structured scan data in `scan-manifest.json`, `findings.json`, and

144 `coverage.json` for automation and integrations. You normally don't need to148 `coverage.json` for automation and integrations. You normally don't need to

145 open these files yourself.149 open these files yourself.

146 150 

151Keep the full scan directory together when sharing or archiving results so the

152links from `report.md` continue to work.

153 

147## Choose your next workflow154## Choose your next workflow

148 155 

149- [Run a standard or scoped scan](https://learn.chatgpt.com/docs/security/plugin/scans) when you want156- [Run a standard or scoped scan](https://learn.chatgpt.com/docs/security/plugin/scans) when you want


159- [Export or track findings](https://learn.chatgpt.com/docs/security/plugin/export-findings) when you166- [Export or track findings](https://learn.chatgpt.com/docs/security/plugin/export-findings) when you

160 need JSON, CSV, SARIF, an approval-gated Linear, GitHub, or Jira issue, or a167 need JSON, CSV, SARIF, an approval-gated Linear, GitHub, or Jira issue, or a

161 private draft GitHub Security Advisory.168 private draft GitHub Security Advisory.

169- [Write vulnerability reports](https://learn.chatgpt.com/docs/security/plugin/vulnerability-reports)

170 when you want to turn supplied findings, disclosure notes, source, and PoCs

171 into polished, self-contained reports.

172- [Propose security hardening](https://learn.chatgpt.com/docs/security/plugin/security-hardening) when

173 you want structural or architectural options based on scan results or other

174 security evidence.

Details

3This changelog highlights changes that affect how you run scans, review3This changelog highlights changes that affect how you run scans, review

4results, and move findings toward remediation.4results, and move findings toward remediation.

5 5 

6## 0.1.11 (July 2026)

7 

8### Produce detailed finding and hardening reports

9 

10- Generate one source-backed vulnerability report for every reportable scan

11 finding, with supporting proof-of-concept files when available.

12- Review a structural hardening portfolio that analyzes the complete finding

13 set, engineering tradeoffs, migration options, and supporting diagrams.

14- Use `report.md` as the entry point to these derived outputs under `findings/`

15 and `hardening/`. Keep the full scan directory together when sharing or

16 archiving results.

17 

18### Run reporting workflows directly

19 

20- Use `$codex-security:vulnerability-writeup` to turn disclosure documents,

21 rough findings, PoCs, and source code into polished reports without first

22 running a Codex Security scan.

23- Use `$codex-security:propose-security-hardening` to develop evidence-backed

24 structural or architectural options from scans, findings, incident or

25 assessment documents, and source code.

26 

27### Apply repository guidance and coverage consistently

28 

29- Define threat-model context, security invariants, reportable finding

30 criteria, exclusions, and severity context in root or nested `SECURITY.md`

31 files. The closest applicable file takes precedence.

32- Review deleted source files in change scans and expand the default repository

33 review coverage before validation.

34- Check deep-scan phase skills, delegated workers, and worker capacity before a

35 deep scan starts.

36 

6## 0.1.9 (June 2026)37## 0.1.9 (June 2026)

7 38 

8### Review scans in the findings workspace39### Review scans in the findings workspace

Details

75 75 

76| File | Contents |76| File | Contents |

77| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |77| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |

78| `report.md` | Primary readable entry point to the complete scan directory. |

79| `findings/<slug>/` | One detailed vulnerability report per reportable finding, with supporting proof-of-concept files when available. |

80| `hardening/` | Structural hardening portfolio and supporting proposals or diagrams when the scan has reportable findings. |

78| `findings.json` | Findings with stable identifiers, severity, confidence, source locations, and remediation. Use it to create pull-request comments or feed downstream tools. |81| `findings.json` | Findings with stable identifiers, severity, confidence, source locations, and remediation. Use it to create pull-request comments or feed downstream tools. |

79| `scan-manifest.json` | Sealed scan receipt with the reviewed target, revisions, and artifact hashes. |82| `scan-manifest.json` | Sealed scan receipt with the reviewed target, revisions, and artifact hashes. |

80| `coverage.json` | Reviewed and deferred surfaces, exclusions, and coverage completeness. |83| `coverage.json` | Reviewed and deferred surfaces, exclusions, and coverage completeness. |


357The examples skip forked pull requests. Run credentialed jobs only from a360The examples skip forked pull requests. Run credentialed jobs only from a

358protected pipeline definition and only for contributors trusted with the scan361protected pipeline definition and only for contributors trusted with the scan

359credential. Archive `codex-security-scans` to keep the structured findings,362credential. Archive `codex-security-scans` to keep the structured findings,

360manifest, and coverage artifacts. Start with advisory results and review363manifest, coverage artifacts, `report.md`, and its linked `findings/` and

361coverage and runtime before making the job a required check.364`hardening/` outputs together. Start with advisory results and review coverage

365and runtime before making the job a required check.

362 366 

363For API-key handling and sandbox controls, see [Non-interactive367For API-key handling and sandbox controls, see [Non-interactive

364mode](https://learn.chatgpt.com/docs/non-interactive-mode). If your organization permits the [Codex368mode](https://learn.chatgpt.com/docs/non-interactive-mode). If your organization permits the [Codex

Details

454. Select **Start scan**.454. Select **Start scan**.

465. Review the capability preflight. If it proposes a configuration change,465. Review the capability preflight. If it proposes a configuration change,

47 review the exact change and let Codex apply it only if it matches your47 review the exact change and let Codex apply it only if it matches your

48 environment. Start a new task if Codex tells you a restart is required.48 environment. Start a new chat if Codex tells you a restart is required.

49 49 

50</WorkflowSteps>50</WorkflowSteps>

51 51 

52Deep scans require delegated workers and at least six usable worker slots. If

53the current runtime doesn't meet those requirements, use a standard scan or

54move the task to a runtime that passes the capability preflight.

55 

52<VideoPlayer56<VideoPlayer

53 src="/videos/codex/security/deep-scan-progress.mp4"57 src="/videos/codex/security/deep-scan-progress.mp4"

54 poster="/videos/codex/security/deep-scan-progress-poster.webp"58 poster="/videos/codex/security/deep-scan-progress-poster.webp"


56 60 

57## Review the result61## Review the result

58 62 

59Deep scans use the same findings workspace and generated `report.md` as standard63Deep scans use the same findings workspace and complete scan directory as

60scans. Review the coverage summary before the findings. A deep scan searches64standard scans. Start with `report.md`, which links to one detailed report for

61the code more extensively, but any deferred surface or proof gap still limits65each reportable finding and a structural hardening portfolio when findings

62the conclusion. For a finding you accept, continue with [Fix and verify a66remain. Keep the linked `findings/` and `hardening/` directories with the

67report when sharing or archiving the result.

68 

69Review the coverage summary before the findings. A deep scan searches the code

70more extensively, but any deferred surface or proof gap still limits the

71conclusion. For a finding you accept, continue with [Fix and verify a

63finding](https://learn.chatgpt.com/docs/security/plugin/fix-findings).72finding](https://learn.chatgpt.com/docs/security/plugin/fix-findings).

64 73 

65To review a pull request, commit, branch range, or local patch, use [Review code74To review a pull request, commit, branch range, or local patch, use [Review code

Details

74that payload.74that payload.

75```75```

76 76 

77Jira tracking requires the native Atlassian Rovo app in Codex. Reusing an issue77Jira tracking requires the Atlassian Rovo plugin in Codex. Reusing an issue

78requires read access; creating or updating one requires read and write access.78requires read access; creating or updating one requires read and write access.

79 79 

80For a private draft GitHub Security Advisory, send:80For a private draft GitHub Security Advisory, send:

Details

62 or proof gaps.62 or proof gaps.

634. **Attack-path analysis** evaluates realistic reachability, impact, and634. **Attack-path analysis** evaluates realistic reachability, impact, and

64 severity.64 severity.

655. **Finalization** validates the structured scan contract and generates655. **Detailed reporting** creates one source-backed vulnerability report per

66 `report.md`.66 reportable finding, with supporting proof-of-concept files when available.

676. **Structural hardening** analyzes the complete finding set and creates a

68 design portfolio when reportable findings remain.

697. **Finalization** validates the structured scan contract and generates

70 `report.md`, which links the detailed reports and hardening portfolio.

67 71 

68Codex reports phase and coverage progress as the scan runs. Don't judge the72Codex reports phase and coverage progress as the scan runs. Don't judge the

69result from early candidates or stop the scan because one phase takes longer73result from early candidates or stop the scan because one phase takes longer


115 119 

116Use the findings workspace for normal review. It presents findings, coverage,120Use the findings workspace for normal review. It presents findings, coverage,

117and follow-up areas without requiring you to inspect raw JSON. Open `report.md`121and follow-up areas without requiring you to inspect raw JSON. Open `report.md`

118when you need a complete portable review for sharing or archiving.122as the primary readable entry point to the complete scan directory. Keep the

123directory together when sharing or archiving it because the report links to

124detailed reports under `findings/` and, when reportable findings exist,

125structural hardening guidance under `hardening/`.

119 126 

120Behind the workspace, each scan preserves `scan-manifest.json`, `findings.json`,127Behind the workspace, each scan preserves `scan-manifest.json`, `findings.json`,

121and `coverage.json` for automation and integrations. You normally don't need to128and `coverage.json` for automation and integrations. You normally don't need to


128 135 

129After a person accepts a finding, use [Fix and verify a finding](https://learn.chatgpt.com/docs/security/plugin/fix-findings)136After a person accepts a finding, use [Fix and verify a finding](https://learn.chatgpt.com/docs/security/plugin/fix-findings)

130to generate and review one bounded patch. Don't ask Codex to fix every finding137to generate and review one bounded patch. Don't ask Codex to fix every finding

131from a scan in one task.138from a scan in one chat.

Details

1# Propose security hardening

2 

3Use `$codex-security:propose-security-hardening` to turn a collection of

4security evidence into structural or architectural hardening options. The

5workflow can analyze a completed Codex Security scan or start from supplied

6findings, disclosure reports, incident reviews, assessment documents, and

7source code.

8 

9The result is a design portfolio, not a patch, and doesn't prove that it fixes a

10vulnerability. Codex changes the repository only after you select an option and

11explicitly ask it to make that change.

12 

13## Prepare the evidence

14 

15Provide the workflow with:

16 

17- A scan directory or an explicit collection of findings and reports.

18- The target source tree and relevant revision or snapshot when available.

19- PoCs, traces, incident evidence, or assessment material that supports the

20 findings.

21- Constraints for performance, memory, compatibility, reliability, operations,

22 delivery time, or change scope.

23 

24The workflow uses the evidence to identify repeated broken invariants, dispersed

25controls, privileged choke points, weak isolation boundaries, and recurring

26remediation patterns. It can also conclude that local fixes are more

27proportionate than an architectural change.

28 

29## Run the workflow

30 

31Send a prompt like:

32 

33```text

34Use $codex-security:propose-security-hardening to analyze [scan directory or finding paths] against [source tree and revision]. Develop evidence-backed structural hardening options with engineering tradeoffs, before-and-after diagrams, a migration plan, and an implementation handoff. Do not modify the repository.

35```

36 

37## Review the portfolio

38 

39A useful portfolio should:

40 

41- Connect each proposed change to concrete findings, source, and threat-model

42 evidence.

43- Describe the current design and the security invariants the new design should

44 preserve.

45- Compare distinct options, including residual risk, performance,

46 reliability, operations, compatibility, and migration cost.

47- Recommend an option only when the evidence supports it, with explicit

48 assumptions and open questions.

49- Include rollout, validation, rollback, and implementation guidance.

50- Separate observed facts, inferences, and proposed design properties.

51 

52Review the evidence and tradeoffs before choosing an option. An architecture

53diagram or design recommendation doesn't replace validation of the original

54findings or the implemented fix.

55 

56## Use hardening guidance from a scan

57 

58When a standard, deep, or change scan has reportable findings, Codex runs this

59workflow once after the detailed vulnerability reports are ready. It writes the

60portfolio to `hardening/hardening.md`, structured analysis to

61`hardening/hardening.json`, and supporting proposals or diagrams under

62`hardening/`. The scan links the portfolio from `report.md`.

63 

64Keep the full scan directory together so those links remain usable. To review

65the individual reports that inform the portfolio, see [Write vulnerability

66reports](https://learn.chatgpt.com/docs/security/plugin/vulnerability-reports).

Details

1# Write vulnerability reports

2 

3Use `$codex-security:vulnerability-writeup` to create a self-contained report

4for each distinct vulnerability. You can start from Codex Security scan results

5or use supplied findings, disclosure notes, PoCs, and source code directly. A

6Codex Security scan isn't required.

7 

8## Prepare the evidence

9 

10Provide the workflow with:

11 

12- The findings, disclosure notes, or assessment documents to review.

13- The target source tree and affected revision or release.

14- Existing PoCs, logs, traces, screenshots, or crash output.

15- Fix commits or diffs when available.

16- The authorization boundary for any testing.

17 

18Source access is important because Codex checks each claim against the affected

19code before writing the final report. If the source or affected revision isn't

20available, decide whether an explicitly labeled, lower-confidence report is useful

21before proceeding.

22 

23## Run the workflow

24 

25Send a prompt like:

26 

27```text

28Use $codex-security:vulnerability-writeup to create one self-contained report for each distinct vulnerability in [input paths]. Verify the claims against [source path and revision], preserve or improve the supplied PoCs, and write the reports to [output directory]. Do not test public or production systems.

29```

30 

31Codex inventories the supplied material, groups reports that describe the same

32root cause and vulnerable path, and creates one report directory per distinct

33vulnerability. Each directory contains a descriptively named Markdown report

34and a `poc/` directory when supporting PoC files are available.

35 

36## Review each report

37 

38Before distributing a report, confirm that it:

39 

40- Traces the bug from the attacker-controlled entry point to the broken

41 security invariant and impact.

42- Distinguishes verified behavior from hypotheses and unresolved constraints.

43- Includes focused source excerpts with paths, functions, and the affected

44 revision.

45- Includes usable PoC source, build or run instructions, representative output,

46 and safety limitations when a PoC is practical.

47- Uses portable paths and doesn't depend on internal storage or local absolute

48 paths.

49 

50Never test a public or production target unless you have explicit authorization

51for that exact target.

52 

53## Use reports from a scan

54 

55When a standard, deep, or change scan has reportable findings, Codex runs this

56workflow once per finding during final reporting. The scan writes each report to

57`findings/<slug>/<slug>.md`, stores supporting files under

58`findings/<slug>/poc/`, and links the report from `report.md`.

59 

60Keep the complete scan directory together when sharing or archiving a scan. To

61look for improvements that address patterns across the reports, continue

62with [Propose security hardening](https://learn.chatgpt.com/docs/security/plugin/security-hardening).

Details

138## Related docs138## Related docs

139 139 

140- [Codex Security](https://learn.chatgpt.com/docs/security) gives the product overview.140- [Codex Security](https://learn.chatgpt.com/docs/security) gives the product overview.

141- [FAQ](https://learn.chatgpt.com/docs/security/faq) covers common questions.141- [Codex Security cloud FAQ](https://learn.chatgpt.com/docs/security/faq) covers common cloud questions.

142- [Improving the threat model](https://learn.chatgpt.com/docs/security/threat-model) explains how to improve scan context and finding prioritization.142- [Improving the threat model](https://learn.chatgpt.com/docs/security/threat-model) explains how to improve scan context and finding prioritization.

Details

25 25 

26If you want to improve the results, edit the threat model first. Use it when findings are missing the areas you care about or showing up in places you don't expect. The threat model changes future scan context.26If you want to improve the results, edit the threat model first. Use it when findings are missing the areas you care about or showing up in places you don't expect. The threat model changes future scan context.

27 27 

28Some users copy the current threat model into Codex, have a conversation to28Some users copy the current threat model into Codex, use a chat to improve it

29 improve it based on the areas they want reviewed more closely, and then paste29 based on the areas they want reviewed more closely, and then paste the updated

30 the updated version back into the web UI.30 version back into the web UI.

31 31 

32### Where to edit32### Where to edit

33 33 


37 37 

38- [Codex Security cloud setup](https://learn.chatgpt.com/docs/security/setup) covers repository setup and findings review.38- [Codex Security cloud setup](https://learn.chatgpt.com/docs/security/setup) covers repository setup and findings review.

39- [Codex Security](https://learn.chatgpt.com/docs/security) gives the product overview.39- [Codex Security](https://learn.chatgpt.com/docs/security) gives the product overview.

40- [FAQ](https://learn.chatgpt.com/docs/security/faq) covers common questions.40- [Codex Security cloud FAQ](https://learn.chatgpt.com/docs/security/faq) covers common cloud questions.

sites.md +145 −13

Details

1# Sites1# Sites

2 2 

3Sites is in public beta. Availability can depend on your plan, region, and3Sites is in public beta. Availability can depend on your plan, region, and

4 workspace settings.4 workspace settings. Plan-specific usage limits apply across all Sites during

5 the beta. ChatGPT shows the current limits and notifies you as you approach

6 one. Reaching a limit can prevent you from creating a Site, adding storage, or

7 keeping a high-usage Site public, but you can still edit and manage existing

8 Sites.

5 9 

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

7Use Sites when you want to turn a prompt or compatible existing project into a11Use Sites when you want to turn a prompt or compatible existing project into a


26 30 

27## Get started with Sites31## Get started with Sites

28 32 

33In ChatGPT, include the word "website" in your prompt or mention `@Sites` to

34start the Sites workflow explicitly.

35 

29<WorkflowSteps variant="headings">36<WorkflowSteps variant="headings">

30 37 

311. Describe the Site381. Describe the Site


86Browse the [Sites showcase](https://developers.openai.com/showcase) for deployed internal apps and the full93Browse the [Sites showcase](https://developers.openai.com/showcase) for deployed internal apps and the full

87 prompts used to create them.94 prompts used to create them.

88 95 

96## Review Site analytics

97 

98Sites records traffic automatically, so you can see how people use a deployed

99Site without adding an analytics SDK. The analytics view shows total unique

100visitors and page views, plus both metrics over time. Change the date range or

101granularity to inspect a different period.

102 

103 

104 

105Open **Sites**, find the Site, then select **More actions** > **Analytics**.

106 

107 

108 

109 

110 

111 

112 

113<Illustration description="Interactive Sites analytics dashboard showing unique visitors and page views over seven days.">

114 <SitesAnalyticsIllustration />

115</Illustration>

116 

117Analytics is currently available for Sites that aren't owned by an Enterprise

118 workspace.

119 

120## Add Sign in with ChatGPT

121 

122Public Sites can remain open to everyone while offering optional Sign in with

123ChatGPT for identity-aware features, such as saved progress, personalized views,

124or records that belong to a specific person. Workspace-restricted Sites already

125use ChatGPT identity to enforce their sharing settings.

126 

127Ask Sites to add the sign-in experience:

128 

129```text

130Add Sign in with ChatGPT to this public Site. Keep the Site available to signed-out visitors. Show a Sign in with ChatGPT action when someone is signed out. After they sign in, greet them with their full name when available, or their email address otherwise. Add a Sign out action, and keep authorization decisions in server-side code.

131```

132 

133<ToggleSection title="How it works">

134 

135Sites handles the sign-in and sign-out flows through platform-provided paths,

136then returns the visitor to your Site:

137 

138```html

139<a href="/signin-with-chatgpt">Sign in with ChatGPT</a>

140<a href="/signout-with-chatgpt">Sign out</a>

141```

142 

143After a visitor signs in, Sites forwards their identity to the server through

144these request headers:

145 

146- `oai-authenticated-user-email` contains the authenticated email address.

147- `oai-authenticated-user-full-name` may contain a non-empty profile name. Treat

148 it as optional and fall back to the email address.

149 

150Keep authorization decisions in server-side code, and don't depend on

151name-split headers.

152 

153</ToggleSection>

154 

89## Understand projects, versions, and deployments155## Understand projects, versions, and deployments

90 156 

91A Site is a persistent hosted output that you can reopen, refine, configure,157A Site is a persistent hosted output that you can reopen, refine, configure,


153 219 

154## Control access and secrets220## Control access and secrets

155 221 

156Hosting a Site doesn't automatically make it public. Keep access limited while222A new Site is limited to its owner and workspace admins until you change its

157you review the content, data handling, and expected audience.223access. Keep access limited while you review the content, data handling, and

224expected audience.

158 225 

159Depending on your account and workspace settings, sharing options can include:226Depending on your account and workspace settings, sharing options can include:

160 227 

161- Only you or people you invite.228- **Owner and workspace admins**

162- Everyone in your workspace.229- **Selected active users or groups**, where supported

163- Anyone with the link.230- **Anyone in the workspace**, where supported

231- **Anyone on the internet**, only when public publishing is enabled

164 232 

165Sharing lets people visit the Site; it doesn't let them edit it. Workspace233Sharing lets people visit the Site; it doesn't let them edit it. In Enterprise

166admins can restrict whether members can share Sites publicly.234workspaces, public publishing is off by default and must be enabled by an admin.

235 

236For limited sharing, invited visitors must sign in with the account that

237received access. A public Site is available without ChatGPT workspace access. A

238Site's audience setting and any sign-in feature built into the Site are separate

239controls.

167 240 

168For example:241For example:

169 242 


192 265 

193 266 

194 267 

268## Connect a custom domain

269 

270Where custom domains are available, you can connect an apex domain or subdomain

271that you already own. Sites doesn't register domains for you, so you must be

272able to change the domain's DNS records. Custom domains aren't available in

273Enterprise workspaces at launch.

274 

275To connect a domain:

276 

2771. Open the Site's settings and select **Add domain**.

2782. Enter the apex domain or subdomain you want to use.

2793. Copy the DNS records and values Sites provides, then add them through your

280 domain provider.

2814. Wait a few minutes, then return to the Site's settings and refresh the domain

282 status.

283 

284You can also ask ChatGPT to help point the domain at your Site. If browsing or

285computer use is enabled, ChatGPT can help you navigate your domain provider

286after you sign in.

287 

195## Review before you share288## Review before you share

196 289 

197Before you share a Site:290Before you share a Site:

198 291 

199- Review the Site's content and behavior in the preview.292- Review its content, generated text and images, links, uploaded files, forms,

200- Check that the Site handles information and uploaded files as expected.293 and interactive behavior.

201- Confirm that the Site doesn't expose confidential information or secret294- Confirm that it doesn't expose confidential or sensitive information, secret

202 values.295 values, or third-party content you don't have the right to share.

296- Test the Site from the intended visitor experience, including its access and

297 sign-in behavior.

298- Review features that collect personal information or other visitor content.

299 Decide whether the Site should collect, share, or publish that information.

300- If the Site uses Sign in with ChatGPT, explain what visitor information it

301 receives and how it uses that information.

302- If the Site collects or processes personal data, comply with

303 [applicable privacy and data-protection laws](https://help.openai.com/en/articles/20001340).

203- Choose the narrowest sharing option that fits the intended audience.304- Choose the narrowest sharing option that fits the intended audience.

204- Open the shared Site and confirm that the intended audience can visit it.305- Open the shared Site and confirm that the intended audience can visit it.

205 306 


210 311 

211 312 

212 313 

314## Take down or delete a Site

315 

316To remove access without deleting a Site, open its sharing settings and restrict

317access to yourself or selected people. Confirm that the previous audience can no

318longer open it.

319 

320To permanently delete a Site:

321 

3221. Open **Sites** and locate the Site.

3232. Select **Delete site** and follow the instructions in the prompt.

3243. Enter the Site slug, then select **Permanently delete**.

325 

326Deleting a Site permanently removes it. You can't restore a deleted Site.

327 

328## Understand limits and unsupported uses

329 

330Sites hosts web experiences that run in the supported Sites runtime. Some

331frameworks, private networks, databases, background services, and hosting

332patterns aren't supported.

333 

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

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

336artifacts, and logs.

337 

338Don't use Sites to process Protected Health Information or payment-card data;

339target children under 13 or the applicable age of digital consent; enable

340financial transactions; distribute malware; enable phishing; impersonate people

341or organizations; or otherwise violate OpenAI policies. See

342[Creating and managing ChatGPT Sites](https://help.openai.com/en/articles/20001339)

343for the current limits and policy links.

344 

213## Related documentation345## Related documentation

214 346 

215 347 

216 348 

217- [ChatGPT desktop app](https://learn.chatgpt.com/docs/app) introduces app navigation, projects, and tasks.349- [ChatGPT desktop app](https://learn.chatgpt.com/docs/app) introduces app navigation, projects, and chats.

218- [Review and ship changes](https://learn.chatgpt.com/docs/code-review?surface=app) explains how to inspect source350- [Review and ship changes](https://learn.chatgpt.com/docs/code-review?surface=app) explains how to inspect source

219 changes before publishing them.351 changes before publishing them.

skills.md +1 −1

Details

2 2 

3Use agent skills to extend Codex with task-specific capabilities. A skill packages instructions, resources, and optional scripts so Codex can follow a workflow reliably. Skills build on the [open agent skills standard](https://agentskills.io).3Use agent skills to extend Codex with task-specific capabilities. A skill packages instructions, resources, and optional scripts so Codex can follow a workflow reliably. Skills build on the [open agent skills standard](https://agentskills.io).

4 4 

5Skills are the authoring format for reusable workflows. Plugins distribute reusable skills and connectors to ChatGPT Work on the web and to Work and Codex in the ChatGPT desktop app. Codex CLI can also install plugins. Use skills to design the workflow itself, then package it as a [plugin](https://learn.chatgpt.com/docs/build-plugins) when you want other people in your workspace to install it.5Skills are the authoring format for reusable workflows. Plugins distribute reusable skills and connectors to Work mode in ChatGPT on the web and to Work mode and Codex in the ChatGPT desktop app. Codex CLI can also install plugins. Use skills to design the workflow itself, then package it as a [plugin](https://learn.chatgpt.com/docs/build-plugins) when you want other people in your workspace to install it.

6 6 

7Skills are available in the ChatGPT desktop app, Codex CLI, and IDE extension.7Skills are available in the ChatGPT desktop app, Codex CLI, and IDE extension.

8 8 

Details

2 2 

3Skills and plugins help ChatGPT complete repeatable work with the right3Skills and plugins help ChatGPT complete repeatable work with the right

4instructions, resources, and tools. They reduce the need to paste the same4instructions, resources, and tools. They reduce the need to paste the same

5prompt, template, requirements, or process into every conversation.5prompt, template, requirements, or process into every chat.

6 6 

7- A **skill** packages instructions and supporting resources for a specific7- A **skill** packages instructions and supporting resources for a specific

8 task or workflow.8 task or workflow.

9- A **plugin** is an installable bundle that can include skills, an app, or9- A **plugin** is an installable bundle that can include skills, connectors, or

10 both. Apps are backed by Model Context Protocol (MCP) servers and can10 both. Connectors are backed by Model Context Protocol (MCP) servers and can

11 optionally include custom ChatGPT UI.11 optionally include custom ChatGPT UI.

12 12 

13## Use skills for repeatable work13## Use skills for repeatable work


69## Use plugins for tools and shared workflows69## Use plugins for tools and shared workflows

70 70 

71Plugins make reusable capabilities easier to install and share. A plugin can71Plugins make reusable capabilities easier to install and share. A plugin can

72combine skills with apps for services such as GitHub, Google Drive, or Slack,72combine skills with connectors for services such as GitHub, Google Drive, or

73and can include MCP servers for additional tools and context.73Slack, and can include MCP servers for additional tools and context.

74 74 

75Browse the plugin directory when you want to add an existing workflow instead75Browse the Plugins Directory when you want to add an existing workflow instead

76of building one yourself. After installing a plugin, describe the task directly76of building one yourself. After installing a plugin, describe the task directly

77or type `@` to choose a specific plugin or bundled skill.77or type `@` to choose a specific plugin or bundled skill.

78 78 

speed.md +2 −2

Details

1# Speed1# Speed

2 2 

3<strong>ChatGPT Work and Codex share usage.</strong> Work usage inside ChatGPT3<strong>Work mode and Codex share usage.</strong> Work mode usage inside

4 uses the same pricing, credits, and usage limits as Codex. See [Codex4 ChatGPT uses the same pricing, credits, and usage limits as Codex. See [Codex

5 pricing](https://learn.chatgpt.com/docs/pricing) for details.5 pricing](https://learn.chatgpt.com/docs/pricing) for details.

6 6 

7## Fast mode7## Fast mode

subagents.md +7 −7

Details

1# Subagents1# Subagents

2 2 

3ChatGPT Work and Codex can run subagent workflows by spawning specialized3Work mode and Codex can run subagent workflows by spawning specialized

4agents in parallel and then collecting their results in one response. This can4agents in parallel and then collecting their results in one response. This can

5be particularly helpful for complex tasks that are highly parallel, such as5be particularly helpful for complex tasks that are highly parallel, such as

6codebase exploration or implementing a multi-step feature plan.6codebase exploration or implementing a multi-step feature plan.


28 28 

29 29 

30 30 

31Ask Codex in an app task to delegate independent parts of the work to31Ask Codex in an app chat to delegate independent parts of the work to

32subagents. Current local Codex releases delegate when you ask directly or when32subagents. Current local Codex releases delegate when you ask directly or when

33applicable `AGENTS.md` or skill instructions request it. The app surfaces each33applicable `AGENTS.md` or skill instructions request it. The app surfaces each

34subagent thread so you can inspect its work and the summary returned to the main34subagent thread so you can inspect its work and the summary returned to the main

35task.35chat.

36 36 

37 37 

38 38 


42 42 

43## Why subagent workflows help43## Why subagent workflows help

44 44 

45Even with large context windows, models have limits. If you flood the main conversation (where you're defining requirements, constraints, and decisions) with noisy intermediate output such as exploration notes, test logs, stack traces, and command output, the session can become less reliable over time.45Even with large context windows, models have limits. If you flood the main chat (where you're defining requirements, constraints, and decisions) with noisy intermediate output such as exploration notes, test logs, stack traces, and command output, the session can become less reliable over time.

46 46 

47This is often described as:47This is often described as:

48 48 

49- **Context pollution**: useful information gets buried under noisy intermediate output.49- **Context pollution**: useful information gets buried under noisy intermediate output.

50- **Context rot**: performance degrades as the conversation fills up with less relevant details.50- **Context rot**: performance degrades as the chat fills up with less relevant details.

51 51 

52For background, see the Chroma writeup on [context rot](https://research.trychroma.com/context-rot).52For background, see the Chroma writeup on [context rot](https://research.trychroma.com/context-rot).

53 53 


186- Ask Codex directly to steer a running subagent, stop it, or close completed186- Ask Codex directly to steer a running subagent, stop it, or close completed

187 subagent threads.187 subagent threads.

188 188 

189<Illustration description="Codex desktop task showing two subagents working in parallel.">189<Illustration description="Codex desktop chat showing two subagents working in parallel.">

190 <SubagentWorkflowIllustration ariaLabel="Codex desktop task showing two subagents working in parallel." />190 <SubagentWorkflowIllustration ariaLabel="Codex desktop chat showing two subagents working in parallel." />

191</Illustration>191</Illustration>

192 192 

193<Illustration description="Codex desktop Subagents panel with no active subagents and three completed audits.">193<Illustration description="Codex desktop Subagents panel with no active subagents and three completed audits.">

Details

300 and scales the review process.300 and scales the review process.

3013. After OpenAI approves the plugin, the developer chooses when to publish it3013. After OpenAI approves the plugin, the developer chooses when to publish it

302 and publishes it from the portal.302 and publishes it from the portal.

3034. After publication, the plugin appears in the universal plugin directory3034. After publication, the plugin appears in the Plugins Directory

304 available in both ChatGPT and Codex.304 available in both ChatGPT and Codex.

305 305 

306No separate apps directory exists. Published apps, skills-only plugins, and306Plugins that contain apps, skills-only plugins, and app-plus-skills plugins all

307app-plus-skills plugins all appear in the plugin directory.307appear in the Plugins Directory.

308 308 

309## Final checklist309## Final checklist

310 310 

Details

96@codex fix the P1 issue96@codex fix the P1 issue

97```97```

98 98 

99Codex starts a cloud task with the pull request as context and can push a fix99Codex starts a cloud chat with the pull request as context and can push a fix

100back to the branch when it has permission to do so.100back to the branch when it has permission to do so.

101 101 

102## Give Codex other tasks102## Give Codex other tasks

103 103 

104If you mention `@codex` in a comment with anything other than `review`, Codex starts a [cloud task](https://learn.chatgpt.com/docs/cloud) using your pull request as context.104If you mention `@codex` in a comment with anything other than `review`, Codex starts a [cloud chat](https://learn.chatgpt.com/docs/cloud) using your pull request as context.

105 105 

106```md106```md

107@codex fix the CI failures107@codex fix the CI failures

Details

1# Use Codex in Linear1# Use Codex in Linear

2 2 

3Use Codex in Linear to delegate work from issues. Assign an issue to Codex or mention `@Codex` in a comment, and Codex creates a cloud task and replies with progress and results.3Use Codex in Linear to delegate work from issues. Assign an issue to Codex or mention `@Codex` in a comment, and Codex creates a cloud chat and replies with progress and results.

4 4 

5Codex in Linear is available on paid plans (see [Pricing](https://learn.chatgpt.com/docs/pricing)).5Codex in Linear is available on paid plans (see [Pricing](https://learn.chatgpt.com/docs/pricing)).

6 6 

7If you're on an Enterprise plan, ask your ChatGPT workspace admin to turn on Codex cloud tasks in [workspace settings](https://chatgpt.com/admin/settings) and enable **Codex for Linear** in [connector settings](https://chatgpt.com/admin/ca).7If you're on an Enterprise plan, ask your ChatGPT workspace admin to turn on Codex cloud chats in [workspace settings](https://chatgpt.com/admin/settings) and enable **Codex for Linear** in [connector settings](https://chatgpt.com/admin/ca).

8 8 

9## Set up the Linear integration9## Set up the Linear integration

10 10 

111. Set up [Codex cloud tasks](https://learn.chatgpt.com/docs/cloud) by connecting GitHub in [Codex](https://chatgpt.com/codex) and creating an [environment](https://learn.chatgpt.com/docs/environments/cloud-environment) for the repository you want Codex to work in.111. Set up [Codex cloud chats](https://learn.chatgpt.com/docs/cloud) by connecting GitHub in [Codex](https://chatgpt.com/codex) and creating an [environment](https://learn.chatgpt.com/docs/environments/cloud-environment) for the repository you want Codex to work in.

122. Go to [Codex settings](https://chatgpt.com/codex/settings/connectors) and install **Codex for Linear** for your workspace.122. Go to [Codex settings](https://chatgpt.com/codex/settings/connectors) and install **Codex for Linear** for your workspace.

133. Link your Linear account by mentioning `@Codex` in a comment thread on a Linear issue.133. Link your Linear account by mentioning `@Codex` in a comment thread on a Linear issue.

14 14 


33 33 

34### Mention `@Codex` in comments34### Mention `@Codex` in comments

35 35 

36You can also mention `@Codex` in comment threads to delegate work or ask questions. After Codex replies, follow up in the thread to continue the same task.36You can also mention `@Codex` in comment threads to delegate work or ask questions. After Codex replies, follow up in the thread to continue the same chat.

37 37 

38<div class="not-prose max-w-3xl mr-auto my-4">38<div class="not-prose max-w-3xl mr-auto my-4">

39 <img src="https://developers.openai.com/images/codex/integrations/linear-comment-light.webp"39 <img src="https://developers.openai.com/images/codex/integrations/linear-comment-light.webp"


52To track progress:52To track progress:

53 53 

54- Open **Activity** on the issue to see progress updates.54- Open **Activity** on the issue to see progress updates.

55- Open the task link to follow along in more detail.55- Open the chat link to follow along in more detail.

56 56 

57When the task finishes, Codex posts a summary and a link to the completed task so you can create a pull request.57When Codex finishes, it posts a summary and a link to the completed chat so you can create a pull request.

58 58 

59### How Codex chooses an environment and repo59### How Codex chooses an environment and repo

60 60 

61- Linear suggests a repository based on the issue context. Codex selects the environment that best matches that suggestion. If the request is ambiguous, it falls back to the environment you used most recently.61- Linear suggests a repository based on the issue context. Codex selects the environment that best matches that suggestion. If the request is ambiguous, it falls back to the environment you used most recently.

62- The task runs against the default branch of the first repository listed in that environment’s repo map. Update the repo map in Codex if you need a different default or more repositories.62- The chat runs against the default branch of the first repository listed in that environment’s repo map. Update the repo map in Codex if you need a different default or more repositories.

63- If no suitable environment or repository is available, Codex will reply in Linear with instructions on how to fix the issue before retrying.63- If no suitable environment or repository is available, Codex will reply in Linear with instructions on how to fix the issue before retrying.

64 64 

65## Automatically assign issues to Codex65## Automatically assign issues to Codex


724. In **Triage rules**, create a rule and choose **Delegate** > **Codex** (and any other properties you want to set).724. In **Triage rules**, create a rule and choose **Delegate** > **Codex** (and any other properties you want to set).

73 73 

74Linear assigns new issues that enter triage to Codex automatically.74Linear assigns new issues that enter triage to Codex automatically.

75When you use triage rules, Codex runs tasks using the account of the issue creator.75When you use triage rules, Codex runs chats using the account of the issue creator.

76 76 

77<div class="not-prose max-w-3xl mr-auto my-4">77<div class="not-prose max-w-3xl mr-auto my-4">

78 <img src="https://developers.openai.com/images/codex/integrations/linear-triage-rule-light.webp"78 <img src="https://developers.openai.com/images/codex/integrations/linear-triage-rule-light.webp"


87 87 

88## Data usage, privacy, and security88## Data usage, privacy, and security

89 89 

90When you mention `@Codex` or assign an issue to it, Codex receives your issue content to understand your request and create a task.90When you mention `@Codex` or assign an issue to it, Codex receives your issue content to understand your request and create a chat.

91Data handling follows OpenAI's [Privacy Policy](https://openai.com/privacy), [Terms of Use](https://openai.com/terms/), and other applicable [policies](https://openai.com/policies).91Data handling follows OpenAI's [Privacy Policy](https://openai.com/privacy), [Terms of Use](https://openai.com/terms/), and other applicable [policies](https://openai.com/policies).

92For more on security, see the [Codex security documentation](https://learn.chatgpt.com/docs/agent-approvals-security).92For more on security, see the [Codex security documentation](https://learn.chatgpt.com/docs/agent-approvals-security).

93 93 


100- **Wrong part of the code**: Add more context in the issue, or give explicit instructions in your `@Codex` comment.100- **Wrong part of the code**: Add more context in the issue, or give explicit instructions in your `@Codex` comment.

101- **More help**: See the [OpenAI Help Center](https://help.openai.com/).101- **More help**: See the [OpenAI Help Center](https://help.openai.com/).

102 102 

103## Connect Linear for local tasks (MCP)103<a id="connect-linear-for-local-tasks-mcp"></a>

104 

105## Connect Linear for local work (MCP)

104 106 

105If you're using the ChatGPT desktop app, Codex CLI, or IDE extension and want it to access Linear issues locally, configure the Linear Model Context Protocol (MCP) server.107If you're using the ChatGPT desktop app, Codex CLI, or IDE extension and want it to access Linear issues locally, configure the Linear Model Context Protocol (MCP) server.

106 108 

Details

1# Use Codex in Slack1# Use Codex in Slack

2 2 

3Use Codex in Slack to kick off coding tasks from channels and threads. Mention `@Codex` with a prompt, and Codex creates a cloud task and replies with the results.3Use Codex in Slack to kick off coding work from channels and threads. Mention `@Codex` with a prompt, and Codex creates a cloud chat and replies with the results.

4 4 

5<div class="not-prose max-w-3xl mr-auto">5<div class="not-prose max-w-3xl mr-auto">

6 <img src="https://developers.openai.com/images/codex/integrations/slack-example.png"6 <img src="https://developers.openai.com/images/codex/integrations/slack-example.png"


13 13 

14## Set up the Slack app14## Set up the Slack app

15 15 

161. Set up [Codex cloud tasks](https://learn.chatgpt.com/docs/cloud). You need a Plus, Pro, Business, Enterprise, or Edu plan (see [ChatGPT pricing](https://chatgpt.com/pricing)), a connected GitHub account, and at least one [environment](https://learn.chatgpt.com/docs/environments/cloud-environment).161. Set up [Codex cloud chats](https://learn.chatgpt.com/docs/cloud). You need a Plus, Pro, Business, Enterprise, or Edu plan (see [ChatGPT pricing](https://chatgpt.com/pricing)), a connected GitHub account, and at least one [environment](https://learn.chatgpt.com/docs/environments/cloud-environment).

172. Go to [Codex settings](https://chatgpt.com/codex/settings/connectors) and install the Slack app for your workspace. Depending on your Slack workspace policies, an admin may need to approve the install.172. Go to [Codex settings](https://chatgpt.com/codex/settings/connectors) and install the Slack app for your workspace. Depending on your Slack workspace policies, an admin may need to approve the install.

183. Add `@Codex` to a channel. If you haven't added it yet, Slack prompts you when you mention it.183. Add `@Codex` to a channel. If you haven't added it yet, Slack prompts you when you mention it.

19 19 

20## Start a task20<a id="start-a-task"></a>

21 

22## Start a chat

21 23 

221. In a channel or thread, mention `@Codex` and include your prompt. Codex can reference earlier messages in the thread, so you often don't need to restate context.241. In a channel or thread, mention `@Codex` and include your prompt. Codex can reference earlier messages in the thread, so you often don't need to restate context.

232. (Optional) Specify an environment or repository in your prompt, for example: `@Codex fix the above in openai/codex`.252. (Optional) Specify an environment or repository in your prompt, for example: `@Codex fix the above in openai/codex`.

243. Wait for Codex to react (👀) and reply with a link to the task. When it finishes, Codex posts the result and, depending on your settings, an answer in the thread.263. Wait for Codex to react (👀) and reply with a link to the chat. When it finishes, Codex posts the result and, depending on your settings, an answer in the thread.

25 27 

26### How Codex chooses an environment and repo28### How Codex chooses an environment and repo

27 29 

28- Codex reviews the environments you have access to and selects the one that best matches your request. If the request is ambiguous, it falls back to the environment you used most recently.30- Codex reviews the environments you have access to and selects the one that best matches your request. If the request is ambiguous, it falls back to the environment you used most recently.

29- The task runs against the default branch of the first repository listed in that environment’s repo map. Update the repo map in Codex if you need a different default or more repositories.31- The chat runs against the default branch of the first repository listed in that environment’s repo map. Update the repo map in Codex if you need a different default or more repositories.

30- If no suitable environment or repository is available, Codex will reply in Slack with instructions on how to fix the issue before retrying.32- If no suitable environment or repository is available, Codex will reply in Slack with instructions on how to fix the issue before retrying.

31 33 

32### Enterprise data controls34### Enterprise data controls

33 35 

34By default, Codex replies in the thread with an answer, which can include information from the environment it ran in.36By default, Codex replies in the thread with an answer, which can include information from the environment it ran in.

35To prevent this, an Enterprise admin can clear **Allow Codex Slack app to post answers on task completion** in [ChatGPT workspace settings](https://chatgpt.com/admin/settings). When an admin turns off answers, Codex replies only with a link to the task.37To prevent this, an Enterprise admin can clear **Allow Codex Slack app to post answers on task completion** in [ChatGPT workspace settings](https://chatgpt.com/admin/settings). When an admin turns off answers, Codex replies only with a link to the chat.

36 38 

37### Data usage, privacy, and security39### Data usage, privacy, and security

38 40 

39When you mention `@Codex`, Codex receives your message and thread history to understand your request and create a task.41When you mention `@Codex`, Codex receives your message and thread history to understand your request and create a chat.

40Data handling follows OpenAI's [Privacy Policy](https://openai.com/privacy), [Terms of Use](https://openai.com/terms/), and other applicable [policies](https://openai.com/policies).42Data handling follows OpenAI's [Privacy Policy](https://openai.com/privacy), [Terms of Use](https://openai.com/terms/), and other applicable [policies](https://openai.com/policies).

41For more on security, see the Codex [security documentation](https://learn.chatgpt.com/docs/agent-approvals-security).43For more on security, see the Codex [security documentation](https://learn.chatgpt.com/docs/agent-approvals-security).

42 44 


47- **Missing connections**: If Codex can't confirm your Slack or GitHub connection, it replies with a link to reconnect.49- **Missing connections**: If Codex can't confirm your Slack or GitHub connection, it replies with a link to reconnect.

48- **Unexpected environment choice**: Reply in the thread with the environment you want (for example, `Please run this in openai/openai (applied)`), then mention `@Codex` again.50- **Unexpected environment choice**: Reply in the thread with the environment you want (for example, `Please run this in openai/openai (applied)`), then mention `@Codex` again.

49- **Long or complex threads**: Summarize key details in your latest message so Codex doesn't miss context buried earlier in the thread.51- **Long or complex threads**: Summarize key details in your latest message so Codex doesn't miss context buried earlier in the thread.

50- **Workspace posting**: Some Enterprise workspaces restrict posting final answers. In those cases, open the task link to view progress and results.52- **Workspace posting**: Some Enterprise workspaces restrict posting final answers. In those cases, open the chat link to view progress and results.

51- **More help**: See the [OpenAI Help Center](https://help.openai.com/).53- **More help**: See the [OpenAI Help Center](https://help.openai.com/).

Details

1# Productivity & Collaboration1# Productivity & Collaboration

2 2 

3Coordinate work across apps, data, and teams.3Coordinate work across plugins, data, and teams.

4 4 

5Use ChatGPT Work or Codex to coordinate work across apps, files, and teams.5Use ChatGPT Work or Codex to coordinate work across plugins, files, and teams.

6ChatGPT can gather context from files, messages, docs, and spreadsheets, then turn it into shareable artifacts.6ChatGPT can gather context from files, messages, docs, and spreadsheets, then turn it into shareable artifacts.

7For data projects that depend on a repository, reproducible scripts, or worktrees, use Codex.7For data projects that depend on a repository, reproducible scripts, or worktrees, use Codex.

8 8 


14 14 

15## Delegate multi-step workflows15## Delegate multi-step workflows

16 16 

17Have ChatGPT gather approved inputs from multiple apps to prepare a workflow, or let it use your computer to complete tasks across apps.17Have ChatGPT gather approved inputs from multiple plugins to prepare a workflow, or let it use your computer to complete tasks across desktop apps.

18 18 

19- https://developers.openai.com/codex/use-cases/new-hire-onboarding19- https://developers.openai.com/codex/use-cases/new-hire-onboarding

20- https://developers.openai.com/codex/use-cases/use-your-computer-with-codex20- https://developers.openai.com/codex/use-cases/use-your-computer-with-codex

Details

22 title: Build a CLI and companion skill22 title: Build a CLI and companion skill

23 body: >-23 body: >-

24 Use $cli-creator to create a CLI you can use, and use $skill-creator to24 Use $cli-creator to create a CLI you can use, and use $skill-creator to

25 create the companion skill in this same task.25 create the companion skill in this same chat.

26 26 

27 27 

28 Source to learn from: [docs URL, OpenAPI spec, redacted curl command,28 Source to learn from: [docs URL, OpenAPI spec, redacted curl command,


82| **An API response is too large for context.** | List only the fields it needs, read the full object by ID, and export the complete response to a file. |82| **An API response is too large for context.** | List only the fields it needs, read the full object by ID, and export the complete response to a file. |

83| **A Slack export has long threads.** | Search with `--limit`, read one thread, and return nearby context instead of the whole archive. |83| **A Slack export has long threads.** | Search with `--limit`, read one thread, and return nearby context instead of the whole archive. |

84| **A team script runs four different steps.** | Split setup, discovery, download, draft, upload, poll, and live write into separate commands. |84| **A team script runs four different steps.** | Split setup, discovery, download, draft, upload, poll, and live write into separate commands. |

85| **A plugin finds the record, but Codex needs a file.** | Keep the plugin in the task; use a CLI to download the attachment, trace, report, video, or log bundle and return the path. |85| **A plugin finds the record, but Codex needs a file.** | Keep the plugin in the chat; use a CLI to download the attachment, trace, report, video, or log bundle and return the path. |

86 86 

87## Share the docs, files, or commands87## Share the docs, files, or commands

88 88 

89Codex needs something concrete to learn from: docs or OpenAPI, a redacted curl command, an export or database path, a log folder, or an existing script. If you want the CLI to follow a familiar style, paste a short `--help` output from `gh`, `kubectl`, or your team's own tool.89Codex needs something concrete to learn from: docs or OpenAPI, a redacted curl command, an export or database path, a log folder, or an existing script. If you want the CLI to follow a familiar style, paste a short `--help` output from `gh`, `kubectl`, or your team's own tool.

90 90 

91If the command needs auth, tell Codex the environment variable name, config file path, or login flow it should support. Set the secret yourself in your shell or config file. Do not paste secrets into the task. Ask Codex to make the CLI's setup check fail clearly when auth is missing.91If the command needs auth, tell Codex the environment variable name, config file path, or login flow it should support. Set the secret yourself in your shell or config file. Do not paste secrets into the chat. Ask Codex to make the CLI's setup check fail clearly when auth is missing.

92 92 

93## Ask Codex to build the CLI and skill93## Ask Codex to build the CLI and skill

94 94 


108 108 

109When you need the CLI again, invoke the skill instead of pasting the docs again:109When you need the CLI again, invoke the skill instead of pasting the docs again:

110 110 

111For recurring work, test the skill once in a task, then ask Codex to [schedule that same invocation from the task](https://developers.openai.com/codex/automations#schedule-work-from-a-task).111For recurring work, test the skill once in a chat, then ask Codex to [schedule a task for that same invocation from the chat](https://developers.openai.com/codex/automations#schedule-a-task-inside-a-chat).

Details

411. Attach the file or mention the connected data source.411. Attach the file or mention the connected data source.

422. Ask the question you want answered.422. Ask the question you want answered.

433. Have ChatGPT inspect the columns, run the calculation, and create an HTML visualization.433. Have ChatGPT inspect the columns, run the calculation, and create an HTML visualization.

444. Open the local preview in the built-in browser, then continue in the same task to adjust the chart or slice the data another way.444. Open the local preview in the built-in browser, then continue in the same chat to adjust the chart or slice the data another way.

45 45 

46 46 

47 47 


51 51 

52After ChatGPT gives you the first answer, ask for the next comparison you would normally check.52After ChatGPT gives you the first answer, ask for the next comparison you would normally check.

53 53 

54You can keep going in the same task: clean a column, exclude a test segment, compare two time windows, make the chart easier to read, or turn the result into a short note for a meeting.54You can keep going in the same chat: clean a column, exclude a test segment, compare two time windows, make the chart easier to read, or turn the result into a short note for a meeting.

Details

2name: Automate bug triage2name: Automate bug triage

3tagline: Turn daily bug reports into a prioritized list, then automate the sweep.3tagline: Turn daily bug reports into a prioritized list, then automate the sweep.

4summary: Ask Codex to check recent alerts, issues, failed checks, logs, and chat4summary: Ask Codex to check recent alerts, issues, failed checks, logs, and chat

5 reports, tune the list in one task, then run that sweep on a schedule.5 reports, tune the list in one chat, then run that sweep on a schedule.

6skills:6skills:

7 - token: github7 - token: github

8 url: https://github.com/openai/plugins/tree/main/plugins/github8 url: https://github.com/openai/plugins/tree/main/plugins/github


23bestFor:23bestFor:

24 - Teams that track bugs across Sentry alerts, Slack threads, Linear issues,24 - Teams that track bugs across Sentry alerts, Slack threads, Linear issues,

25 GitHub issues, failing PR checks, support tickets, or logs.25 GitHub issues, failing PR checks, support tickets, or logs.

26 - Triage workflows you want to run manually in one Codex task before26 - Triage workflows you want to run manually in one Codex chat before

27 scheduling the work.27 scheduling the work.

28starterPrompt:28starterPrompt:

29 title: Run a Bug Triage Sweep29 title: Run a Bug Triage Sweep


102 102 

103## How to use103## How to use

104 104 

105Ask Codex to check the places where bugs already appear: Sentry alerts, Linear issues, GitHub issues, PR checks, deploy logs, support tickets, and Slack threads. Start with one manual sweep, tune the report in the task, then run it on a schedule.105Ask Codex to check the places where bugs already appear: Sentry alerts, Linear issues, GitHub issues, PR checks, deploy logs, support tickets, and Slack threads. Start with one manual sweep, tune the report in the chat, then run it on a schedule.

106 106 

107Use one Codex task for the whole triage loop:107Use one Codex chat for the whole triage loop:

108 108 

109 109 

110 110 

1111. Run an on-demand sweep and get a draft list.1111. Run an on-demand sweep and get a draft list.

1122. Review the list and give feedback in that same task.1122. Review the list and give feedback in that same chat.

1133. Schedule the triage work from that task.1133. Schedule a task for the triage work from that chat.

1144. Optional: ask Codex to draft Linear issues, Slack updates, GitHub comments, or handoff notes when you are confident in the report.1144. Optional: ask Codex to draft Linear issues, Slack updates, GitHub comments, or handoff notes when you are confident in the report.

115 115 

116 116 


140- Guesses are separated from observed facts.140- Guesses are separated from observed facts.

141- Each bug has a short recommended next action.141- Each bug has a short recommended next action.

142 142 

143Tune the report in the same task before you schedule it. You can ask Codex to:143Tune the report in the same chat before you schedule it. You can ask Codex to:

144 144 

145- Check one more source before ranking the list.145- Check one more source before ranking the list.

146- Drop noisy alerts that the team already knows about.146- Drop noisy alerts that the team already knows about.


151 151 

152## Phase 3: Automate it152## Phase 3: Automate it

153 153 

154When the on-demand report is useful, stay in the same task and schedule the triage work from it. Codex can use what you refined in the task to write the recurring prompt.154When the on-demand report is useful, stay in the same chat and [schedule a task for the triage work from it](https://developers.openai.com/codex/automations#schedule-a-task-inside-a-chat). Codex can use what you refined in the chat to write the recurring prompt.

155 155 

156**Schedule the triage work**156**Schedule the triage work**

157 157 

Details

40 40 

41If you're working on a budget and want to review the variances or inspect any issues, ChatGPT can help you create a fully functional review workbook you can work with.41If you're working on a budget and want to review the variances or inspect any issues, ChatGPT can help you create a fully functional review workbook you can work with.

42 42 

43Attach the budget plan, actuals export, and close notes, then ask ChatGPT for an editable review workbook. ChatGPT can preserve the raw inputs, map actuals to plan, calculate variances, and create a summary view you can inspect in the task.43Attach the budget plan, actuals export, and close notes, then ask ChatGPT for an editable review workbook. ChatGPT can preserve the raw inputs, map actuals to plan, calculate variances, and create a summary view you can inspect in the chat.

44 44 

45## Create the review workbook45## Create the review workbook

46 46 


491. Attach the budget plan, actuals export, and close notes, or provide exact file references along with the source.491. Attach the budget plan, actuals export, and close notes, or provide exact file references along with the source.

502. Run the starter prompt and ask for an editable `.xlsx` workbook.502. Run the starter prompt and ask for an editable `.xlsx` workbook.

513. Open the workbook in ChatGPT. Expand it into the full-screen view to inspect the raw inputs, mappings, variance formulas, and summary tab.513. Open the workbook in ChatGPT. Expand it into the full-screen view to inspect the raw inputs, mappings, variance formulas, and summary tab.

524. Continue in the same task to fix category mappings, add department cuts, or draft the finance summary.524. Continue in the same chat to fix category mappings, add department cuts, or draft the finance summary.

53 53 

54 54 

55 55 

56If the source files are in a connected app, mention the exact files or folder. Avoid asking ChatGPT to search a broad Drive or workspace when the review should use specific finance sources. When the workbook appears in the task, open it and expand it full-screen to review the raw inputs, mappings, variance formulas, and summary tab before asking for revisions.56If the source files are in a connected plugin, mention the exact files or folder. Avoid asking ChatGPT to search a broad Drive or workspace when the review should use specific finance sources. When the workbook appears in the chat, open it and expand it full-screen to review the raw inputs, mappings, variance formulas, and summary tab before asking for revisions.

57 57 

58## Check the variances58## Check the variances

59 59 

Details

8 - Apps that need lightweight structured persistence, file uploads, or8 - Apps that need lightweight structured persistence, file uploads, or

9 workspace-oriented sharing.9 workspace-oriented sharing.

10 - Internal tools that benefit from building, testing, deploying, and iterating10 - Internal tools that benefit from building, testing, deploying, and iterating

11 in one task.11 in one chat.

12starterPrompt:12starterPrompt:

13 title: Build and Deploy an Internal App13 title: Build and Deploy an Internal App

14 body: |-14 body: |-


34 url: /showcase/sites34 url: /showcase/sites

35---35---

36 36 

37## Build and deploy from one task37<a id="build-and-deploy-from-one-task"></a>

38 

39## Build and deploy from one chat

38 40 

39Sites is a managed hosting service in ChatGPT. Ask ChatGPT to create an app, and it can build the project, run it for testing, deploy it, and return a URL you can share.41Sites is a managed hosting service in ChatGPT. Ask ChatGPT to create an app, and it can build the project, run it for testing, deploy it, and return a URL you can share.

40 42 


51You can also leverage [Plugins](https://developers.openai.com/codex/plugins) to fetch or refresh data from internal sources.53You can also leverage [Plugins](https://developers.openai.com/codex/plugins) to fetch or refresh data from internal sources.

52 54 

53If you need live data fetching, you can connect to a 3rd party tool using an55If you need live data fetching, you can connect to a 3rd party tool using an

54 API key. But if you want to use plugin connections, you can [schedule work56 API key. But if you want to use plugin connections, you can [schedule a task

55 from the current task](https://developers.openai.com/codex/automations#schedule-work-from-a-task) to fetch57 from the current chat](https://developers.openai.com/codex/automations#schedule-a-task-inside-a-chat) to

56 data with plugins on a set schedule, update the app, and redeploy it.58 fetch data with plugins on a set schedule, update the app, and redeploy it.

57 59 

58## Choose storage deliberately60## Choose storage deliberately

59 61 

Details

68 68 

69Check the standards alignment, pacing, assessment load, accessibility, and age appropriateness. Confirm that ChatGPT has not invented district requirements or learner information.69Check the standards alignment, pacing, assessment load, accessibility, and age appropriateness. Confirm that ChatGPT has not invented district requirements or learner information.

70 70 

71Revise the plan in the same task, then mark the approved version clearly before using it to generate decks or classroom materials.71Revise the plan in the same chat, then mark the approved version clearly before using it to generate decks or classroom materials.

Details

13 - Bioinformatics teams validating bulk RNA-seq inputs before differential13 - Bioinformatics teams validating bulk RNA-seq inputs before differential

14 expression.14 expression.

15 - Researchers who want transcript and gene-level quantification plus QC in one15 - Researchers who want transcript and gene-level quantification plus QC in one

16 task.16 chat.

17 - Teams that need mapping-rate, duplication, library-type, and17 - Teams that need mapping-rate, duplication, library-type, and

18 resource-readiness review.18 resource-readiness review.

19starterPrompt:19starterPrompt:


621. Point ChatGPT to a directory with the sample sheet, FASTQs, transcriptome FASTA, genome FASTA, and GTF, or provide exact file references.621. Point ChatGPT to a directory with the sample sheet, FASTQs, transcriptome FASTA, genome FASTA, and GTF, or provide exact file references.

632. Run the starter prompt so ChatGPT can validate strandedness, reference consistency, and tool readiness before execution.632. Run the starter prompt so ChatGPT can validate strandedness, reference consistency, and tool readiness before execution.

643. Open the generated MultiQC and matrix artifacts in ChatGPT to review mapping rate, duplication, library-type agreement, and resource readiness.643. Open the generated MultiQC and matrix artifacts in ChatGPT to review mapping rate, duplication, library-type agreement, and resource readiness.

654. Continue in the same task to fix blockers, rerun with updated metadata, or hand the resulting gene-level matrices into downstream differential expression.654. Continue in the same chat to fix blockers, rerun with updated metadata, or hand the resulting gene-level matrices into downstream differential expression.

66 66 

67 67 

68 68 

Details

471. Attach the cash-flow inputs, operating assumptions, and model constraints.471. Attach the cash-flow inputs, operating assumptions, and model constraints.

482. Run the starter prompt and ask for an editable `.xlsx` workbook.482. Run the starter prompt and ask for an editable `.xlsx` workbook.

493. Open the workbook in ChatGPT. Expand it into the full-screen view to inspect assumptions, formulas, scenarios, and the summary tab.493. Open the workbook in ChatGPT. Expand it into the full-screen view to inspect assumptions, formulas, scenarios, and the summary tab.

504. Continue in the same task to change collections, payroll, vendor payment, growth, or safety-balance assumptions.504. Continue in the same chat to change collections, payroll, vendor payment, growth, or safety-balance assumptions.

51 51 

52 52 

53 53 

54When the workbook appears in the task, open it and expand it full-screen. Review the timing assumptions, formulas, scenarios, and summary tab, then ask ChatGPT to revise the same workbook from there.54When the workbook appears in the chat, open it and expand it full-screen. Review the timing assumptions, formulas, scenarios, and summary tab, then ask ChatGPT to revise the same workbook from there.

55 55 

56## Review cash pressure56## Review cash pressure

57 57 

Details

38 Use the prior pack or progress outline, initiative trackers, metric38 Use the prior pack or progress outline, initiative trackers, metric

39 snapshots, latest forecast model, KPI dashboard, cash view, leadership39 snapshots, latest forecast model, KPI dashboard, cash view, leadership

40 notes, owner commentary, and open questions I provide. If any sources are in40 notes, owner commentary, and open questions I provide. If any sources are in

41 connected apps, use only the exact @google-drive files or @slack threads I41 connected plugins, use only the exact @google-drive files or @slack threads

42 name.42 I name.

43 43 

44 44 

45 Identify the through-line across workstreams, then update the narrative,45 Identify the through-line across workstreams, then update the narrative,


743. Ask ChatGPT to find the through-line across progress, proof points, risks, and next milestones.743. Ask ChatGPT to find the through-line across progress, proof points, risks, and next milestones.

754. Run the starter prompt and request an editable `.pptx` file.754. Run the starter prompt and request an editable `.pptx` file.

765. Review the source tie-out for every changed claim, metric, and chart.765. Review the source tie-out for every changed claim, metric, and chart.

776. Inspect the rendered slides for clipping, overflow, and layout drift, then resolve owner inputs in the same task.776. Inspect the rendered slides for clipping, overflow, and layout drift, then resolve owner inputs in the same chat.

78 78 

79 79 

80 80 

Details

70 70 

71 71 

72 72 

73Use the starter prompt on this page for the first cleaning pass. Replace the file name and bullets with your own. The useful details are the problems you already see and the file you need next: a cleaned CSV, a clean spreadsheet tab, or an upload-ready file. After ChatGPT writes the clean copy, open the cleaned file and the data-quality note from the task before using the data downstream.73Use the starter prompt on this page for the first cleaning pass. Replace the file name and bullets with your own. The useful details are the problems you already see and the file you need next: a cleaned CSV, a clean spreadsheet tab, or an upload-ready file. After ChatGPT writes the clean copy, open the cleaned file and the data-quality note from the chat before using the data downstream.

Details

1# Productivity & Collaboration1# Productivity & Collaboration

2 2 

3Coordinate work across apps, data, and teams.3Coordinate work across plugins, data, and teams.

4 4 

5Use ChatGPT Work or Codex to coordinate work across apps, files, and teams.5Use ChatGPT Work or Codex to coordinate work across plugins, files, and teams.

6ChatGPT can gather context from files, messages, docs, and spreadsheets, then turn it into shareable artifacts.6ChatGPT can gather context from files, messages, docs, and spreadsheets, then turn it into shareable artifacts.

7For data projects that depend on a repository, reproducible scripts, or worktrees, use Codex.7For data projects that depend on a repository, reproducible scripts, or worktrees, use Codex.

8 8 


14 14 

15## Delegate multi-step workflows15## Delegate multi-step workflows

16 16 

17Have ChatGPT gather approved inputs from multiple apps to prepare a workflow, or let it use your computer to complete tasks across apps.17Have ChatGPT gather approved inputs from multiple plugins to prepare a workflow, or let it use your computer to complete tasks across desktop apps.

18 18 

19- https://developers.openai.com/codex/use-cases/new-hire-onboarding19- https://developers.openai.com/codex/use-cases/new-hire-onboarding

20- https://developers.openai.com/codex/use-cases/use-your-computer-with-codex20- https://developers.openai.com/codex/use-cases/use-your-computer-with-codex

Details

165 165 

166## Explore with charts and separate worktrees166## Explore with charts and separate worktrees

167 167 

168Exploratory data analysis is where Codex benefits from clean isolation. One worktree can test address cleanup or feature engineering while another focuses on charts or alternate model directions. That keeps each diff reviewable and prevents one long task from mixing incompatible ideas.168Exploratory data analysis is where Codex benefits from clean isolation. One worktree can test address cleanup or feature engineering while another focuses on charts or alternate model directions. That keeps each diff reviewable and prevents one long chat from mixing incompatible ideas.

169 169 

170The ChatGPT desktop app includes built-in worktree support. If you are working in a terminal, plain Git worktrees work well too:170The ChatGPT desktop app includes built-in worktree support. If you are working in a terminal, plain Git worktrees work well too:

171 171 


213- `$doc` and `$pdf` for stakeholder-facing outputs.213- `$doc` and `$pdf` for stakeholder-facing outputs.

214- `$vercel-deploy` when you want to share the result as a URL.214- `$vercel-deploy` when you want to share the result as a URL.

215 215 

216Once the workflow stabilizes, create repo-local skills for the repeated parts, such as `refresh-data`, `merge-and-qa`, or `publish-weekly-report`. That's a better long-term pattern than pasting the same procedural prompt into every task.216Once the workflow stabilizes, create repo-local skills for the repeated parts, such as `refresh-data`, `merge-and-qa`, or `publish-weekly-report`. That's a better long-term pattern than pasting the same procedural prompt into every chat.

217 217 

218## Suggested prompts218## Suggested prompts

219 219 

Details

551. Attach the historical financials, valuation assumptions, and any modeling notes, or provide exact file references along with the source.551. Attach the historical financials, valuation assumptions, and any modeling notes, or provide exact file references along with the source.

562. Run the starter prompt and ask for an editable `.xlsx` workbook.562. Run the starter prompt and ask for an editable `.xlsx` workbook.

573. Open the generated workbook in ChatGPT. Expand it into the full-screen view to inspect the model tabs, formulas, assumptions, and valuation summary.573. Open the generated workbook in ChatGPT. Expand it into the full-screen view to inspect the model tabs, formulas, assumptions, and valuation summary.

584. Continue in the same task to check formula links, change assumptions, add scenarios, or tighten the model.584. Continue in the same chat to check formula links, change assumptions, add scenarios, or tighten the model.

59 59 

60 60 

61 61 

62When the workbook appears in the task, open it and expand it full-screen. Review the source inputs, forecast drivers, valuation outputs, and sensitivity tables, then ask ChatGPT to revise the same workbook from there.62When the workbook appears in the chat, open it and expand it full-screen. Review the source inputs, forecast drivers, valuation outputs, and sensitivity tables, then ask ChatGPT to revise the same workbook from there.

63 63 

64## Check the valuation64## Check the valuation

65 65 


67 67 

68## Revise one assumption68## Revise one assumption

69 69 

70After reviewing the workbook, ask for targeted revisions in the same task. Change one driver at a time so the impact is easy to inspect.70After reviewing the workbook, ask for targeted revisions in the same chat. Change one driver at a time so the impact is easy to inspect.

Details

3tagline: Search an authorized repository deeply for plausible vulnerabilities.3tagline: Search an authorized repository deeply for plausible vulnerabilities.

4summary: Use the Codex Security plugin to run a more comprehensive audit of a4summary: Use the Codex Security plugin to run a more comprehensive audit of a

5 repository or scoped folder that repeats discovery, validates candidates, and5 repository or scoped folder that repeats discovery, validates candidates, and

6 produces reviewable coverage and findings.6 produces reviewable coverage, detailed finding reports, and structural

7 hardening guidance.

7skills:8skills:

8 - token: $codex-security:deep-security-scan9 - token: $codex-security:deep-security-scan

9 url: /codex/security/plugin/deep-scans10 url: /codex/security/plugin/deep-scans

10 description: Run repeated discovery passes over a repository or scoped folder,11 description: Run repeated discovery passes over a repository or scoped folder,

11 validate surviving findings, analyze attack paths, and generate reviewable12 validate surviving findings, analyze attack paths, and generate detailed

12 artifacts.13 reports and structural hardening guidance.

13bestFor:14bestFor:

14 - Application security reviews of a repository or component that you own or15 - Application security reviews of a repository or component that you own or

15 are authorized to assess.16 are authorized to assess.


35 this as a pull request or diff review.36 this as a pull request or diff review.

36 37 

37 38 

38 Return the generated report path. Summarize the findings, reviewed surfaces,39 Return the scan directory and report.md path. Summarize the findings,

39 and proof gaps that require human review first.40 reviewed surfaces, structural hardening guidance, and proof gaps that

41 require human review first.

40 suggestedEffort: high42 suggestedEffort: high

41relatedLinks:43relatedLinks:

42 - label: Deep-scan guide44 - label: Deep-scan guide


65 67 

661. Open the repository in Codex and complete the [Codex Security plugin quickstart](https://developers.openai.com/codex/security/plugin).681. Open the repository in Codex and complete the [Codex Security plugin quickstart](https://developers.openai.com/codex/security/plugin).

672. Confirm that you own the repository or have authorization to assess it.692. Confirm that you own the repository or have authorization to assess it.

683. Add repository-specific architecture, trust-boundary, build, test, and validation guidance in `AGENTS.md` when it will improve the review.703. Add architecture, trust-boundary, security-invariant, finding-criteria,

694. Run the starter prompt and let the scan complete its repeated discovery, validation, attack-path analysis, and final reporting stages.71 exclusion, and severity guidance in `SECURITY.md`. Use nested `SECURITY.md`

705. Review the findings workspace and any proof gaps before asking Codex to change code or reproduce a finding further.72 files for directory-specific policy.

734. Keep supported build, test, and validation commands and other repository

74 instructions in `AGENTS.md`.

755. Run the starter prompt and let the scan complete its repeated discovery,

76 validation, attack-path analysis, per-finding reporting, structural

77 hardening, and final reporting stages.

786. Review the findings workspace, detailed reports, hardening portfolio, and

79 any proof gaps before asking Codex to change code or reproduce a finding

80 further.

71 81 

72 82 

73 83 

Details

66 66 

67## Iterate from the live URL67## Iterate from the live URL

68 68 

69Once you have the preview, keep the same task open. Ask Codex to open the URL, fix layout issues, update copy, wire missing data, or read Vercel logs if the deploy fails. The task already has the repo, deployment, and build context.69Once you have the preview, keep the same chat open. Ask Codex to open the URL, fix layout issues, update copy, wire missing data, or read Vercel logs if the deploy fails. The chat already has the repo, deployment, and build context.

70 70 

71Good follow-ups are specific:71Good follow-ups are specific:

72 72 

Details

2name: Draft PRDs from internal context2name: Draft PRDs from internal context

3tagline: Create product requirements documents from Linear, Slack, source3tagline: Create product requirements documents from Linear, Slack, source

4 documents, and meeting notes.4 documents, and meeting notes.

5summary: Use ChatGPT with the $documents skill and connected apps such as5summary: Use ChatGPT with the $documents skill and connected plugins such as

6 Linear, Slack, Notion or Google Drive to create a reviewable PRD with the6 Linear, Slack, Notion or Google Drive to create a reviewable PRD with the

7 expected sections, a timeline, decisions, open questions, and a source7 expected sections, a timeline, decisions, open questions, and a source

8 appendix.8 appendix.


722. Name the sources directly: the Linear project or milestone, the Slack channel or thread, and the docs or notes ChatGPT should cite.722. Name the sources directly: the Linear project or milestone, the Slack channel or thread, and the docs or notes ChatGPT should cite.

733. Give ChatGPT the PRD section contract.733. Give ChatGPT the PRD section contract.

744. Review the source appendix first, then the requirements and open questions.744. Review the source appendix first, then the requirements and open questions.

755. Use the same task to resolve gaps, tighten scope, and prepare the handoff.755. Use the same chat to resolve gaps, tighten scope, and prepare the handoff.

76 76 

77 77 

78 78 

79<a id="refine-in-the-same-chat"></a>79<a id="refine-in-the-same-chat"></a>

80<a id="refine-in-the-same-task"></a>

80 81 

81## Refine in the same task82## Refine in the same chat

82 83 

83Use the starter prompt on this page for the first draft. If something is missing, point ChatGPT at the missing source instead of starting over.84Use the starter prompt on this page for the first draft. If something is missing, point ChatGPT at the missing source instead of starting over.

84 85 

85## Check the source trail86## Check the source trail

86 87 

87Before sharing the PRD, ask ChatGPT to list the claims with weak or missing support, the unresolved questions, and the decisions it treated as confirmed. If the source appendix does not make those easy to audit, keep refining the same task before exporting or posting anything.88Before sharing the PRD, ask ChatGPT to list the claims with weak or missing support, the unresolved questions, and the decisions it treated as confirmed. If the source appendix does not make those easy to audit, keep refining the same chat before exporting or posting anything.

88 89 

89### Suggested prompt90### Suggested prompt

90 91 

Details

92 92 

93You should get a list of things to check and run every time a new event is planned.93You should get a list of things to check and run every time a new event is planned.

94 94 

95## Schedule the playbook from the task95<a id="schedule-the-playbook-from-the-task"></a>

96 96 

97After the first run of your new playbook works, keep the same task open and ask ChatGPT to [schedule the playbook from that task](https://developers.openai.com/codex/automations#schedule-work-from-a-task).97## Schedule a playbook task inside the chat

98 

99After the first run of your new playbook works, keep the same chat open and ask ChatGPT to [schedule a task for the playbook from that chat](https://developers.openai.com/codex/automations#schedule-a-task-inside-a-chat).

Details

65 65 

661. Give ChatGPT the feedback sources and one sentence of context.661. Give ChatGPT the feedback sources and one sentence of context.

672. Ask for a Google Sheet or Doc with themes, evidence links, questions, and follow-ups.672. Ask for a Google Sheet or Doc with themes, evidence links, questions, and follow-ups.

683. Use the same task to turn the reviewed sheet into a Slack update or issue draft.683. Use the same chat to turn the reviewed sheet into a Slack update or issue draft.

694. Pin the task and schedule work from it if the feedback source keeps changing.694. Pin the chat and schedule a task from it if the feedback source keeps changing.

70 70 

71 71 

72 72 


74 74 

75## Turn the sheet into the next draft75## Turn the sheet into the next draft

76 76 

77Once the sheet exists, use the same task to make it useful for the next person. Ask ChatGPT to add a column, split a theme, draft a Slack update, or turn a reviewed theme into an issue draft.77Once the sheet exists, use the same chat to make it useful for the next person. Ask ChatGPT to add a column, split a theme, draft a Slack update, or turn a reviewed theme into an issue draft.

78 78 

79## Keep a feedback channel current79## Keep a feedback channel current

80 80 

81For a Slack channel or issue queue that keeps getting new reports, pin the task and ask ChatGPT to check it on a schedule.81For a Slack channel or issue queue that keeps getting new reports, pin the chat and ask ChatGPT to schedule a task inside it.

Details

32 32 

33If Codex flags a regression or potential issue, you can ask it to fix it by commenting on the pull request with a follow-up prompt like `@codex fix it`.33If Codex flags a regression or potential issue, you can ask it to fix it by commenting on the pull request with a follow-up prompt like `@codex fix it`.

34 34 

35This will start a new cloud task that will fix the issue and update the pull request.35This will start a new cloud chat that will fix the issue and update the pull request.

36 36 

37## Define review guidance37## Define review guidance

38 38 

Details

51 51 

52You can do this in two ways:52You can do this in two ways:

53 53 

54- Iterate on the visual direction using the ImageGen skill, and once you are satisfied with the proposed UI, you can ask Codex to build a prototype matching the visuals. In that case, select Codex, start a new task, and attach the final image you want to implement rather than continuing the ChatGPT chat directly. Codex does better when it can reference a user attachment.54- Iterate on the visual direction using the ImageGen skill, and once you are satisfied with the proposed UI, you can ask Codex to build a prototype matching the visuals. In that case, select Codex, start a new chat, and attach the final image you want to implement rather than continuing the ChatGPT chat directly. Codex does better when it can reference a user attachment.

55- Use a plugin and simply describe your idea: the plugin will generate the visual direction for you and handle next steps.55- Use a plugin and simply describe your idea: the plugin will generate the visual direction for you and handle next steps.

56 56 

57## Leverage a plugin57## Leverage a plugin


73A good proof of concept is scoped to an MVP that can be implemented quickly and validated with the team.73A good proof of concept is scoped to an MVP that can be implemented quickly and validated with the team.

74If you want to make sure the MVP is working as expected, you can use Playwright interactive to let Codex verify its work.74If you want to make sure the MVP is working as expected, you can use Playwright interactive to let Codex verify its work.

75 75 

76Once you have a first version working, you can iterate on it by asking for scoped changes in the same task:76Once you have a first version working, you can iterate on it by asking for scoped changes in the same chat:

Details

9 takes many passes9 takes many passes

10 - Tasks with visual or subjective outputs that need both deterministic checks10 - Tasks with visual or subjective outputs that need both deterministic checks

11 and an LLM-as-a-judge score11 and an LLM-as-a-judge score

12 - Long-running Codex tasks where you want progress tracked clearly instead of12 - Long-running Codex chats where you want progress tracked clearly instead of

13 relying on context13 relying on context

14starterPrompt:14starterPrompt:

15 title: Keep Iterating Until the Eval Passes15 title: Keep Iterating Until the Eval Passes


100 100 

101## Keep a running log of the loop101## Keep a running log of the loop

102 102 

103Long-running work is much more reliable when Codex keeps notes about the loop instead of relying only on the task context.103Long-running work is much more reliable when Codex keeps notes about the loop instead of relying only on the chat context.

104 104 

105That running log should record:105That running log should record:

106 106 

Details

2name: Make granular UI changes2name: Make granular UI changes

3tagline: Use Codex-Spark for fast, focused UI iteration in an existing app.3tagline: Use Codex-Spark for fast, focused UI iteration in an existing app.

4summary: Use Codex to make one small UI adjustment at a time in an existing app,4summary: Use Codex to make one small UI adjustment at a time in an existing app,

5 verify it in the browser, and keep iterating quickly from a popped-out task5 verify it in the browser, and keep iterating quickly from a popped-out chat

6 window near your preview.6 window near your preview.

7skills:7skills:

8 - token: $playwright8 - token: $playwright


68## Development flow68## Development flow

69 69 

701. Open the existing app and get the relevant route or component visible.701. Open the existing app and get the relevant route or component visible.

712. Pop out the active Codex task into a [floating window](https://developers.openai.com/codex/reference/settings#keep-an-app-chat-near-your-work) and keep it near your browser, editor, or design preview while you work.712. Pop out the active Codex chat into a [floating window](https://developers.openai.com/codex/reference/settings#keep-a-chat-near-your-work) and keep it near your browser, editor, or design preview while you work.

723. Give Codex one specific UI change at a time. Include the route, viewport, current screenshot, target screenshot, or exact product note if you have it.723. Give Codex one specific UI change at a time. Include the route, viewport, current screenshot, target screenshot, or exact product note if you have it.

734. Ask Codex to inspect the current implementation, make the smallest defensible edit, and preserve the app's existing components, tokens, layout primitives, and data flow.734. Ask Codex to inspect the current implementation, make the smallest defensible edit, and preserve the app's existing components, tokens, layout primitives, and data flow.

745. Review the result, then send the next small adjustment in the same task.745. Review the result, then send the next small adjustment in the same chat.

75 75 

76## Write small prompts76## Write small prompts

77 77 

Details

531. Ask ChatGPT to review Gmail for emails that need your attention.531. Ask ChatGPT to review Gmail for emails that need your attention.

542. Ask it to use Slack, docs, or project notes for context that explains the bigger picture.542. Ask it to use Slack, docs, or project notes for context that explains the bigger picture.

553. Tell ChatGPT which drafts were useful and which emails it should ignore next time.553. Tell ChatGPT which drafts were useful and which emails it should ignore next time.

564. Schedule work from the task when it becomes useful, and pin it if you want fast access later.564. Schedule a task from the chat when it becomes useful, and pin the chat if you want fast access later.

57 57 

58 58 

59 59 


67 67 

68Over time, ChatGPT should get better at deciding what needs a draft and what can stay out of your way.68Over time, ChatGPT should get better at deciding what needs a draft and what can stay out of your way.

69 69 

70## Schedule email triage from the task70<a id="schedule-email-triage-from-the-task"></a>

71 71 

72You can schedule an inbox check-in from the same task. On each scheduled run, ChatGPT checks Gmail and the context sources you named, then posts only when there are emails that need your attention or drafts worth reviewing.72## Schedule an email triage task inside the chat

73 

74You can schedule an inbox check-in task from the same chat. On each scheduled run, ChatGPT checks Gmail and the context sources you named, then posts only when there are emails that need your attention or drafts worth reviewing.

73 75 

74Once the drafts look useful, ask ChatGPT to keep an eye on Gmail. Email triage is a good job to automate: the drafts are reviewable, and you still decide what gets sent.76Once the drafts look useful, ask ChatGPT to keep an eye on Gmail. Email triage is a good job to automate: the drafts are reviewable, and you still decide what gets sent.

75 77 

76Use [scheduled work from a task](https://developers.openai.com/codex/automations#schedule-work-from-a-task) after the task has a good sense of your reply patterns. If ChatGPT finds an email that needs a decision it cannot make, it should flag the question instead of guessing.78You can [schedule a task inside this chat](https://developers.openai.com/codex/automations#schedule-a-task-inside-a-chat) after the chat has a good sense of your reply patterns. If ChatGPT finds an email that needs a decision it cannot make, it should flag the question instead of guessing.

77 79 

78## Organize your inbox80## Organize your inbox

79 81 

Details

120 120 

121 121 

122 122 

123If the brief includes private or sensitive information, keep the output local to the task and ask ChatGPT to flag anything that doesn't belong in a shared doc.123If the brief includes private or sensitive information, keep the output local to the chat and ask ChatGPT to flag anything that doesn't belong in a shared doc.

Details

37 37 

38 Use the KPI dashboard, metric definitions, close workbook, revenue and38 Use the KPI dashboard, metric definitions, close workbook, revenue and

39 expense tables, forecast update, prior review, and owner notes I provide. If39 expense tables, forecast update, prior review, and owner notes I provide. If

40 any inputs are in connected apps, use only the exact @google-drive files or40 any inputs are in connected plugins, use only the exact @google-drive files

41 @slack threads I name.41 or @slack threads I name.

42 42 

43 43 

44 Create an editable document with a short leadership summary, material KPI44 Create an editable document with a short leadership summary, material KPI

Details

11 - token: google-drive11 - token: google-drive

12 url: https://github.com/openai/plugins/tree/main/plugins/google-drive12 url: https://github.com/openai/plugins/tree/main/plugins/google-drive

13 description: Bring approved docs, tracker templates, exports, and shared13 description: Bring approved docs, tracker templates, exports, and shared

14 onboarding folders into the task context.14 onboarding folders into the chat context.

15 - token: notion15 - token: notion

16 url: https://github.com/openai/plugins/tree/main/plugins/notion16 url: https://github.com/openai/plugins/tree/main/plugins/notion

17 description: Reference onboarding plans, project pages, checklists, and team17 description: Reference onboarding plans, project pages, checklists, and team

Details

722. Ask it to inventory access gaps before drawing conclusions.722. Ask it to inventory access gaps before drawing conclusions.

733. Run the starter prompt to create priorities, meeting preparation, replies, decisions, and FYIs.733. Run the starter prompt to create priorities, meeting preparation, replies, decisions, and FYIs.

744. Review the source links, move uncertain items into an open-questions list, and tell ChatGPT which items were useful or noisy.744. Review the source links, move uncertain items into an open-questions list, and tell ChatGPT which items were useful or noisy.

755. Continue in the same task when a priority needs a draft, a deeper source review, or a recurring check.755. Continue in the same chat when a priority needs a draft, a deeper source review, or a recurring check.

76 76 

77 77 

78 78 


80 80 

81## Make the brief recurring81## Make the brief recurring

82 82 

83Start with one manual brief. After the structure reliably surfaces the right priorities, schedule work from the same task so ChatGPT can return to the approved sources each morning and compare the new brief with the previous one. Keep correcting the task when it overweights noise or misses an important source.83Start with one manual brief. After the structure reliably surfaces the right priorities, schedule a task from the same chat so ChatGPT can return to the approved sources each morning and compare the new brief with the previous one. Keep correcting the chat when it overweights noise or misses an important source.

84 84 

85## Review what changed85## Review what changed

86 86 

Details

52 52 

53- `@Computer Test my app in staging. Cover signup, invite a teammate, and upgrade billing. Log every bug with repro steps, expected result, actual result, and severity.`53- `@Computer Test my app in staging. Cover signup, invite a teammate, and upgrade billing. Log every bug with repro steps, expected result, actual result, and severity.`

54 54 

55If you already maintain a test-plan file in the repo, attach it to the task or point Codex at it so the QA pass follows your existing flows.55If you already maintain a test-plan file in the repo, attach it to the chat or point Codex at it so the QA pass follows your existing flows.

56 56 

57## Practical tips57## Practical tips

58 58 


70 70 

71## Good follow-ups71## Good follow-ups

72 72 

73After the QA pass, keep the same task open and ask Codex to fix one of the bugs it found, turn the findings into Linear or GitHub-ready drafts, or narrow the next pass to one specific failing flow.73After the QA pass, keep the same chat open and ask Codex to fix one of the bugs it found, turn the findings into Linear or GitHub-ready drafts, or narrow the next pass to one specific failing flow.

74 74 

75## Suggested prompt75## Suggested prompt

76 76 

Details

64 64 

65Check every recommendation against the cited source. Confirm that required content, accessibility guidance, institutional policy, and instructor discretion are represented correctly.65Check every recommendation against the cited source. Confirm that required content, accessibility guidance, institutional policy, and instructor discretion are represented correctly.

66 66 

67After approving the plan, continue in the same task and revise one group of files at a time. Preserve the originals and ask for a change summary after each revision pass.67After approving the plan, continue in the same chat and revise one group of files at a time. Preserve the originals and ask for a change summary after each revision pass.

Details

543. Define base, upside, and downside rules along with protected assumptions.543. Define base, upside, and downside rules along with protected assumptions.

554. Run the starter prompt and request an editable forecast workbook.554. Run the starter prompt and request an editable forecast workbook.

565. Review assumption changes, formula links, sensitivities, and approval items.565. Review assumption changes, formula links, sensitivities, and approval items.

576. Continue in the same task to tune one driver at a time.576. Continue in the same chat to tune one driver at a time.

58 58 

59 59 

60 60 

Details

1---1---

2name: Save workflows as skills2name: Save workflows as skills

3tagline: Create a skill Codex can keep on hand for work you repeat.3tagline: Create a skill Codex can keep on hand for work you repeat.

4summary: Turn a working Codex task, review rules, test commands, release4summary: Turn a working Codex chat, review rules, test commands, release

5 checklists, design conventions, writing examples, or repo-specific scripts5 checklists, design conventions, writing examples, or repo-specific scripts

6 into a skill Codex can use in future tasks.6 into a skill Codex can use in future tasks.

7skills:7skills:


12bestFor:12bestFor:

13 - Codified workflows you want Codex to use again.13 - Codified workflows you want Codex to use again.

14 - Teams that want a reusable skill instead of a long prompt pasted into every14 - Teams that want a reusable skill instead of a long prompt pasted into every

15 task.15 chat.

16starterPrompt:16starterPrompt:

17 title: Create a Skill From My Context17 title: Create a Skill From My Context

18 body: >-18 body: >-


23 23 

24 Use these sources when creating the skill:24 Use these sources when creating the skill:

25 25 

26 - Working example: [say "use this task," link a merged PR, or paste a good26 - Working example: [say "use this chat," link a merged PR, or paste a good

27 Codex answer]27 Codex answer]

28 28 

29 - Source: [paste a Slack thread, PR review link, runbook URL, docs URL, or29 - Source: [paste a Slack thread, PR review link, runbook URL, docs URL, or


45 45 

46Use skills to give Codex reusable instructions, resources, and scripts for work you repeat. A [skill](https://developers.openai.com/codex/build-skills) can preserve the task, doc, command, or example that made Codex useful the first time.46Use skills to give Codex reusable instructions, resources, and scripts for work you repeat. A [skill](https://developers.openai.com/codex/build-skills) can preserve the task, doc, command, or example that made Codex useful the first time.

47 47 

48Start with one working example: a Codex task that cherry-picked a PR, a release checklist from Notion, a set of useful PR comments, or a Slack thread explaining a launch process.48Start with one working example: a Codex chat that cherry-picked a PR, a release checklist from Notion, a set of useful PR comments, or a Slack thread explaining a launch process.

49 49 

50## How to use50## How to use

51 51 


53 53 

541. Add the context you want Codex to use.541. Add the context you want Codex to use.

55 55 

56 Stay in the Codex task you want to preserve, paste the Slack thread or docs link, and add the rule, command, or example Codex should remember.56 Stay in the Codex chat you want to preserve, paste the Slack thread or docs link, and add the rule, command, or example Codex should remember.

57 57 

582. Run the starter prompt.582. Run the starter prompt.

59 59 


65 65 

66 Skills in `~/.codex/skills` are available from any repo. Skills in the current repo can be committed so teammates can use them too.66 Skills in `~/.codex/skills` are available from any repo. Skills in the current repo can be committed so teammates can use them too.

67 67 

684. Use the skill, then update it from the task.684. Use the skill, then update it from the chat.

69 69 

70 Invoke the new `$skill-name` on the next PR, alert, review, release note, or design task. If it uses the wrong test command, misses a review rule, skips a runbook step, or writes a draft you would not send, ask Codex to add that correction to the skill.70 Invoke the new `$skill-name` on the next PR, alert, review, release note, or design task. If it uses the wrong test command, misses a review rule, skips a runbook step, or writes a draft you would not send, ask Codex to add that correction to the skill.

71 71 


77 77 

78| What you have | What to add |78| What you have | What to add |

79| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |79| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

80| **A workflow from a Codex task that you want to preserve** | Stay in that task and say `use this task`. Codex can use the task context, commands, edits, and feedback as the starting point. |80| **A workflow from a Codex chat that you want to preserve** | Stay in that chat and say `use this chat`. Codex can use the chat context, commands, edits, and feedback as the starting point. |

81| **Docs or a runbook** | Paste the release checklist, link the incident-response runbook, attach the API PDF, or point Codex at the markdown guide in your repo. |81| **Docs or a runbook** | Paste the release checklist, link the incident-response runbook, attach the API PDF, or point Codex at the markdown guide in your repo. |

82| **Team conversation** | Paste the Slack thread where someone explained an alert, link the PR review with frontend rules, or attach the support conversation that explains the customer problem. |82| **Team conversation** | Paste the Slack thread where someone explained an alert, link the PR review with frontend rules, or attach the support conversation that explains the customer problem. |

83| **Scripts or commands the skill should reuse** | Add the test command, preview command, release script, log-fetch script, or local helper command you want future Codex tasks to run. |83| **Scripts or commands the skill should reuse** | Add the test command, preview command, release script, log-fetch script, or local helper command you want future Codex tasks to run. |

84| **A good result** | Add the merged PR, final changelog entry, accepted launch note, resolved ticket, before/after screenshot, or final Codex answer you want future tasks to match. |84| **A good result** | Add the merged PR, final changelog entry, accepted launch note, resolved ticket, before/after screenshot, or final Codex answer you want future tasks to match. |

85 85 

86If the source is in Slack, Linear, GitHub, Notion, or Sentry, connect that tool in Codex with a [plugin](https://developers.openai.com/codex/plugins), mention it in the starter prompt, or paste the relevant part into the task.86If the source is in Slack, Linear, GitHub, Notion, or Sentry, connect that tool in Codex with a [plugin](https://developers.openai.com/codex/plugins), mention it in the starter prompt, or paste the relevant part into the chat.

87 87 

88## What Codex creates88## What Codex creates

89 89 

Details

1---1---

2name: Annotate scRNA-seq data2name: Annotate scRNA-seq data

3tagline: Review single-cell QC, annotations, and UMAPs in one task.3tagline: Review single-cell QC, annotations, and UMAPs in one chat.

4summary: Use ChatGPT with the NGS Analysis plugin to turn a 10x-style matrix4summary: Use ChatGPT with the NGS Analysis plugin to turn a 10x-style matrix

5 bundle into QC-filtered single-cell artifacts, threshold-justified filtering5 bundle into QC-filtered single-cell artifacts, threshold-justified filtering

6 summaries, annotations, and UMAPs you can inspect and revise in the same task.6 summaries, annotations, and UMAPs you can inspect and revise in the same chat.

7skills:7skills:

8 - token: NGS Analysis8 - token: NGS Analysis

9 url: codex://plugins/ngs-analysis@openai-curated9 url: codex://plugins/ngs-analysis@openai-curated


621. Point ChatGPT to the appropriate matrix, barcodes, genes or features, manifest, and dataset metadata, or provide exact file references.621. Point ChatGPT to the appropriate matrix, barcodes, genes or features, manifest, and dataset metadata, or provide exact file references.

632. Run the starter prompt so ChatGPT can choose QC thresholds from the observed distributions and record the rationale in the run artifacts.632. Run the starter prompt so ChatGPT can choose QC thresholds from the observed distributions and record the rationale in the run artifacts.

643. Open the visualization index and review notebook or app to inspect QC pass or fail counts, UMAPs, and annotation confidence.643. Open the visualization index and review notebook or app to inspect QC pass or fail counts, UMAPs, and annotation confidence.

654. Continue in the same task to refine thresholds, supply a matched reference atlas, or rerun after unblocking doublet detection.654. Continue in the same chat to refine thresholds, supply a matched reference atlas, or rerun after unblocking doublet detection.

66 66 

67 67 

68 68 


83 83 

84Finally, review the cell-level metrics and filtering outcomes. ChatGPT preserves84Finally, review the cell-level metrics and filtering outcomes. ChatGPT preserves

85this table with the filtered `.h5ad` and visualization artifacts so you can85this table with the filtered `.h5ad` and visualization artifacts so you can

86revise the thresholds in the same task without losing the rationale for the86revise the thresholds in the same chat without losing the rationale for the

87first pass.87first pass.

88 88 

89![Open cell-level QC metrics and filtering outcomes for review.](https://developers.openai.com/codex/use-cases/scrna-seq-post-count-qc-screenshot-3.webp)89![Open cell-level QC metrics and filtering outcomes for review.](https://developers.openai.com/codex/use-cases/scrna-seq-post-count-qc-screenshot-3.webp)

Details

85 85 

86 86 

87 87 

88After trying this and tweaking the flow to match your needs, you can [schedule the work from the task](https://developers.openai.com/codex/automations#schedule-work-from-a-task) by asking ChatGPT to do the same thing on a schedule.88After trying this and tweaking the flow to match your needs, you can [schedule a task for the work from the chat](https://developers.openai.com/codex/automations#schedule-a-task-inside-a-chat) by asking ChatGPT to do the same thing on a schedule.

89 89 

90## Ask for the right output90## Ask for the right output

91 91 


120 120 

121## Draft the follow-up121## Draft the follow-up

122 122 

123Once the queue is right, keep the action in the same task. Ask ChatGPT to draft a reply or handoff from the evidence it already gathered:123Once the queue is right, keep the action in the same chat. Ask ChatGPT to draft a reply or handoff from the evidence it already gathered:

Details

1---1---

2name: Kick off coding tasks from Slack2name: Kick off coding tasks from Slack

3tagline: Turn Slack threads into scoped cloud tasks.3tagline: Turn Slack threads into scoped cloud chats.

4summary: Mention `@Codex` in Slack to start a task tied to the right repo and4summary: Mention `@Codex` in Slack to start a chat tied to the right repo and

5 environment, then review the result back in the thread or in Codex cloud.5 environment, then review the result back in the thread or in Codex cloud.

6bestFor:6bestFor:

7 - Async handoffs that start in a Slack thread and already have enough context7 - Async handoffs that start in a Slack thread and already have enough context


24 24 

251. Install the Slack app, connect the right repositories and environments, and add `@Codex` to the channel.251. Install the Slack app, connect the right repositories and environments, and add `@Codex` to the channel.

262. Mention `@Codex` in a thread with a clear request, constraints, and the outcome you want.262. Mention `@Codex` in a thread with a clear request, constraints, and the outcome you want.

273. Open the task link, review the result, and continue the follow-up in Slack if the task needs another pass.273. Open the chat link, review the result, and continue the follow-up in Slack if the task needs another pass.

28 28 

29You can learn more about how to use Codex in Slack in the [dedicated guide](https://developers.openai.com/codex/third-party/slack).29You can learn more about how to use Codex in Slack in the [dedicated guide](https://developers.openai.com/codex/third-party/slack).

30 30 

Details

931. Start with a concrete comparison question and the exact targets, disease, and evidence lanes you want ChatGPT to cover.931. Start with a concrete comparison question and the exact targets, disease, and evidence lanes you want ChatGPT to cover.

942. Invoke the `Life Science Research` plugin and tell ChatGPT to run the lanes in parallel with subagents so each evidence family stays bounded.942. Invoke the `Life Science Research` plugin and tell ChatGPT to run the lanes in parallel with subagents so each evidence family stays bounded.

953. Ask ChatGPT to score each lane on a fixed 1-5 scale and to keep direct disease evidence separate from adjacent phenotypes.953. Ask ChatGPT to score each lane on a fixed 1-5 scale and to keep direct disease evidence separate from adjacent phenotypes.

964. Review the saved raw payloads, the lane-by-target score table, and the synthesized rank in the same task.964. Review the saved raw payloads, the lane-by-target score table, and the synthesized rank in the same chat.

Details

101 101 

102If the process has more steps, turn it into a [skill](https://developers.openai.com/codex/build-skills) so future Codex tasks can follow the same source-checking, drafting, and verification loop. See [Save workflows as skills](https://developers.openai.com/codex/use-cases/reusable-codex-skills) for more details on this pattern.102If the process has more steps, turn it into a [skill](https://developers.openai.com/codex/build-skills) so future Codex tasks can follow the same source-checking, drafting, and verification loop. See [Save workflows as skills](https://developers.openai.com/codex/use-cases/reusable-codex-skills) for more details on this pattern.

103 103 

104You can also [schedule this workflow from the current task](https://developers.openai.com/codex/automations#schedule-work-from-a-task). For example, ask Codex to fetch recent GitHub pull requests and keep the docs current every week:104You can also [schedule a task for this workflow from the current chat](https://developers.openai.com/codex/automations#schedule-a-task-inside-a-chat). For example, ask Codex to fetch recent GitHub pull requests and keep the docs current every week:

Details

72 72 

73## Good follow-ups73## Good follow-ups

74 74 

75Once the task finishes, keep the same task open if you want ChatGPT to summarize what it changed, double-check the result, or turn the workflow into a more repeatable pattern through [customization](https://developers.openai.com/codex/customization/overview).75Once the work finishes, keep the same chat open if you want ChatGPT to summarize what it changed, double-check the result, or turn the workflow into a more repeatable pattern through [customization](https://developers.openai.com/codex/customization/overview).

76 76 

77## Suggested prompt77## Suggested prompt

78 78 

Details

75 75 

76## Move from mock to prototype76## Move from mock to prototype

77 77 

78Use the final mock image that you want Codex to implement. Select Codex, start a new task, and reattach the image rather than continuing the ChatGPT chat directly. Then ask Codex to implement the mock—optionally using the [Build Web Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-web-apps) if you're building a web app—to turn it into a working prototype:78Use the final mock image that you want Codex to implement. Select Codex, start a new chat, and reattach the image rather than continuing the ChatGPT chat directly. Then ask Codex to implement the mock—optionally using the [Build Web Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-web-apps) if you're building a web app—to turn it into a working prototype:

Details

562. Define the comparison, materiality threshold, and required finance lines.562. Define the comparison, materiality threshold, and required finance lines.

573. Run the starter prompt and ask for an editable bridge workbook.573. Run the starter prompt and ask for an editable bridge workbook.

584. Review source breaks, sign conventions, and driver rankings.584. Review source breaks, sign conventions, and driver rankings.

595. Continue in the same task to resolve owner questions and prepare commentary.595. Continue in the same chat to resolve owner questions and prepare commentary.

60 60 

61 61 

62 62 

Details

108 108 

109## Follow up on the first draft109## Follow up on the first draft

110 110 

111After the first package is ready, use the same task to tune it for the audience or next workflow.111After the first package is ready, use the same chat to tune it for the audience or next workflow.

112 112 

113You can also ask ChatGPT to compare this call with the last few weekly calls, turn action items into a mutual action plan, create a version for a sales engineer with only technical blockers, or draft CRM updates without saving them.113You can also ask ChatGPT to compare this call with the last few weekly calls, turn action items into a mutual action plan, create a version for a sales engineer with only technical blockers, or draft CRM updates without saving them.

114 114 

115## Automate recurring meeting intelligence115## Automate recurring meeting intelligence

116 116 

117For weekly account check-ins or deal reviews, pin the task and ask ChatGPT to [schedule the follow-up work from it](https://developers.openai.com/codex/automations#schedule-work-from-a-task).117For weekly account check-ins or deal reviews, pin the chat and ask ChatGPT to [schedule a task for the follow-up work from it](https://developers.openai.com/codex/automations#schedule-a-task-inside-a-chat).

118 118 

119You don't necessarily want ChatGPT to post automatically, but it can create drafts for your review that you can approve and post.119You don't necessarily want ChatGPT to post automatically, but it can create drafts for your review that you can approve and post.

use-chatgpt.md +36 −14

Details

23 23 

24## Choose how you want to work24## Choose how you want to work

25 25 

26Open Quick Chat to start an ordinary ChatGPT chat for a question or26Use Chat mode for a question or back-and-forth. Switch to Work mode when you want

27conversation. Use ChatGPT Work when you want to carry a larger task through to27ChatGPT to carry a larger task through to a reviewable result. Select Codex when

28a reviewable result. For software development and technical tasks, use Codex.28you want developer views or more technical detail, especially for software

29development.

29 30 

30| Choose | When you want to | Examples |31| Choose | When you want to | Examples |

31| ------------ | --------------------------------------------- | ---------------------------------------------------------------------------- |32| --------- | --------------------------------------------- | ---------------------------------------------------------------------------- |

32| Chat | Work through something with ChatGPT | Ask a question, search the web, brainstorm, draft a message, compare options |33| Chat mode | Work through something with ChatGPT | Ask a question, search the web, brainstorm, draft a message, compare options |

33| ChatGPT Work | Define an outcome and get a reviewable result | Create a deck, analyze files, draft a report, build a project plan |34| Work mode | Define an outcome and get a reviewable result | Create a deck, analyze files, draft a report, build a project plan |

34| Codex | Work on software or technical tasks | Debug code, run tests, review a PR, implement a feature |35| Codex | Use developer tools and see technical details | Debug code, run tests, review a PR, implement a feature |

35 36 

36Quick Chat is a good place to begin when you want to:37In Codex, point to **New chat**, then select the **Quick chat** icon on its right

38when you want to:

37 39 

38- Ask a question, search the web, or learn about a topic.40- Ask a question, search the web, or learn about a topic.

39- Get an unfamiliar idea explained in simpler language.41- Get an unfamiliar idea explained in simpler language.


44- Compare options or think through a decision.46- Compare options or think through a decision.

45- Clarify what you need before starting a larger task.47- Clarify what you need before starting a larger task.

46 48 

47When you need a substantial, reviewable result, switch to Work and describe the49When you need a substantial, reviewable result, switch to Work mode and describe

48outcome you need. See [Get started with Work](https://learn.chatgpt.com/docs/get-started-with-work) for50the outcome you need. See [Get started with Work mode](https://learn.chatgpt.com/docs/get-started-with-work)

49example tasks, prompts, and best practices.51for example tasks, prompts, and best practices.

52 

53### Compare Work mode and Codex on desktop

54 

55Work mode and Codex use the same agent, and their capabilities overlap. If you

56prefer Codex, you can keep using it for research, documents, presentations, and

57other knowledge work. When both are available to you, the desktop app changes

58the interface and how the agent presents its work.

59 

60<ToggleSection title="Detailed comparison">

61 

62| Difference | ChatGPT in Desktop app | Codex in Desktop app |

63| ------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------- |

64| Where to start | Select **ChatGPT**, then switch the composer to **Work** | Select **Codex** in the product selector |

65| Chats you see | See Chat-mode chats started in ChatGPT on web and mobile, plus Work-mode chats | Focus on Codex chats and development projects |

66| Quick chat | Not available | When available, access ChatGPT chats from web and mobile in Codex |

67| Technical detail | Hide technical details like Git or shell commands | See developer details, including diff and review views |

68| Agent communication | Prefers nontechnical language and finished outputs | Can include technical and implementation details |

69| Pull requests pane | Not available in Work mode | Available when enabled |

70 

71</ToggleSection>

50 72 

51### Talk to ChatGPT naturally73### Talk to ChatGPT naturally

52 74 


100### Keep related work in a project122### Keep related work in a project

101 123 

102Projects help you organize ChatGPT around a topic, goal, or ongoing body of124Projects help you organize ChatGPT around a topic, goal, or ongoing body of

103work. Keep related conversations, tasks, files, and instructions in one project125work. Keep related chats, files, and instructions in one project

104when the work will continue over time or depend on the same context. [Learn more126when the work will continue over time or depend on the same context. [Learn more

105about projects.](https://learn.chatgpt.com/docs/projects)127about projects.](https://learn.chatgpt.com/docs/projects)

106 128 


122 144 

123Plugins can connect ChatGPT to the tools and information you use for work, such145Plugins can connect ChatGPT to the tools and information you use for work, such

124as Google Drive, SharePoint, Salesforce, or Gong. Use them when a task depends146as Google Drive, SharePoint, Salesforce, or Gong. Use them when a task depends

125on information outside the conversation, actions in another system, or a147on information outside the chat, actions in another system, or a

126repeatable workflow.148repeatable workflow.

127 149 

128Plugin availability depends on your plan, workspace settings, and the plugin150Plugin availability depends on your plan, workspace settings, and the plugin


179 <span slot="icon">201 <span slot="icon">

180 <Settings />202 <Settings />

181 </span>203 </span>

182 Set preferences and carry useful context across chats and tasks.204 Set preferences and carry useful context across chats.

183 </IconItem>](https://learn.chatgpt.com/docs/personalize)205 </IconItem>](https://learn.chatgpt.com/docs/personalize)

184</div>206</div>

visualizations.md +10 −10

Details

2 2 

3Visualizations turn questions, ideas, and information into charts, maps,3Visualizations turn questions, ideas, and information into charts, maps,

4diagrams, calculators, simulations, and interactive explainers you can explore4diagrams, calculators, simulations, and interactive explainers you can explore

5in a ChatGPT conversation. Use one when adjusting inputs or seeing a5in a ChatGPT chat. Use one when adjusting inputs or seeing a

6relationship would make an answer easier to understand, compare, practice, or6relationship would make an answer easier to understand, compare, practice, or

7act on.7act on.

8 8 


31 31 

32| Surface | Current availability |32| Surface | Current availability |

33| --------------------------- | ----------------------------------------------------------------------------- |33| --------------------------- | ----------------------------------------------------------------------------- |

34| ChatGPT on the web | Available to supported accounts in Chat and ChatGPT Work |34| ChatGPT on the web | Available to supported accounts in Chat mode and Work mode |

35| ChatGPT desktop app | Rolling out in preview |35| ChatGPT desktop app | Rolling out in preview |

36| ChatGPT mobile apps | Rolling out to eligible accounts; composer controls can differ by app version |36| ChatGPT mobile apps | Rolling out to eligible accounts; composer controls can differ by app version |

37| Codex CLI and IDE extension | Visualization rendering isn't supported |37| Codex CLI and IDE extension | Visualization rendering isn't supported |


70/>70/>

71 71 

72Tell ChatGPT which information to use, such as content already in the72Tell ChatGPT which information to use, such as content already in the

73conversation, pasted data, an attached file, or an available connected source.73chat, pasted data, an attached file, or an available connected source.

74For complex requests, choose a higher reasoning setting when one is available.74For complex requests, choose a higher reasoning setting when one is available.

75 75 

76## Explore interactive examples76## Explore interactive examples


85 85 

86## Refine and continue86## Refine and continue

87 87 

88Continue in the same conversation and describe the change you want. Useful88Continue in the same chat and describe the change you want. Useful

89follow-ups include:89follow-ups include:

90 90 

91- Add or remove a control, filter, comparison, or annotation.91- Add or remove a control, filter, comparison, or annotation.


101 101 

102## Share or reuse a result102## Share or reuse a result

103 103 

104Use the conversation's standard **Share** action when it's available. Review104Use the chat's standard **Share** action when it's available. Review

105the entire shared conversation first, including its source data and earlier105the entire shared chat first, including its source data and earlier

106messages. A visualization is generally a snapshot of the information available106messages. A visualization is generally a snapshot of the information available

107when ChatGPT created it, not a live dashboard that stays synchronized with a107when ChatGPT created it, not a live dashboard that stays synchronized with a

108connected source.108connected source.


121## Recover from a failed result121## Recover from a failed result

122 122 

123Visualizations can take a minute or longer to generate. If the result is blank123Visualizations can take a minute or longer to generate. If the result is blank

124or missing, wait for the response to finish, reload the conversation once, and124or missing, wait for the response to finish, reload the chat once, and

125then retry. If it still fails:125then retry. If it still fails:

126 126 

127- Ask for a smaller or simpler visualization.127- Ask for a smaller or simpler visualization.


130- Verify important values, geographic boundaries, and source assumptions.130- Verify important values, geographic boundaries, and source assumptions.

131- Ask for a chart, diagram, table, or Site instead.131- Ask for a chart, diagram, table, or Site instead.

132 132 

133Use the same data-handling judgment you use for any ChatGPT conversation. Only133Use the same data-handling judgment you use for any ChatGPT chat. Only

134include sensitive information when your organization permits it, and review134include sensitive information when your organization permits it, and review

135the full conversation before you share it.135the full chat before you share it.

136 136 

137## Related docs137## Related docs

138 138 

139- [Sites](https://learn.chatgpt.com/docs/sites)139- [Sites](https://learn.chatgpt.com/docs/sites)

140- [Projects, chats, and tasks](https://learn.chatgpt.com/docs/projects)140- [Projects and chats](https://learn.chatgpt.com/docs/projects)

141- [Work with files](https://learn.chatgpt.com/docs/artifacts-viewer)141- [Work with files](https://learn.chatgpt.com/docs/artifacts-viewer)

142- [Image generation](https://learn.chatgpt.com/docs/image-generation)142- [Image generation](https://learn.chatgpt.com/docs/image-generation)

whats-new.md +37 −33

Details

6 6 

7## July 6–10, 20267## July 6–10, 2026

8 8 

9### Take on ambitious work with ChatGPT Work9<a id="take-on-ambitious-work-with-chatgpt-work"></a>

10 10 

11[ChatGPT Work](https://learn.chatgpt.com/docs/get-started-with-work) is an agent in11### Take on ambitious work in ChatGPT

12ChatGPT that can gather context from your files and [plugins](https://learn.chatgpt.com/docs/plugins),12 

13[Work mode](https://learn.chatgpt.com/docs/get-started-with-work) in ChatGPT can gather context from

14your files and [plugins](https://learn.chatgpt.com/docs/plugins),

13take action across workflows, and create reviewable documents, presentations,15take action across workflows, and create reviewable documents, presentations,

14spreadsheets, Sites, and other finished work. Powered by16spreadsheets, Sites, and other finished work. Powered by

15[GPT-5.6](https://learn.chatgpt.com/docs/models), it can break a goal into steps and work for hours while17[GPT-5.6](https://learn.chatgpt.com/docs/models), it can break a goal into steps and work for hours while


27### Choose the right GPT-5.6 model29### Choose the right GPT-5.6 model

28 30 

29The [GPT-5.6 family](https://learn.chatgpt.com/docs/models#recommended-models) offers three recommended31The [GPT-5.6 family](https://learn.chatgpt.com/docs/models#recommended-models) offers three recommended

30models across ChatGPT Work, the ChatGPT desktop app, Codex CLI, and the Codex IDE32models across Work mode in ChatGPT, the ChatGPT desktop app, Codex CLI, and the Codex IDE

31extension. Sol is the flagship for complex coding, computer use, research, and33extension. Sol is the flagship for complex coding, computer use, research, and

32security work. Terra balances capability and cost for everyday work, while Luna34security work. Terra balances capability and cost for everyday work, while Luna

33is the fastest, lowest-cost option. The default **Power** setting uses Sol with35is the fastest, lowest-cost option. The default **Power** setting uses Sol with


35 37 

36### Use Codex in the ChatGPT desktop app38### Use Codex in the ChatGPT desktop app

37 39 

38On July 9, the Codex app merges into the new40On July 9, the Codex app merged into the

39[ChatGPT desktop app](https://learn.chatgpt.com/docs/app) for macOS and Windows. Codex keeps its41[ChatGPT desktop app](https://learn.chatgpt.com/docs/app) for macOS and Windows. Codex keeps its

40dedicated coding experience alongside Chat and Work, with inline editing in42dedicated coding experience alongside ChatGPT's Chat and Work modes. The Codex

41diffs, pull request review in the side panel, faster43experience includes inline editing in diffs, pull request review in the side panel, faster

42[Computer Use](https://learn.chatgpt.com/docs/computer-use) powered by GPT-5.6, and multi-repository44[Computer Use](https://learn.chatgpt.com/docs/computer-use) powered by GPT-5.6, and multi-repository

43projects.45projects.

44 46 


57and replay it with new inputs. Initial availability excludes the EEA, the59and replay it with new inputs. Initial availability excludes the EEA, the

58United Kingdom, and Switzerland, and requires Computer Use.60United Kingdom, and Switzerland, and requires Computer Use.

59 61 

60<a id="continue-a-chat-on-another-host"></a>62<a id="continue-a-task-on-another-host"></a>

61 63 

62### Continue a task on another host64### Continue a chat on another host

63 65 

64[Task handoff](https://learn.chatgpt.com/docs/remote-connections#hand-off-a-task-between-hosts)66[Chat handoff](https://learn.chatgpt.com/docs/remote-connections#hand-off-a-chat-between-hosts)

65moves a task and its Git state between your local computer and a connected67moves a chat and its Git state between your local computer and a connected

66remote host. Codex can create or reuse a worktree on the destination, transfer68remote host. Codex can create or reuse a worktree on the destination, transfer

67the task, and continue from the matching project.69the chat, and continue from the matching project.

68 70 

69The same desktop release adds bulk actions to scheduled run history, so71The same desktop release adds bulk actions to scheduled run history, so

70you can mark every run as read or archive eligible runs together.72you can mark every run as read or archive eligible runs together.


72### Browse and review workspaces from iOS74### Browse and review workspaces from iOS

73 75 

74In the ChatGPT mobile app, **Remote** added a workspace file browser, a76In the ChatGPT mobile app, **Remote** added a workspace file browser, a

75directory picker for new tasks, expand-and-collapse controls for diffs, and77directory picker for new chats, expand-and-collapse controls for diffs, and

76per-task or cross-task MCP approval choices on iOS.78per-chat or cross-chat MCP approval choices on iOS.

77 79 

78Computer Use, the Chrome extension, Memories, and Chronicle also began80Computer Use, the Chrome extension, Memories, and Chronicle also began

79rolling out to the EEA, the United Kingdom, and Switzerland. Memories remain81rolling out to the EEA, the United Kingdom, and Switzerland. Memories remain


114 116 

115New migration flows can import supported setup from other coding agents during117New migration flows can import supported setup from other coding agents during

116onboarding. The Codex app also added `/init` for creating project instructions,118onboarding. The Codex app also added `/init` for creating project instructions,

117plus improved plugin management, browser diagnostics, and completed-task119plus improved plugin management, browser diagnostics, and completed-chat

118summaries.120summaries.

119 121 

120### Set up Codex tasks from iOS122<a id="set-up-codex-tasks-from-ios"></a>

123 

124### Set up Codex chats from iOS

121 125 

122Remote on iOS can now choose a branch, create a worktree, run an environment126Remote on iOS can now choose a branch, create a worktree, run an environment

123setup script, manage goals, and add inline review comments.127setup script, manage goals, and add inline review comments.


167 prompt={`Use @Computer to open the Windows app, reproduce the export failure, save a diagnostic file, and summarize the exact steps that trigger the problem.`}171 prompt={`Use @Computer to open the Windows app, reproduce the export failure, save a diagnostic file, and summarize the exact steps that trigger the problem.`}

168/>172/>

169 173 

170Remote on iOS also added Spotlight and Shortcuts entry points, archived-task174Remote on iOS also added Spotlight and Shortcuts entry points, archived-chat

171browsing, `/side`, and options to save or copy rendered images. The desktop app175browsing, `/side`, and options to save or copy rendered images. The desktop app

172added task coordination for local projects and worktrees, content and176added chat coordination for local projects and worktrees, content and

173branch-name search for past tasks, and consistent visual identifiers for177branch-name search for past chats, and consistent visual identifiers for

174background subagents.178background subagents.

175 179 

176Read the [May 25 iOS](https://learn.chatgpt.com/docs/changelog#codex-2026-05-25-mobile) and180Read the [May 25 iOS](https://learn.chatgpt.com/docs/changelog#codex-2026-05-25-mobile) and


281 variant="no-wallpaper"285 variant="no-wallpaper"

282/>286/>

283 287 

284<a id="start-with-a-chat-and-keep-it-moving"></a>288<a id="start-with-a-task-and-keep-it-moving"></a>

285 289 

286### Start with a task and keep it moving290### Start with a chat and keep it moving

287 291 

288[Standalone tasks](https://learn.chatgpt.com/docs/projects#start-without-a-project) made it292[Standalone chats](https://learn.chatgpt.com/docs/projects#start-without-a-project) made it

289possible to begin without choosing a project folder. The same release added293possible to begin without choosing a project folder. The same release added

290[scheduled work from a task](https://learn.chatgpt.com/docs/automations#schedule-work-from-a-task),294[scheduled tasks inside a chat](https://learn.chatgpt.com/docs/automations#schedule-a-task-inside-a-chat),

291pull-request context, richer file previews, and [Memories](https://learn.chatgpt.com/docs/customization/memories) for295pull-request context, richer file previews, and [Memories](https://learn.chatgpt.com/docs/customization/memories) for

292work that spans tasks.296work that spans chats.

293 297 

294[Read the April 16 Codex app release notes](https://learn.chatgpt.com/docs/changelog#codex-2026-04-16-app).298[Read the April 16 Codex app release notes](https://learn.chatgpt.com/docs/changelog#codex-2026-04-16-app).

295 299 


313[Plugins](https://learn.chatgpt.com/docs/plugins) launched as installable bundles of skills,317[Plugins](https://learn.chatgpt.com/docs/plugins) launched as installable bundles of skills,

314connectors, and MCP servers. They made complete workflows easier to discover,318connectors, and MCP servers. They made complete workflows easier to discover,

315install, and share, while redesigned plugin and skill pages made their contents319install, and share, while redesigned plugin and skill pages made their contents

316and status clearer. Search for past tasks also arrived that week.320and status clearer. Search for past chats also arrived that week.

317 321 

318Read the [task search](https://learn.chatgpt.com/docs/changelog#codex-2026-03-24-app),322Read the [task search](https://learn.chatgpt.com/docs/changelog#codex-2026-03-24-app),

319[plugins launch](https://learn.chatgpt.com/docs/changelog#codex-2026-03-25), and323[plugins launch](https://learn.chatgpt.com/docs/changelog#codex-2026-03-25), and


323 327 

324### Branch earlier and choose tools from the composer328### Branch earlier and choose tools from the composer

325 329 

326You could fork a task from an earlier message, making it easier to try a new330You could fork a chat from an earlier message, making it easier to try a new

327approach without losing the original path. Model and reasoning commands became331approach without losing the original path. Model and reasoning commands became

328available while drafting, enabled skills appeared in the `@` menu, and GPT-5.4332available while drafting, enabled skills appeared in the `@` menu, and GPT-5.4

329mini added a faster option for lighter tasks and subagents.333mini added a faster option for lighter tasks and subagents.

330 334 

331Read the [GPT-5.4 mini](https://learn.chatgpt.com/docs/changelog#codex-2026-03-17),335Read the [GPT-5.4 mini](https://learn.chatgpt.com/docs/changelog#codex-2026-03-17),

332[conversation control](https://learn.chatgpt.com/docs/changelog#codex-2026-03-18-app), and336[chat control](https://learn.chatgpt.com/docs/changelog#codex-2026-03-18-app), and

333[skill menu](https://learn.chatgpt.com/docs/changelog#codex-2026-03-19-app) release notes.337[skill menu](https://learn.chatgpt.com/docs/changelog#codex-2026-03-19-app) release notes.

334 338 

335## March 9–13, 2026339## March 9–13, 2026


352### Let Codex inspect terminal output356### Let Codex inspect terminal output

353 357 

354Codex also learned to read the [integrated terminal](https://learn.chatgpt.com/docs/integrated-terminal#run-and-validate-your-project)358Codex also learned to read the [integrated terminal](https://learn.chatgpt.com/docs/integrated-terminal#run-and-validate-your-project)

355for the current task. It could inspect a running development server or build359for the current chat. It could inspect a running development server or build

356output directly instead of asking you to paste it.360output directly instead of asking you to paste it.

357 361 

358<PromptComponent362<PromptComponent


378 variant="no-wallpaper"382 variant="no-wallpaper"

379/>383/>

380 384 

381<a id="move-chats-between-local-and-worktree"></a>385<a id="move-tasks-between-local-and-worktree"></a>

382 386 

383### Move tasks between Local and Worktree387### Move chats between Local and Worktree

384 388 

385[Local and Worktree handoff](https://learn.chatgpt.com/docs/environments/git-worktrees#working-between-local-and-worktree)389[Local and Worktree handoff](https://learn.chatgpt.com/docs/environments/git-worktrees#working-between-local-and-worktree)

386made it possible to move an active task while preserving its context. GPT-5.4390made it possible to move an active chat while preserving its context. GPT-5.4

387also arrived in Codex that week for coding, computer use, and longer-context391also arrived in Codex that week for coding, computer use, and longer-context

388workflows.392workflows.

389 393 


396### Iterate in real time and branch an approach400### Iterate in real time and branch an approach

397 401 

398GPT-5.3-Codex-Spark entered research preview as a near-instant model for402GPT-5.3-Codex-Spark entered research preview as a near-instant model for

399real-time coding iteration. The app also added conversation forking and a403real-time coding iteration. The app also added chat forking and a

400floating, always-on-top task window, so you could explore another approach or404floating, always-on-top chat window, so you could explore another approach or

401keep Codex beside an editor or browser.405keep Codex beside an editor or browser.

402 406 

403Read the [Spark](https://learn.chatgpt.com/docs/changelog#codex-2026-02-12) and407Read the [Spark](https://learn.chatgpt.com/docs/changelog#codex-2026-02-12) and

windows.md +3 −3

Details

3Use Codex on Windows with the native [ChatGPT desktop app](https://learn.chatgpt.com/docs/windows/windows-app), the3Use Codex on Windows with the native [ChatGPT desktop app](https://learn.chatgpt.com/docs/windows/windows-app), the

4[CLI](https://learn.chatgpt.com/docs/codex/cli), or the [IDE extension](https://learn.chatgpt.com/docs/codex/ide).4[CLI](https://learn.chatgpt.com/docs/codex/cli), or the [IDE extension](https://learn.chatgpt.com/docs/codex/ide).

5 5 

6The ChatGPT desktop app on Windows supports core workflows such as parallel tasks,6The ChatGPT desktop app on Windows supports core workflows such as parallel chats,

7worktrees, scheduled tasks, Git functionality, the built-in browser, file previews,7worktrees, scheduled tasks, Git functionality, the built-in browser, file previews,

8plugins, and skills.8plugins, and skills.

9 9 


23 <CodexCallout23 <CodexCallout

24 href="/codex/windows/windows-app"24 href="/codex/windows/windows-app"

25 title="Use the ChatGPT desktop app on Windows"25 title="Use the ChatGPT desktop app on Windows"

26 description="Work across projects, run parallel tasks, and review results in one place with the native Windows app."26 description="Work across projects, run parallel chats, and review results in one place with the native Windows app."

27 iconSrc="/images/codex/codex-banner-icon.webp"27 iconSrc="/images/codex/codex-banner-icon.webp"

28 />28 />

29</div>29</div>


207 207 

208Sandboxed commands cannot reach the network208Sandboxed commands cannot reach the network

209 209 

210Some Codex tasks are intentionally run without outbound network access,210Some Codex chats are intentionally run without outbound network access,

211depending on the permissions mode in use.211depending on the permissions mode in use.

212 212 

213If a task fails because it cannot reach the network:213If a task fails because it cannot reach the network:

Details

1# ChatGPT desktop app for Windows1# ChatGPT desktop app for Windows

2 2 

3The [ChatGPT desktop app for Windows](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi) gives you one interface for3The [ChatGPT desktop app for Windows](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi) gives you one interface for

4working across projects, running parallel tasks, and reviewing results.4working across projects, running parallel chats, and reviewing results.

5The Windows app supports core workflows such as worktrees, scheduled tasks, Git5The Windows app supports core workflows such as worktrees, scheduled tasks, Git

6functionality, the built-in browser, file previews, plugins, and skills.6functionality, the built-in browser, file previews, plugins, and skills.

7It runs natively on Windows using PowerShell and the7It runs natively on Windows using PowerShell and the


9run in [Windows Subsystem for Linux 2 (WSL2)](#windows-subsystem-for-linux-wsl).9run in [Windows Subsystem for Linux 2 (WSL2)](#windows-subsystem-for-linux-wsl).

10 10 

11<CodexScreenshot11<CodexScreenshot

12 alt="ChatGPT desktop app for Windows showing a project sidebar, active task, and review pane"12 alt="ChatGPT desktop app for Windows showing a project sidebar, active chat, and review pane"

13 lightSrc="/images/codex/windows/codex-windows-light.webp"13 lightSrc="/images/codex/windows/codex-windows-light.webp"

14 darkSrc="/images/codex/windows/codex-windows-dark.webp"14 darkSrc="/images/codex/windows/codex-windows-dark.webp"

15 variant="no-wallpaper"15 variant="no-wallpaper"


84- WSL84- WSL

85 85 

86This change applies only to new terminal sessions. If you already have an86This change applies only to new terminal sessions. If you already have an

87integrated terminal open, restart the app or start a new task before87integrated terminal open, restart the app or start a new chat before

88expecting the new default terminal to appear.88expecting the new default terminal to appear.

89 89 

90</div>90</div>

Details

3Use Codex on Windows with the native [ChatGPT desktop app](https://learn.chatgpt.com/docs/windows/windows-app), the3Use Codex on Windows with the native [ChatGPT desktop app](https://learn.chatgpt.com/docs/windows/windows-app), the

4[CLI](https://learn.chatgpt.com/docs/codex/cli), or the [IDE extension](https://learn.chatgpt.com/docs/codex/ide).4[CLI](https://learn.chatgpt.com/docs/codex/cli), or the [IDE extension](https://learn.chatgpt.com/docs/codex/ide).

5 5 

6The ChatGPT desktop app on Windows supports core workflows such as parallel tasks,6The ChatGPT desktop app on Windows supports core workflows such as parallel chats,

7worktrees, scheduled tasks, Git functionality, the built-in browser, file previews,7worktrees, scheduled tasks, Git functionality, the built-in browser, file previews,

8plugins, and skills.8plugins, and skills.

9 9 


23 <CodexCallout23 <CodexCallout

24 href="/codex/windows/windows-app"24 href="/codex/windows/windows-app"

25 title="Use the ChatGPT desktop app on Windows"25 title="Use the ChatGPT desktop app on Windows"

26 description="Work across projects, run parallel tasks, and review results in one place with the native Windows app."26 description="Work across projects, run parallel chats, and review results in one place with the native Windows app."

27 iconSrc="/images/codex/codex-banner-icon.webp"27 iconSrc="/images/codex/codex-banner-icon.webp"

28 />28 />

29</div>29</div>


207 207 

208Sandboxed commands cannot reach the network208Sandboxed commands cannot reach the network

209 209 

210Some Codex tasks are intentionally run without outbound network access,210Some Codex chats are intentionally run without outbound network access,

211depending on the permissions mode in use.211depending on the permissions mode in use.

212 212 

213If a task fails because it cannot reach the network:213If a task fails because it cannot reach the network:

workflows.md +19 −15

Details

49 relying on the image alone.49 relying on the image alone.

50- Ask ChatGPT to use [web search](https://learn.chatgpt.com/docs/web-search) when the answer depends on50- Ask ChatGPT to use [web search](https://learn.chatgpt.com/docs/web-search) when the answer depends on

51 current information, and ask for sources when you need to check the result.51 current information, and ask for sources when you need to check the result.

52- Use a [project](https://learn.chatgpt.com/docs/projects) when related chats or tasks should share files,52- Use a [project](https://learn.chatgpt.com/docs/projects) when related chats should share files,

53 sources, or a local folder.53 sources, or a local folder.

54 54 

55### Use connected sources55### Use connected sources


81 81 

82### Personalize ChatGPT82### Personalize ChatGPT

83 83 

84Put preferences that should apply across chats and tasks in **Settings > Personalization**84Put preferences that should apply across chats in **Settings > Personalization**

85as custom instructions. Keep details that matter only to the current task in the85as custom instructions. Keep details that matter only to the current chat in the

86prompt.86prompt.

87 87 

88[<IconItem title="Review personalization settings" className="mt-4">88[<IconItem title="Review personalization settings" className="mt-4">


229ingredients across meals, and finish with one consolidated shopping list.229ingredients across meals, and finish with one consolidated shopping list.

230```230```

231 231 

232## Prompting for Work232<a id="prompting-for-work"></a>

233 233 

234Use Chat for quick questions, short rewrites, brainstorming, and lightweight234## Prompting in Work mode

235drafts. Use Work for tasks that draw on different sources or tools, involve a235 

236Use Chat mode for quick questions, short rewrites, brainstorming, and lightweight

237drafts. Use Work mode for tasks that draw on different sources or tools, involve a

236sequence of steps, make changes, or produce a larger deliverable.238sequence of steps, make changes, or produce a larger deliverable.

237 239 

238For Work tasks, describe the result you need, provide the source material, name240In Work mode, describe the result you need, provide the source material, name

239the audience, and explain how you'll review the work. Ask ChatGPT to plan,241the audience, and explain how you'll review the work. Ask ChatGPT to plan,

240gather the needed information, create files, and check them before it finishes.242gather the needed information, create files, and check them before it finishes.

241 243 

242### Use Work efficiently244<a id="use-work-efficiently"></a>

245 

246### Use Work mode efficiently

243 247 

244Work is useful for time-consuming or recurring tasks, or for finished files you248Work mode is useful for time-consuming or recurring tasks, or for finished files you

245can reuse. A task that uses more credits can still be worthwhile if it saves249can reuse. A task that uses more credits can still be worthwhile if it saves

246time, improves quality, or helps you make an important decision.250time, improves quality, or helps you make an important decision.

247 251 


285for launch day. Flag any missing decisions before producing the final files.289for launch day. Flag any missing decisions before producing the final files.

286```290```

287 291 

288For recurring work, first refine the prompt in a normal task. After the output is292For recurring work, first refine the prompt in a normal chat. After the output is

289reliable, [schedule work from that task](https://learn.chatgpt.com/docs/automations#schedule-work-from-a-task).293reliable, [schedule a task inside that chat](https://learn.chatgpt.com/docs/automations#schedule-a-task-inside-a-chat).

290Create a standalone scheduled task instead when each scheduled run should start294Create a standalone scheduled task instead when each scheduled run should start

291a new task.295a new chat.

292 296 

293<a id="use-editor-context"></a>297<a id="use-editor-context"></a>

294 298 


528 532 

529<WorkflowSteps>533<WorkflowSteps>

530 534 

5311. Attach the image in the Codex task (drag-and-drop or paste).5351. Attach the image in the Codex chat (drag-and-drop or paste).

5322. Prompt Codex:5362. Prompt Codex:

533 537 

534 ```text538 ```text


592 596 

593### Delegate refactor to the cloud597### Delegate refactor to the cloud

594 598 

595Use this when you want to design an approach with local context, then delegate the long implementation to a cloud task that can run in parallel.599Use this when you want to design an approach with local context, then delegate the long implementation to a cloud chat that can run in parallel.

596 600 

597#### Local planning (IDE)601#### Local planning (IDE)

598 602 


635 639 

6361. If you haven't already done so, set up a [Codex cloud environment](https://learn.chatgpt.com/docs/environments/cloud-environment).6401. If you haven't already done so, set up a [Codex cloud environment](https://learn.chatgpt.com/docs/environments/cloud-environment).

6372. Click on the cloud icon beneath the prompt composer and select your cloud environment.6412. Click on the cloud icon beneath the prompt composer and select your cloud environment.

6383. When you enter the next prompt, Codex creates a new task in the cloud that carries over the existing task context (including the plan and any local source changes).6423. When you enter the next prompt, Codex creates a new chat in the cloud that carries over the existing chat context (including the plan and any local source changes).

639 643 

640 ```text644 ```text

641 Implement Milestone 1 from the plan.645 Implement Milestone 1 from the plan.