prompting.md Codex Docs, 2026-02-19 20:37 UTC → 2026-04-22 00:42 UTC

1# Prompting1# Prompting

2 2 

3Interacting with the Codex agent

4 

5## Prompts3## Prompts

6 4 

7You interact with Codex by sending prompts (user messages) that describe what you want it to do.5You interact with Codex by sending prompts (user messages) that describe what you want it to do.

16Add a new command-line option `--json` that outputs JSON.14Add a new command-line option `--json` that outputs JSON.

17```15```

18 16 

19When you submit a prompt, Codex works in a loop: it calls the model and then performs any actions (file reads, file edits, tool calls, and so on) indicated by the model output. This process ends when the task is complete or you cancel it.17When you submit a prompt, Codex works in a loop: it calls the model and then performs the actions indicated by the model output, such as file reads, file edits, and tool calls. This process ends when the task is complete or you cancel it.

20 18 

21As with ChatGPT, Codex is only as effective as the instructions you give it. Here are some tips we find helpful when prompting Codex:19As with ChatGPT, Codex is only as effective as the instructions you give it. Here are some tips we find helpful when prompting Codex:

22 20 

33 31 

34Threads can run either locally or in the cloud:32Threads can run either locally or in the cloud:

35 33 

36- **Local threads** run on your machine. Codex can read and edit your files and run commands, so you can see what changes and use your existing tools. To reduce the risk of unwanted changes outside your workspace, local threads run in a [sandbox](https://developers.openai.com/codex/security).34- **Local threads** run on your machine. Codex can read and edit your files and run commands, so you can see what changes and use your existing tools. To reduce the risk of unwanted changes outside your workspace, local threads run in a [sandbox](https://developers.openai.com/codex/agent-approvals-security).

37- **Cloud threads** run in an isolated [environment](https://developers.openai.com/codex/cloud/environments). Codex clones your repository and checks out the branch it's working on. Cloud threads are useful when you want to run work in parallel or delegate tasks from another device. To use cloud threads with your repo, push your code to GitHub first. You can also [delegate tasks from your local machine](https://developers.openai.com/codex/ide/cloud-tasks), which includes your current working state.35- **Cloud threads** run in an isolated [environment](https://developers.openai.com/codex/cloud/environments). Codex clones your repository and checks out the branch it's working on. Cloud threads are useful when you want to run work in parallel or delegate tasks from another device. To use cloud threads with your repo, push your code to GitHub first. You can also [delegate tasks from your local machine](https://developers.openai.com/codex/ide/cloud-tasks), which includes your current working state.

38 36 

37In the Codex app, you can also start a chat without choosing a project. Chats

38aren't tied to a saved repository or project folder. Use them for research,

39planning, connected-tool workflows, or other work where Codex shouldn't start

40from a codebase. Chats use a Codex-managed `threads` directory under your Codex

41home as their working location. By default, that location is `~/.codex/threads`.

42To change the base location for this state, set `CODEX_HOME`; see

43[Config and state locations](https://developers.openai.com/codex/config-advanced#config-and-state-locations).

44 

39## Context45## Context

40 46 

41When you submit a prompt, include context that Codex can use, such as references to relevant files and images. The Codex IDE extension automatically includes the list of open files and the selected text range as context.47When you submit a prompt, include context that Codex can use, such as references to relevant files and images. The Codex IDE extension automatically includes the list of open files and the selected text range as context.