Codex · Series · Part 1 of 8

Meet Codex and set it up: the interfaces, the first session, and choosing a model

Every time I start work on a project with an AI assistant, I catch myself explaining the same things again: how to build it, which folders matter, which style we follow. This eight-part series is about ending that habit with one small file called AGENTS.md. Before the file makes sense, though, you need the basics, so Part 1 covers what Codex is, the official ways to use it, how to install and sign in, how much freedom to give it, and how to pick a model.

Words you will see

1. What is Codex?

Codex is OpenAI’s coding agent. You describe a goal in plain language, and Codex reads your project, edits files and runs commands to get there, within limits you set. The documentation’s glossary describes the agent as the part that “reasons over context, uses tools, and completes a task”. Underneath is a large language model, the same kind of “very fancy autocomplete” I described in my Android AI chat post: it reads your input as tokens and writes a reply one token at a time.

Two names get mixed up, so let me separate them:

Codex also lives inside the ChatGPT desktop app. In the docs’ quickstart, you pick Codex from the ChatGPT dropdown when you want software development with codebase context and developer tools, and you pick ChatGPT for other work. This series is mostly about the coding side.

2. The official ways to use it

Codex is not tied to one window. OpenAI ships it in several places. The CLI and the IDE extension share the same configuration layers, so a habit you learn in one carries over to the other.

The docs also describe a non-interactive mode, codex exec, for scripts and CI. We meet it in Part 7.

What the maturity labels mean

Some features carry a maturity label. You will see these words in the docs, and in this series:

For example, as of 18 October 2026 the command reference marks codex, codex exec and codex resume as stable, and codex cloud as experimental. The Linux desktop app is described as a preview, and permission profiles as beta.

3. Installing Codex

Before you install

• A way to sign in: a ChatGPT account, or an OpenAI API key. Plans differ in what they include. As of 18 October 2026 the pricing page lists Codex on the web, in the CLI, in the IDE extension and on iOS under Plus, and lists the desktop app with GPT-6 Luna under Free and Go, subject to rollout. See the pricing page for current plans and limits.
• A project folder to work in, ideally one under git.
• Optional: git itself. The Windows app docs call Git the tool that powers the review panel and lets you inspect or revert changes.

Pick the install command for your system

You can also run codex update, which the command reference says checks for and applies an update when your installed release supports self-update.

Windows: native, WSL or the desktop app

On Windows you have three official routes:

• Native CLI: the PowerShell command above. The Windows desktop app runs natively using PowerShell and the Windows sandbox.
• WSL2 (Windows Subsystem for Linux): choose it when you need Linux-native tooling or your repositories already live in WSL2. In an elevated PowerShell or Windows Terminal run wsl --install (Ubuntu is a common choice), then wsl to open a Linux shell, and install Codex inside it with the macOS/Linux command. WSL1 is not supported: the docs say it worked through Codex 0.114, and from 0.115 the Linux sandbox uses bubblewrap.
• The ChatGPT desktop app: download it from the download page, or run winget install --id 9PLM9XGG6VKS -s msstore. By default its agent runs in PowerShell; in Settings you can switch the agent to WSL and restart the app.

# Inside an elevated PowerShell (WSL route)
wsl --install
wsl

# Then, inside the WSL shell
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

The docs also advise keeping repositories under your Linux home folder (for example ~/code/my-app) rather than under /mnt/c, because Windows-mounted paths can be slower and cause more symlink and permission issues.

Linux: CLI and desktop app

On Linux the CLI uses the same installer as macOS. Codex’s sandbox on Linux and WSL2 relies on bubblewrap, which the docs ask you to install first:

# Debian / Ubuntu
sudo apt install bubblewrap

# Fedora
sudo dnf install bubblewrap

The ChatGPT desktop app for Linux is a preview. The docs list Ubuntu 24.04 LTS and 26.04 LTS, Debian 13, Fedora 43 and 44, and current Arch Linux, each for x64 and ARM64. Packages are a .deb (Ubuntu, Debian), an .rpm (Fedora) or an install script (Arch); follow the Linux desktop app guide for the exact download and install steps.

