1. From Autocomplete to Agents: What Codex Is

If your mental model of AI coding help is "fancy autocomplete", the first ten minutes with OpenAI Codex will be disorienting. You type a sentence describing an outcome, and the tool starts reading your files, running your tests, and editing code across your repository, narrating what it does as it goes. Nothing about that resembles tab completion. This chapter builds the right mental model before you install anything, because developers who understand what the agent is actually doing get dramatically better results than developers who treat it as a magic box.

The three eras of AI coding help

The first era was autocomplete. Tools like the original GitHub Copilot predicted the next few lines of code based on the current file. Useful, but you stayed the driver at every keystroke: the model never saw beyond a narrow window of text and never took an action on its own.

The second era was chat. You pasted code into ChatGPT, asked a question, and copied the answer back into your editor. The models got much smarter, but you became the clipboard: shuttling context in, shuttling code out, and fixing all the places where the model guessed wrong about files it could not see.

The third era is agents. The model is connected to tools. It can list files, search your codebase, read exactly what it needs, edit files, and execute commands. You describe an outcome, and the agent works toward it, checking its own results along the way. That closing of the loop, from "suggests text" to "does work and verifies it", is the biggest shift in day-to-day developer tooling since version control went distributed.

What "agentic" actually means

Strip away the marketing and an agent is a loop. Each cycle looks like this:

1. The model looks at the goal plus everything it has gathered so far.
2. It decides on one next action: read a file, run a search, apply a patch, execute a command.
3. The harness (the program wrapping the model) performs that action and feeds the result back.
4. Repeat until the model decides the goal is met, then it reports what it did.

Here is what that loop looks like on a real micro-task, abridged from an actual session:

Goal: "The date formatting test is failing. Fix it."
• Ran: npm test            (sees one failing assertion)
• Searched: rg -n "formatDate" src/
• Read: src/utils/dates.js (spots a timezone offset applied twice)
• Edited: src/utils/dates.js (+3 -2)
• Ran: npm test            (16 passing)
• Reports: root cause, the fix, and the passing output

There is nothing mystical here. It is a while-loop around a language model with function calls. What makes it work now, when it did not work well a few years ago, is that the models behind Codex are trained specifically for this loop: long multi-step tasks, tool use, recovering from failed commands, and knowing when to stop and ask a human.

Meet OpenAI Codex

Codex is OpenAI's coding agent. It is powered by models tuned specifically for agentic software engineering; at the time of writing the default is from the GPT-5.1 Codex family (gpt-5.1-codex-max). The exact model name will have changed by the time you read this, and that is fine: this course teaches the workflow, which is far more stable than model names. The CLI itself is open source (the openai/codex repository on GitHub) and written in Rust, so it starts fast and behaves the same on macOS and Linux.

Out of the box, Codex can:

• explain an unfamiliar codebase, file by file, in plain language
• find and fix bugs, starting from nothing but a stack trace
• implement features that span many files
• write tests, run them, and iterate until they pass
• review diffs and pull requests and flag real problems
• automate chores: changelogs, mechanical migrations, one-off scripts

One agent, three surfaces

You can drive the same agent from three places, and they share one account and one set of usage limits:

• The CLI: you run codex in a terminal, inside a repository. This is the fastest feedback loop, it is fully scriptable, and every action the agent takes is visible.
• The IDE extension: for VS Code and its forks (Cursor, Windsurf). The same local agent, with your current file and selection wired in as context.
• The cloud: tasks submitted from chatgpt.com/codex or the ChatGPT mobile apps run in isolated containers connected to your GitHub repositories, and results come back as proposed pull requests. The cloud side also powers automatic code review on GitHub.

This course is CLI-first. When you can see every command the agent runs, you build accurate instincts about what it is good at, and those instincts transfer directly to the IDE and cloud surfaces, which chapter 9 covers in detail.

A quick word about the name

"Codex" has meant two different things. The 2021 Codex was an autocomplete-era model, the one that originally powered GitHub Copilot; OpenAI retired it years ago. The name came back in 2025 attached to the agent you are learning now. This matters when you search the web: tutorials about the old Codex API are useless for the agent, and mixing them up wastes an afternoon. Check the date on anything you read, and prefer material from mid-2025 or later.

What Codex is genuinely good at

Look at the pattern behind every strong use case: the work is verifiable. The agent thrives when there is a way to check the result mechanically.

• Bug fixes where a reproduction or failing test exists, or can be written
• Mechanical changes repeated across many files, where humans get bored and sloppy
• Writing tests for existing behavior, including edge cases you did not list
• Code archaeology: "what does this module do, and why is this check here"
• Glue work: build scripts, CI tweaks, scaffolding, data munging one-offs

What it will not do for you

An honest tool description includes the failure modes, and this course will keep returning to them.

• It does not know your product, your users, or why that weird workaround exists, unless you tell it or it is written down in the repo.
• It sometimes writes confidently wrong code. Confidence is not correctness, and polish is not proof.
• It can misreport its own work, for example claiming tests pass when it never re-ran them after a final tweak. Chapter 7 is entirely about defending against this.
• It will not own consequences. You review every diff, and you own the merge button.
• It changes where your effort goes rather than removing effort: less typing, much more reading and reviewing.

If critically reading other people's diffs is not currently a strength of yours, expect that skill to grow fast. Agentic tools reward it more than any other single skill.

What you need to follow along

• Comfort in a terminal, and git basics: branch, diff, commit, reset.
• macOS or Linux. On Windows, run everything inside WSL2.
• Either a paid ChatGPT plan (Plus, Pro, Team, Edu, or Enterprise) or an OpenAI API key for usage-based billing.
• A small, non-production repository to practice on. Real code you know well is ideal.

Next up: getting Codex installed, signed in, and configured, which takes about ten minutes end to end.