Codex: agentic coding in your environment

In Canvas (the previous lesson's tool) you edit one document or file collaboratively. Codex is different: it operates across the whole repo and can execute. That single capability, running a command and reading the output, is what turns a code generator into an agent. It writes a test, runs it, sees it fail, edits the implementation, runs again. You are no longer copy-pasting snippets. You are reviewing a finished, tested change.

Setting up: the local CLI

Let's use the CLI because it makes the loop most visible. Install and authenticate:

On first run it authenticates through your ChatGPT account (or an APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → key) and detects the repo. From here you can type a task in plain language at the prompt.

The single most important file you can add is AGENTS.md at the repo root. Think of it as custom instructions scoped to this codebase: it tells Codex how to build, test, and behave. Codex reads it automatically.

This is the difference between an agent that flails and one that fits your project. Spend ten minutes here and every future task gets cheaper.

A concrete walkthrough: implement a small feature and run the tests

Here is the scenario. Our billing-service has a discount module. We want a new function that applies a percentage discount to an order total, with validation. We want it tested. Watch the agentic loop.

Step 1: Give the task

At the Codex prompt:

Notice what we did and did not specify. We described behavior and edge cases, not implementation. We explicitly asked it to run tests, which is the instruction that activates the loop.

Step 2: The agent plans and reads

Codex first explores. It greps for discount.py, reads the existing functions to match style, and checks how other tests are structured. This read-before-write step is why a clean AGENTS.md and a tidy repo pay off: the agent imitates what it sees.

It then states a short plan: create the function, add test_discount.py, run pytest.

Step 3: It writes the code

It produces something like this and writes it to disk:

And a matching test file with the cases you asked for.

Step 4: It runs the tests (the loop)

This is the part you cannot get from a plain chat. Codex executes poetry run pytest -q in the sandbox. Suppose one boundary test fails because of a floating-point comparison. The agent sees the failing output, edits the test to use pytest.approx, and reruns. Green. It does this without asking you, because the work happened inside an isolated environment, not on your production branch.

You will see each command and its output stream in the terminal. That transparency is the point: you are watching the reasoning, not trusting a black box.

Step 5: The review step

When the loop settles, Codex shows you a unified diff of everything it changed. Nothing is committed yet. You read it like a pull request:

• Does apply_percentage_discount match your rounding expectations? (Maybe you want round(..., 2).)
• Are the tests meaningful or trivially passing?
• Did it touch any file it should not have?

You can approve, ask for a revision in natural language ("round the result to 2 decimal places and add a test for that"), or discard. The review step is non-negotiable. The agent is fast and competent and still sometimes wrong, so you remain the gate.

Approval modes: how much rope to give it

Codex lets you set how autonomous it is. The exact labels evolve, but the spectrum is consistent:

• Suggest / read-only: it proposes edits and commands but asks before doing anything.
• Auto / workspace-write: it edits files and runs commands inside the working directory without promptingpromptingPrompt engineering is the practice of designing and refining text inputs to guide large language models toward accurate, relevant, and reliable outputs.View full definition →, but stays sandboxed.
• Full access: it can run anything, including network calls. Use this rarely and deliberately.

A good default for real work is the middle mode with network access off. The agent can edit and test freely but cannot reachreachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → the internet, which closes off a large class of accidents (and prompt-injection risks if it reads untrusted files). Turn network on only when a task genuinely needs to fetch a dependency.

Cloud Codex and parallel tasks

The CLI is great for working alongside the agent. The cloud Codex in ChatGPT is built for delegation. You connect a GitHub repo, then hand off a task ("fix the flaky test in test_orders.py") and let it run in its own container. You can fire off several tasks in parallel and check back later.

When cloud Codex finishes, it can open a pull request directly on GitHub. Your review step becomes a normal PR review with CI attached, which is exactly where a careful team wants the human checkpoint to live. This is the model for batch work: triage three small bugs on Monday morning by describing each one, then review three PRs over coffee.

Where Codex fits next to the rest of the ecosystem

You now have several agentic surfaces in the OpenAI world. Keeping them straight prevents misuse:

• Codex is for working in *your* codebase: read, edit, run tests, open PRs. It is engineering.
• Advanced Data Analysis (Code Interpreter) runs Python in a throwaway sandbox to analyze a file or make a chart. It is not connected to your repo and is not meant to ship code into it.
• Canvas is a focused editing surface for a single document or file with you in the loop on every change. It does not run your test suite across a project.
• The ChatGPT agent browses, clicks, and uses tools to complete general web and computer tasks. It is not a coding agent.

If you are building your own agent in software rather than using these products, that is the Agents SDK and the Responses APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →, which expose function calling and tool use as primitives. Codex is the productized, coding-specialized version of those same ideas, with the sandbox, the repo integration, and the diff review built for you.

A realistic engineering rhythm

Here is how teams actually use it day to day:

1. Scoped tasks, not vague wishes. "Add input validation to the signup endpoint and tests" works. "Improve the codebase" does not. Small, verifiable tasks keep the loop honest and the diffs reviewable.

2. Let tests be the contract. Because Codex runs them, a strong test suite is your steering wheel. Ask it to write the test first when the behavior is precise.

3. Keep `AGENTS.md` alive. When the agent does something annoying twice, that is a missing instruction, not a model failure. Add the rule.

4. Review every diff like a PR. Treat agent output exactly as you would a junior engineer's first draft: usually solid, occasionally subtly wrong, always your responsibility once you merge.

Key Takeaways

• The loop is the value: Codex reads, writes, *runs* your commands, and iterates on failures, all inside a sandbox. Always include "run the tests" in your task so the loop actually fires.
• Write an `AGENTS.md` at your repo root with build, test, and convention instructions. It is the single highest-leverage setup step and makes every task more accurate.
• Default to workspace-write with network access off. Give full access only for specific tasks that need it.
• The diff review is your job, not optional. Approve, revise, or discard like a pull request; use cloud Codex to open real PRs when you want CI and team review in the path.
• Use the right surface: Codex for your codebase, Code Interpreter for one-off analysis, Canvas for single-file editing, and the Agents SDK when you are building agents yourself.