Check that it worked

Open a new terminal window and run:

codex --version

It prints a version number. For a fuller health check, run codex doctor. The docs say it generates a diagnostic report covering installation, configuration, authentication, runtime, Git, terminal, app-server and chat inventory. Add --summary for just the grouped check rows and the final count.

If you see “command not found” or “not recognized”

This is the most common first-day problem with any command-line tool. It usually means your terminal cannot find the codex program. The part of the docs that covers it is brief, so here is what they support, in order:

1. Open a new terminal window. The docs’ Windows troubleshooting table gives this as the first fix when codex is not recognized after installation, because an already-open window does not see the updated PATH (the list of folders your terminal searches for commands).
2. Check whether the command exists at all. The WSL page uses this on Linux-style shells:

   which codex || echo "codex not found"

   On Windows PowerShell, Get-Command codex shows where it is found, and the docs suggest it for spotting competing standalone and npm copies when the wrong version starts.
3. Check the PATH of the right account. The docs warn that an install done under a different account (for example a system account in a managed setup) does not install into your own profile.
4. In WSL, install it inside WSL. The WSL page’s own fix for “cannot find codex” is to verify the binary exists and is on PATH inside WSL. If it is missing, run the macOS/Linux installer in the WSL shell and repeat the which check above.

The docs do not print a specific folder to add to PATH, so I will not guess one. If the steps above do not fix it, re-run the installer, or install with Homebrew or npm instead, then open a new terminal. Still stuck? codex doctor is built for this, and the issue tracker is where the docs send bug reports.

4. Signing in: ChatGPT account or API key

According to the authentication page, Codex supports two ways to sign in when using OpenAI models. The desktop app, CLI and IDE extension support both. Codex cloud needs ChatGPT.

Get an API key from the OpenAI dashboard. The docs pipe the key in through stdin so it does not end up in your shell history as a typed argument. Compare which features each method supports on the feature availability table.

Start it and sign in

1. Go to your project. Codex works relative to the folder you start it in, so this matters.

   cd ~/projects/my-app

2. Start it.

   codex

3. Sign in. The first run asks you to choose Sign in with ChatGPT or another available method. For ChatGPT sign-in a browser window opens, and after you sign in the browser returns your credentials to Codex.

Good to know about sign-in

• Check or end it. codex login status prints the active sign-in method. codex logout (or /logout inside a chat) clears the stored credentials. Use it on a shared machine.
• Login is cached. Codex stores it locally, in a plaintext file at ~/.codex/auth.json or in your operating system’s credential store. The CLI and IDE extension share the cache. Treat auth.json like a password: do not commit it, paste it into tickets, or share it in chat. The cli_auth_credentials_store setting (file, keyring, auto or ephemeral) chooses where it goes.
• No browser on the machine? On a remote or headless computer, the docs prefer device code login, which they label beta: run codex login --device-auth, open the link on another device and enter the one-time code. It must be enabled in your ChatGPT security settings or workspace permissions first.
• Your sign-in method decides the rules. The docs say it determines which admin controls and data-handling policies apply: ChatGPT workspace settings for ChatGPT sign-in, your API organisation’s settings for an API key.

5. Your first session

Once you run codex in a project folder, you get a prompt. You type in plain language. A good first message is not “write me a feature”, it is a question that lets Codex look around. The CLI page’s own first example is exactly that:

Tell me about this project

If you want a safe place to practise, make a throwaway project first. This is the checklist I would follow on day one:

1. Create a playground in git.

   mkdir ~/codex-playground && cd ~/codex-playground
   git init
   printf '# Playground\n' > README.md
   git add . && git commit -m "start"
   git switch -c try-codex

