My cleaning script is a tangled monolith
The script becomes maintainable and reusable; a colleague adapts the ingest module for a new instrument within an hour.
Track 13 · Advanced
13.2.1
Codex
OpenAI's terminal coding agent — reads, edits, runs your repo
1Overview
OpenAI's agentic coding tool, purpose-built for code rather than general chat or web browsing. It runs directly against files already on your machine, not a remote sandbox.
Codex is OpenAI's agentic coding tool — a terminal agent (plus a VS Code extension and managed cloud tasks) that reads your repository, edits files, runs commands, and iterates on test failures until they pass. The CLI is open source (Rust) and runs locally in your own checkout, so your code stays on your machine. → Coding-focused: OpenAI models only, no bring-your-own-model.
1.1Before you start
1.2After this chapter you can
→Read and edit a repo end to end — refactor, add a feature, fix a failing test
→Run it from the terminal, a VS Code extension, or a fully managed cloud task
→Know its limit: OpenAI models only, needs a paid ChatGPT plan or API credits
1.3Best for
Refactoring a messy analysis script or debugging a failing test end-to-end — purpose-built for code over general chat or web browsing.
1.4Watch out
Needs a paid ChatGPT plan or API credits to run at all — there's no free tier to try it on first.
1.5Free vs paid
Included with ChatGPT Plus ($20/mo) and Pro plans, or pay per token via the API. The CLI is free and open source; you pay for model usage.
2Lessons 5
2.1 Clone a sample repo and list its files
A local copy of a GitHub repository that you will use as the workspace for Codex.
You will have a checkout on your machine that Codex can read and edit.
- Open a terminal window.
- Run
git clone https://github.com/openai/codex-demo.git(replace with any public repo you prefer). - Change directory into the cloned folder with
cd codex-demo. - Run
ls -Rto display the full file tree. - Confirm that the repository contains source files and a test suite.
- You'll see A printed recursive list of all files in the repository, confirming the checkout succeeded.
- Takeaway Having a local repo gives Codex direct access to code and tests for automated editing.
2.2 Run Codex CLI to scan the repository
The Codex command‑line interface that reads a project’s files and builds an internal model of its code.
You will invoke Codex so it knows about the current repo structure and can later suggest edits.
- In the same terminal, ensure you are inside the cloned repository directory.
- Execute
codex initto initialize a Codex session for this project. - Wait for the command to finish; it will output a summary of files it has indexed.
- Run
codex statusto view the current state reported by Codex. - Note any messages indicating that Codex successfully loaded the repository.
- You'll see A confirmation message listing the number of files indexed and a status line showing “ready”.
- Takeaway Initializing Codex creates a live representation of your codebase that powers later automated actions.
2.3 Ask Codex to generate a missing function
An interactive request to the Codex agent to create code that satisfies a described need.
You will have a new function added to the source tree, written by Codex.
- Identify a file that lacks a needed helper (e.g.,
utils.py). - Run
codex edit utils.pyand when prompted, type: “Create a function calledparse_inputthat takes a string and returns a dictionary of key/value pairs.” - Confirm the request by pressing Enter.
- Allow Codex to modify the file; it will print the diff it applied.
- Open
utils.pywithcat utils.pyto verify the newparse_inputfunction appears.
- You'll see A displayed diff showing the added function and the updated file content containing
def parse_input(...):. - Takeaway Codex can write code on demand, turning natural language specifications into concrete implementations.
2.4 Run the test suite through Codex
A command that tells Codex to execute the project’s tests and report failures.
You will see which tests pass or fail, giving Codex context for further fixes.
- From the repository root, run
codex test. - Observe the output; Codex will invoke the project's test runner (e.g., pytest) and capture results.
- Wait until the command finishes and displays a summary of passed/failed tests.
- If any tests fail, note the error messages shown.
- Record the number of failing tests for the next lesson.
- You'll see A test report listing each test case with PASS or FAIL status and a final count of failures.
- Takeaway Running tests through Codex lets the agent see concrete failure signals it can later address automatically.
2.5 Let Codex fix a failing test automatically
An iterative workflow where Codex diagnoses a test failure, edits code, and re‑runs the tests until they pass.
You will have a previously failing test now passing after Codex’s automated edit cycle.
- Ensure you are still in the repository directory with the failing test identified earlier.
- Run
codex fixto start an automatic repair session. - When prompted, provide the name of the failing test (e.g.,
test_parse_input). - Allow Codex to propose a patch; it will display the diff and ask for confirmation.
- Confirm the patch, then let Codex re‑run the tests automatically.
- Observe the final test report confirming that the previously failing test now passes.
- You'll see A displayed diff applied by Codex followed by a new test run showing all tests PASS.
- Takeaway Codex can close the loop from failure detection to code correction, streamlining debugging cycles.
3You’ll know it worked 30 checkable outcomes in this chapter
- ✓The ingest module can be imported and used by a colleague to process new instrument data within an hour
- ✓The report.md file contains the summarized repo risks after the CI job completes
- ✓The chat window shows the selected reasoning level next to the model name and response times vary accordingly
- ✓A new folder named Chess Game appears in the file system and is listed in Codex's project sidebar
- ✓The profile in Codex (or another IDE) points to the GLM 5.2 model
- ✓The archived session appears in an 'Archived' list and is no longer active
- ✓The UI indicates 'Plan mode' and no code is executed automatically
- ✓The avatar icon animates or shows a status message during implementation
30 outcomes in all — one per recipe below.
4FAQ, Tips & How-to 68
one problem, one solution, one action
Research & data tools3
Tests fail after a dependency upgrade
The upgrade unblocks in under an hour with a clear audit trail of why each fix was made.
Need to compute a clinical risk score from a paper
The calculator reproduces the paper's worked examples exactly and is ready to embed in the practice's internal tools, with the underlying formula and citation kept alongside the code so it stays auditable.
Internal tools & ops1
Need a repo risk summary in CI
The official Codex Action packages this exec mode for direct use inside GitHub Actions.
Need a code generation tool that runs on your computer
Learn how to install and launch Codex on your desktop for full feature access
Unsure if actions need confirmation
Control how Codex executes commands by setting the approval mode
Typing prompts is a hassle
Use voice input to send prompts to Codex instead of typing
Want balanced speed and answer quality
Balance speed and quality by choosing the appropriate reasoning level
Want to run desktop programs via a chat command
Enable Codex to open, write to, and launch desktop programs
Want to make Chrome open pages and click stuff automatically
Let Codex interact with the built-in browser to control Chrome tabs and pages
Need a new GitHub repository for your code
Create a GitHub repo directly from Codex and sync project files
Need a fresh project folder for a chess game
Organize work by creating a new project directory with a main branch
Want a multiplayer chess prototype
Trigger Codex to produce multiple files, set up WebSockets, and launch a server from a single prompt
Want to edit part of a web page by clicking it
Fine-grained UI editing by annotating HTML elements in the built-in browser
Want to start a local server without switching apps
Execute code directly from Codex's built-in terminal without leaving the app
Can’t get the new AI model to work
Set up GLM 5.2 via OpenRouter by copying its endpoint into your tool's provider settings and creating a profile
You must have a ChatGPT account to use OpenAI Codex
Upgrading to a paid ChatGPT plan prevents Codex from pausing after five-hour or weekly limits
Completed tasks still crowd your workspace
You can archive a session from the workspace once its tasks are finished
The Codex desktop application is available for Windows and macOS; Linux users must use the CLI
Need to run code and see results instantly
Enabling the built-in browser lets Codex run and test code within the same environment
Need to make a Word doc or call Canva
Installing plugins expands Codex's ability to generate documents or call external services
Want to pause automatic code changes
Using Shift+Tab switches Codex to a planning state where it only suggests changes
Need to build and test everything in a folder
The /goal command tells Codex to build and test all features in a folder automatically
Plan too big for the agent
Organizing a plan into separate feature files keeps the agent's context window low (≈13 %)
Need to keep design drafts safe from running
Saving mock-up or design ideas in a /plans folder prevents accidental execution
The pet avatar displays Codex's current activity, letting you monitor progress while working elsewhere
Learn how installing Codex from the Microsoft Store sets up a secure sandboxed environment
Run PowerShell commands from chat
See how Codex can execute PowerShell scripts directly on Windows
Outbound traffic is blocked until I approve it
Learn to toggle Codex's network access between auto-review, manual approval, and full
Need pre‑configured Kali or Ubuntu VMs for a hacking lab
Use Codex to automatically create Hyper-V virtual machines for hacking labs
Want a Python script from an English description
Codex parses the natural-language request, shows the file it will create, and waits for your approval before acting
Observing Codex's output — Fibonacci script execution
When you approve, Codex writes the script, runs it, and shows the computed sequence in your terminal
I don’t know what the code does
Starting with an open-ended request (e.g., "Tell me about this project") lets Codex gather context, improving later targeted edits
Need to keep AI from touching other files
A sandbox isolates Codex's file operations, protecting critical paths like .git
Rules defined in AGENTS.md files closer to your current folder take precedence over broader definitions
Having to repeat conventions for every task
Writing your conventions once in AGENTS.md lets Codex enforce them on every task without extra effort
Need quick, cheap edits for routine work
Use the mini model for light or time-sensitive edits to reduce cost and increase speed
Need to lock in a model before starting the CLI
Specify the desired Codex model when starting the CLI to avoid later switches
Providing the exact symptom or error message lets Codex locate the failure in the codebase
Want the assistant to know my open files and selections
Providing open files, selections, and @file references lets Codex work with full project context
My prompts take forever locally
Long-running prompts can be sent to a cloud environment, freeing your local IDE
AI thinks too shallow or too deep
Adjusting reasoning settings tailors how much thought Codex applies to a request
Need to run long or parallel jobs without watching them
You can off-load long or parallel jobs to Codex's cloud so they run without your supervision
Want cloud jobs to run from a GitHub issue
Tagging `@codex` on an issue or pull request automatically hands the job to Codex's cloud
Need to hook up an external tool
You can extend Codex with external tools by defining an MCP server in the configuration file
When you need only the final answer from a command
You can pipe the final message directly into other tools or files
Use `--json` to get a structured JSON stream suitable for automated processing
Want the answer saved without extra redirection
Specify an output path so Codex writes its final answer without needing extra redirection
Let AI change my files while blocking all other actions
Grant Codex write access to the current workspace while keeping other permissions restricted
Start with the Plus plan to cover regular study work without overpaying
Move to the Pro plan only after you hit Plus's rate-limit ceiling
Use the Business plan for on-demand scaling without a fixed monthly fee
Verbally labeling each loop stage reinforces the mental model and improves debugging of agent behavior
What actually is OpenAI Codex — is it just a chatbot for code?
Codex is OpenAI's agentic coding system, not a simple chatbot. It can autonomously read your codebase, run tests, edit files, execute shell commands, and propose pull requests. It works across four surfaces: a terminal CLI, a desktop app, an IDE extension (VS Code, Cursor, Devin Desktop — formerly Windsurf), and a cloud/web interface — all sharing one account.
What is the sandboxing and approval system — can Codex break my computer?
Codex runs inside an OS-enforced sandbox that restricts it to your current project directory by default and blocks network access during the agent phase. It must ask for your approval before touching files outside the workspace, accessing the internet, or running commands flagged as potentially unsafe. The default mode stops and asks at dangerous boundaries rather than acting freely.
How does the cloud version work — does Codex run tasks while I'm away?
Yes. The cloud version runs each task in its own isolated, OpenAI-managed container pre-loaded with your connected GitHub repository. You assign a task, close your laptop, and Codex works asynchronously. When done, it produces a pull request you can review, accept, or reject. You can also trigger tasks by tagging @codex on a GitHub issue.
How much does Codex cost, and what do the plans give you?
Codex is bundled into ChatGPT subscriptions: Free (limited), Plus ($20/month, a meaningful number of cloud tasks per rolling window), and Pro tiers ($100–$200/month, much higher limits). Usage typically resets on a rolling multi-hour cycle. If you exceed your limit you can buy additional credits. API-key-only usage is pay-as-you-go but loses some cloud GitHub features.
What are the system requirements — does it run on Windows?
The desktop app runs natively on macOS and Windows. The CLI runs on macOS, common Linux distributions, and Windows via WSL2 (Windows Subsystem for Linux). A few GB of RAM is recommended. Git is optional but useful for the built-in pull-request helpers.
Is this the same Codex as the old OpenAI Codex API from 2021?
No — they share a name but are different things. The original 2021 Codex was a text-to-code completion model (a fine-tuned GPT-3) accessed via API, which OpenAI retired in 2023. The current Codex (2025–2026) is a full agentic coding platform powered by modern models, with a CLI, desktop app, IDE extension, and cloud task runner.
Do I need a ChatGPT Plus or Pro subscription, or can I use the free plan?
Codex is available on ChatGPT plans, with much lower usage limits on the free tier. The $20/month Plus plan gives meaningful access; the higher Pro plan multiplies that. You can also use an OpenAI API key instead of a ChatGPT subscription, which bills at standard API rates.
Do I need an API key, or can I just sign in with my ChatGPT account?
You can sign in with your regular ChatGPT account — no API key needed, and that draws on your plan's included usage. API keys are an alternative for developers who want Codex in automated scripts or CI/CD pipelines; usage then bills at pay-per-use API rates, and some cloud features need a ChatGPT workspace login.
How do I install and start using Codex?
You have several options: download the desktop app; install the CLI via npm ('npm install -g @openai/codex') or Homebrew; install the VS Code / Cursor / Devin Desktop (formerly Windsurf) extension; or use the web version in your browser. After installing, sign in with your ChatGPT account or API key, point it at a project folder, and type your first request in plain English.
What's the difference between the CLI, desktop app, IDE extension, and the cloud version?
All share the same models and account. The CLI and desktop app run locally and are best for interactive sessions where you review each change. The IDE extension embeds Codex in VS Code or similar editors. The cloud/web version runs tasks asynchronously in isolated OpenAI-managed containers — you can delegate a task, close your laptop, and come back to a pull request.
Do I need to know how to code to use Codex?
No coding knowledge is required to start. Non-technical users are advised to begin with the desktop app or web interface, which feel less intimidating than the terminal. You can ask Codex in plain English to explain what a project does or propose a change. That said, the cloud workflow produces git diffs and pull requests, so a basic idea of what those are helps when reviewing output.
Is my code sent to OpenAI's servers? Will it be used to train future models?
When using Codex, your code is processed by OpenAI's servers — that is how the model reads and edits it. By default on consumer plans (Free, Plus), OpenAI may use your content for training; you can opt out in the privacy settings. Business, Enterprise, and Edu plans have training off by default. Codex also has separate settings for allowing or blocking training on full environments.
Isolated task containers — each runs your repo code in the cloud
Tasks run asynchronously in the cloud, even when you're away
▸How-to Everyone
Not sure which coding model to use
You can switch between the default and lighter or heavier models during a session or set a default in your config
The same set on /recipes, filtered by tool and role.
5Videos 2
The Ultimate Codex Tutorial: How To Use Codex For Beginners 2026
The freshest beginner walkthrough — start here to get Codex working on your own machine before going deeper.
Codex Full Course 2026: The NEW Best AI Coding Tool
Watch after the beginner video when you want the full picture of how Codex fits a real coding workflow, not just a first run.
6FAQ 12
What actually is OpenAI Codex — is it just a chatbot for code?
Codex is OpenAI's agentic coding system, not a simple chatbot. It can autonomously read your codebase, run tests, edit files, execute shell commands, and propose pull requests. It works across four surfaces: a terminal CLI, a desktop app, an IDE extension (VS Code, Cursor, Devin Desktop — formerly Windsurf), and a cloud/web interface — all sharing one account.
What is the sandboxing and approval system — can Codex break my computer?
Codex runs inside an OS-enforced sandbox that restricts it to your current project directory by default and blocks network access during the agent phase. It must ask for your approval before touching files outside the workspace, accessing the internet, or running commands flagged as potentially unsafe. The default mode stops and asks at dangerous boundaries rather than acting freely.
How does the cloud version work — does Codex run tasks while I'm away?
Yes. The cloud version runs each task in its own isolated, OpenAI-managed container pre-loaded with your connected GitHub repository. You assign a task, close your laptop, and Codex works asynchronously. When done, it produces a pull request you can review, accept, or reject. You can also trigger tasks by tagging @codex on a GitHub issue.
How much does Codex cost, and what do the plans give you?
Codex is bundled into ChatGPT subscriptions: Free (limited), Plus ($20/month, a meaningful number of cloud tasks per rolling window), and Pro tiers ($100–$200/month, much higher limits). Usage typically resets on a rolling multi-hour cycle. If you exceed your limit you can buy additional credits. API-key-only usage is pay-as-you-go but loses some cloud GitHub features.
What are the system requirements — does it run on Windows?
The desktop app runs natively on macOS and Windows. The CLI runs on macOS, common Linux distributions, and Windows via WSL2 (Windows Subsystem for Linux). A few GB of RAM is recommended. Git is optional but useful for the built-in pull-request helpers.
Is this the same Codex as the old OpenAI Codex API from 2021?
No — they share a name but are different things. The original 2021 Codex was a text-to-code completion model (a fine-tuned GPT-3) accessed via API, which OpenAI retired in 2023. The current Codex (2025–2026) is a full agentic coding platform powered by modern models, with a CLI, desktop app, IDE extension, and cloud task runner.
Do I need a ChatGPT Plus or Pro subscription, or can I use the free plan?
Codex is available on ChatGPT plans, with much lower usage limits on the free tier. The $20/month Plus plan gives meaningful access; the higher Pro plan multiplies that. You can also use an OpenAI API key instead of a ChatGPT subscription, which bills at standard API rates.
Do I need an API key, or can I just sign in with my ChatGPT account?
You can sign in with your regular ChatGPT account — no API key needed, and that draws on your plan's included usage. API keys are an alternative for developers who want Codex in automated scripts or CI/CD pipelines; usage then bills at pay-per-use API rates, and some cloud features need a ChatGPT workspace login.
How do I install and start using Codex?
You have several options: download the desktop app; install the CLI via npm ('npm install -g @openai/codex') or Homebrew; install the VS Code / Cursor / Devin Desktop (formerly Windsurf) extension; or use the web version in your browser. After installing, sign in with your ChatGPT account or API key, point it at a project folder, and type your first request in plain English.
What's the difference between the CLI, desktop app, IDE extension, and the cloud version?
All share the same models and account. The CLI and desktop app run locally and are best for interactive sessions where you review each change. The IDE extension embeds Codex in VS Code or similar editors. The cloud/web version runs tasks asynchronously in isolated OpenAI-managed containers — you can delegate a task, close your laptop, and come back to a pull request.
Do I need to know how to code to use Codex?
No coding knowledge is required to start. Non-technical users are advised to begin with the desktop app or web interface, which feel less intimidating than the terminal. You can ask Codex in plain English to explain what a project does or propose a change. That said, the cloud workflow produces git diffs and pull requests, so a basic idea of what those are helps when reviewing output.
Is my code sent to OpenAI's servers? Will it be used to train future models?
When using Codex, your code is processed by OpenAI's servers — that is how the model reads and edits it. By default on consumer plans (Free, Plus), OpenAI may use your content for training; you can opt out in the privacy settings. Business, Enterprise, and Edu plans have training off by default. Codex also has separate settings for allowing or blocking training on full environments.
7Glossary 22 terms
Show the 22 terms
Codex
codex- The OpenAI Codex CLI tool — a lightweight AI coding agent you run in your terminal that can read files, write code, and execute commands on your behalf.
codex exec- Runs Codex non-interactively from the command line, streams results to your terminal or a file, and exits when the task is done — useful for scripting or automation.
codex mcp- A Codex subcommand that manages connections to Model Context Protocol servers, which let Codex reach external tools and data sources beyond your local files.
-i- Short for --image; attaches one or more image files to your prompt so Codex can see screenshots, diagrams, or other visuals when answering.
--image- Attaches one or more image files to your prompt so Codex can see screenshots, diagrams, or other visuals when answering.
-m- Short for --model; lets you choose which AI model Codex uses for a session (e.g., codex -m gpt-5.5).
--json- Makes Codex print its output as newline-delimited JSON events instead of formatted text — useful when another program needs to read the results.
--output-schema- Points Codex to a JSON Schema file; Codex validates its final response against that schema before finishing, ensuring the output has the exact shape your code expects.
-o <path>- Short for --output-last-message; writes the assistant's final reply to a file at the given path, making it easy to pipe results into other scripts.
/model- An interactive slash command that lets you switch the AI model Codex is using mid-session without restarting.
/permissions- An interactive slash command that sets what Codex is allowed to do without asking first — adjusting the approval threshold for the current session.
~/.codex/config.toml- The main user-level configuration file for Codex, stored in your home directory, where you set durable defaults like model, MCP servers, and feature flags.
~/.codex/AGENTS.md- A personal instructions file Codex reads before every session — write it in plain English to tell Codex about your preferences, coding style, or recurring context.
.git- A hidden folder Git creates inside every repository to store the project's full version history and configuration — its presence tells tools (including Codex) that the folder is a Git repo.
workspace-write- A sandbox mode that lets Codex read and edit files inside your current project folder, but blocks it from writing elsewhere on your computer or accessing the network.
untrusted- An approval policy that lets Codex run commands it recognises as safe automatically but stops and asks you before running anything outside its trusted set.
on-request- An approval policy that lets Codex work freely within its sandbox but pauses to ask for your permission whenever it needs to go beyond those boundaries.
never- An approval policy that lets Codex act fully autonomously without asking for permission — it still respects the sandbox limits, but never pauses for human approval.
npm test- A standard command that runs the automated tests defined for a JavaScript or TypeScript project — if all tests pass, the code behaves as expected.
gpt-5.5- OpenAI's most capable Codex model (as of mid-2026), best for complex coding, research, and multi-step tasks — the recommended default when quality matters most.
gpt-5.4-mini- A faster, lower-cost Codex model suited for simpler or repetitive tasks where speed matters more than maximum reasoning power.
gpt-5.3-codex-spark- A text-only research-preview Codex model built for near-instant response (over 1,000 tokens per second), optimized for real-time coding iteration — available to ChatGPT Pro subscribers.
8See also
💬 Discuss this chapter
Ask, share, or report — over on the Heidelberg AI community forum.