2. Start Codex with codex and, if asked, decide whether to trust the folder. If you are unsure, do not trust it yet: the docs say Codex may start in read-only until you explicitly trust the working directory.
3. Ask a question. “Tell me about this project.” Nothing should change yet.
4. Check where you stand. Type /status. The docs say it shows the active model, approval policy, writable roots and remaining context.
5. Ask for one tiny change. “Add a one-line description under the title in README.md.” Read any approval request before you answer it.
6. Inspect the result. Type /diff to see the git diff, including files git is not tracking yet.
7. Keep or discard. Happy? git commit -am "try codex". Not happy? git restore README.md, or just delete the playground.
8. Leave and come back. Quit with /exit, then run codex resume (see below) to reopen a recent chat.

> Tell me about this project

● I'll look at the project files first.
  read README.md
  read app/build.gradle.kts
  search "MainActivity"

● This is an Android app that shows a list of notes.
  • UI is in app/src/main/java/.../ui/ (Jetpack Compose)
  • Data is stored with Room in .../data/
  • Run it with ./gradlew installDebug

> _

Notice what happened. You did not paste any code. Codex chose which files to read. When it wants to do something outside its sandbox boundary, such as edit a file outside the workspace or use the network, it stops and asks you first. Section 7 explains exactly when.

Two prompt habits from the official best practices guide pay off immediately. First, a good default prompt has four parts: the goal, the context (use @ to search for a file and add its path), any constraints, and a done when condition such as “tests pass”. Second, for anything hard or vague, ask Codex to plan before it codes (the /plan command in section 6).

How to stop, interrupt and quit

One honest gap: the pages I checked do not name a default key that interrupts just the current turn. They do show that the interrupt key is configurable (interrupt_turn under [tui.keymap.chat] in config.toml, with f12 as the example), and that /keymap lets you inspect and change shortcut bindings. Open /keymap to see what your version uses.

Stay safe on day one

6. Slash commands worth knowing

Typing / in the prompt opens a menu of commands that control the chat itself rather than talk to the model. Type a few letters to filter the list. If a chat is already running, you can type a slash command and press Tab to queue it for the next turn. These are the ones I use most. The full list is in the official CLI reference:

Beyond these, the reference lists commands for /fork, /side, /goal, /mcp, /skills, /hooks and more. We meet most of them in Parts 5 to 7. Some commands appear only when available: for example /fast shows up only if the current model offers a Fast tier.

7. Approvals, sandbox and permission modes

Earlier you saw that Codex can stop and ask. The docs explain this as two separate controls that work together:

The three sandbox modes

Even in workspace-write, some paths stay read-only inside the workspace: .git, and .agents, .codex and .aws when they exist as directories.

The approval policy

The two values you can pass to --ask-for-approval (-a) are on-request, where Codex runs what the sandbox allows and asks when it needs to go beyond it, and never, which turns approval prompts off. The docs stress that never still works within whatever sandbox you chose, so you keep control of how much autonomy there is. They also mention a granular form for keeping some prompt categories interactive and rejecting others, and say the older untrusted value has been retired and can stop the client from starting if it is still in your config.

The combinations you will actually use

The docs call the default preset Auto. In the CLI you pick between the presets with /permissions. In the desktop app and IDE extension the permissions control sits below the composer, where the docs call the starting mode Ask for approval.

The --approve-for-me row comes from the command reference; the same behaviour is also written in the docs as -c approvals_reviewer=auto_review. The reviewer only looks at actions that already need approval, uses extra model calls, and can make mistakes, so the docs say it does not replace isolation or your own oversight. While you are learning, keep approvals on you.

What Codex does on first launch

The docs say Codex detects whether your folder is version-controlled and recommends Auto for version-controlled folders and read-only for folders that are not. That is one more reason to put your practice project in git. To accept the defaults, simply run codex. To set them explicitly:

codex --sandbox workspace-write --ask-for-approval on-request
codex --sandbox read-only --ask-for-approval on-request

> /permissions

 Select approval preset
 ✓ Auto        edit and run in the workspace, ask beyond it
   Read Only   read and answer, review edits first
   (more choices may appear for your setup)

Plan mode: think first

Separately from permissions, /plan switches the chat into plan mode: Codex proposes an execution plan before implementation starts. You can add a prompt inline, for example /plan Propose a migration plan for this service. It is unavailable while Codex is already working. Why it matters: a plan is cheap to correct, and code is not. Catching a wrong assumption in step 2 of a plan costs you one sentence. Catching it after twenty edited files costs a lot of tokens and time. I use it for anything touching several files, new features, and any code I do not know well.

8. Changing the model and reasoning effort

Codex can run on different models. A larger model reasons better about hard problems but is slower and uses more of your allowance. A smaller one is quick and fine for simple, repeatable tasks. Matching the model to the job is one of the easiest ways to work faster and spend less. The docs’ model page says to start with the default reasoning effort and raise it when the task needs deeper planning or analysis.

How to choose

# 1. Inside a chat: pick a model and reasoning effort from the popup
/model

# 2. When you start Codex (this launch only)
codex --model gpt-6.1-sol
codex -m gpt-6-luna

# 3. Saved in config.toml (see section 9)
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"

# 4. Any single setting for one launch
codex -c model_reasoning_effort=high

> /model

 Choose a model
 ✓ gpt-6.1-sol
   gpt-6-luna
   (only models available to your account appear)

Command-line flags beat saved settings for that launch. In the picker, the CLI can show more reasoning options if you select More reasoning… after choosing a model.

Which models, as of 18 October 2026

Per the models page, the docs recommend GPT-6.1 Sol (gpt-6.1-sol) when it is available to your account and client for complex coding and agentic work, and GPT-6 Luna (gpt-6-luna) for focused, repeatable tasks. Astra is described as the choice when a task needs the strongest capability across steps and tools. Availability depends on rollout, your sign-in method, your client and, for Enterprise and Edu, whether an administrator enabled a model. If a model is not listed in your picker, pick another.

Reasoning effort

Effort levels have friendly names in the apps and plain names in config. The docs say Light in the desktop app, ChatGPT Work on the web and the IDE extension is called Low in the CLI. In config.toml, model_reasoning_effort takes values such as low, medium, high, xhigh, max or ultra, but only the levels your model and client actually support. Guidance from the docs:

• Low for quick, well-scoped tasks.
• Medium for tasks that need more planning.
• High and Extra High for difficult work with multiple steps, sources or trade-offs.
• Max gives the model more time on a single hard task; Ultra uses subagents to work on parts of a task in parallel. The docs say most tasks need neither, and that Luna supports up to Max but not Ultra.

Higher effort takes longer and uses more tokens, so raise it on purpose. Reasoning efforts also do not map exactly between model generations, so the docs suggest trying a familiar task at a lower setting and adjusting.

One more control: /fast toggles a Fast service tier on or off and saves your choice, but only when the current model offers one.

9. config.toml and where it lives

Beyond the model, you can save preferences in a config.toml file (TOML is a simple key = "value" text format). Per the config basics page, your personal defaults live in ~/.codex/config.toml, and you can scope settings to a project with a .codex/config.toml file in the repo. Codex loads project .codex/ layers only when you trust the project. The CLI and the IDE extension share the same layers. In the extension, click the gear icon, then Codex Settings > Open config.toml. The Codex home folder is $CODEX_HOME, which defaults to ~/.codex; the app on Windows uses %USERPROFILE%\.codex.

When settings disagree, Codex resolves them in this order, highest first:

model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

That small file says: use GPT-6.1 Sol at medium effort by default, ask for approval when going beyond the sandbox, let commands write inside the workspace, and use cached web search results. Every key above is one the docs list as commonly changed. Here is what the less obvious ones mean:

Do not mix the old and new styles: the docs say permission profiles (default_permissions, beta) do not compose with the older sandbox_mode settings, so use one or the other. If something does not apply, run /debug-config to see which layer won. For every available key, see the configuration reference.

Notice that config.toml configures behaviour. It does not tell Codex anything about your project. For that, we need a different kind of file.

10. What comes next

You can now install Codex, sign in, talk to it, control what it may do, and switch models. But start a new chat and Codex has forgotten what you taught it. That is not a bug; it is how language models work. In Part 2 we fix it with AGENTS.md. Part 3 shows how that saves tokens and speeds up onboarding, and Part 4 covers the Codex models, the API and the official links.