Running Your First Task

📚 Series Navigation: The previous article 05 · Connecting Third-Party Models Like DeepSeek explained the wild path of "switching brains." That concludes the configuration part of the series—this article gets down to business, letting Codex modify your code for real and running through the complete loop from listing requirements to reviewing the diff for acceptance. The next article 07 · Desktop App Overview will explore the Desktop App face of Codex.

Hey guys, let me share a stupid thing I did when I first started using Codex.

It was my first night after installing the Codex CLI, and I was excited to see if it could actually modify code. I directly cd'ed into our company's two-year-old legacy repository with hundreds of files and threw a broad prompt: "Refactor the user module, it's too messy." Codex spent about ten seconds reading files, scrolled the terminal screen until my eyes blurred, and then spat out a massive chunk of changes—spanning seven or eight files. I thought to myself "it should be fine," and hit approve without looking closely at the details.

The result? It did "refactor" it, but it also changed two API signatures I hadn't asked it to touch, causing local tests to fail immediately. It took me nearly an hour to review its changes line-by-line and pick what to keep and what to roll back. My biggest lesson that night wasn't 'Codex is bad,' but 'I skipped the step I should have paused for—reviewing the diff.'

To be honest, that action is the one I want to pass on to you the most in this article. Today we won't touch large projects; we will build a toy project with just three lines of code and spend five minutes running through the loop of 'list requirements → Codex modifies in the sandbox → review diff for acceptance → keep or roll back' so you get the success experience of "Codex modified my code correctly, and I understood the whole process clearly." I will guide you through both the Desktop App and CLI paths.

After reading this article, you will get:

• A step-by-step action flow from opening the terminal/App to running your first task—just follow along
• The core action of "reviewing the diff" engraved into your muscle memory—the biggest divide between beginners and pros
• Step-by-step operations + expected outputs for both the Desktop App and CLI paths to verify your success
• Key reminders so you don't fall into traps on your first run (how to follow up after a rejection, how to roll back if things go wrong)

⚠️ All specific commands, parameters, and default behaviors mentioned below are based on the Codex official documentation; model names and UI text are subject to change and should match what is actually displayed on your local system.

---

01 Do Not Practice on Real Projects, Start with a Toy

First, the conclusion I bought with an hour of my time: when using Codex for the first time, never practice on a real repository; build a toy project with three lines of code.

Why? My story at the beginning explains it clearly—real projects have many files and complex dependencies. Codex will read a lot of things, making it impossible for you to track what it changed, and it is exactly when you "cannot track things" that you are most likely to click approve blindly. A toy project has only two or three lines; you can spot every single character it touches, making it perfect for practicing.

Analogy: Learning to ride a bicycle on an empty road. No one starts by riding into the morning rush hour on a main road—you start in an empty lane where falling doesn't hurt, getting a feel for balance and brakes. The toy project is your empty lane: if things break, you can delete it and rebuild it in thirty seconds without panic.

Who should pay special attention to this advice:

• Those who have never touched a command line—just watching the terminal screen scroll as Codex reads files is enough to make your palms sweat; don't add the pressure of "modifying a real project."
• Those who just switched from other tools—for example, if you are used to Claude Code and expect Codex to follow the same patterns, only to find its sandbox and approval rhythm differ from your expectations (which is what Articles 05 and 02 warned about). Get a feel for its temperament on a toy first.
• Those who are in a rush to get work done—the more in a rush you are, the more you should verify the loop with a minimal flow first. Verifying the pipeline is much faster than fixing a broken project midway.

Open your terminal (Terminal App on Mac, PowerShell on Windows) and type these two lines to build a toy directory:

mkdir hello-codex
cd hello-codex

These lines mean: create a folder named hello-codex and enter it. mkdir = make directory; cd = change directory.

Next, place a simple Python file inside. On Mac / Linux, run:

echo 'def add(a, b):
    return a + b' > main.py

On Windows PowerShell, writing multi-line text with echo is slightly awkward; you can open Notepad, create a file named main.py, paste these two lines, and save it:

def add(a, b):
    return a + b

💡 Summary in one sentence: For your first run with Codex, build a toy project with three lines of code as an "empty lane"—you can easily see what it modified, and delete it to rebuild if it breaks, keeping your mind at ease.

---

02 State Your Requirements Clearly: The "Think → Do → See" Loop

Now that the project is built, don't rush to start it; take a minute to think about what you want it to do and how to state it.

Why talk about this first? Because Codex is not a wishing well—the quality of what you get out depends on the quality of the prompt you put in. Section 02 explained that it is an agent (Agent) that works in a loop: invoking the model, executing instructions (reading files, modifying files, invoking tools), and repeating until the task is done or canceled. In plain English, it boils down to: Think → Do → See.

Analogy: Handing work to a reliable contractor. If you say "tidy up this room," they can only guess, and it will likely not match what you want; if you say "paint the master bedroom off-white, add a sink to the balcony, and finish by next Friday," they know exactly what to do and how to inspect their work. The more specific your requirements are, and the clearer the definition of completion is, the less likely the contractor (Codex) will wander off. This matches the two core recommendations in the official "Prompting" documentation:

• Enable self-validation: Include reproduction steps, acceptance criteria, or lint/test commands in your prompt. The quality of Codex's output will be significantly higher.
• Break large tasks into steps: Split complex tasks into small, focused steps, making them easy to test and review. If you don't know how to split them, ask Codex to outline a plan first.

Compare the "vague" and "specific" prompts below to feel the difference:

❌ Vague Prompt	✅ Specific Prompt
"Optimize this function"	"Add type annotations to add, and raise a TypeError if non-numbers are passed"
"Why is this test failing?"	"Run pytest, locate the failure cause, fix it, and run tests again to verify all green"
"Refactor the project"	"Do not modify anything yet; write a refactoring plan for me first, and I will confirm before you start editing"

The last line is my most common starting move now—for any work that is slightly large, my first prompt is always "give me a plan first, do not edit anything." This is what I learned from my initial refactoring incident: let it present the plan first, review the direction, and then let it edit, which is much better than cleaning up a mess after it edits blindly.

💡 Summary in one sentence: Codex works in a "Think → Do → See" loop; the more specific your prompts and acceptance criteria are, the less likely it is to go off track. Let it write a plan first for large tasks instead of editing immediately.

---

03 The First Task: Read, Do Not Modify (Verify File Access)

For your first actual task, I recommend asking it to explain code rather than modifying it.

Why explain first? Two practical reasons: first, confirm that Codex actually reads your files instead of hallucinating (the biggest doubt for beginners is "did it actually read my code?"); second, explanation tasks carry zero risk—it only reads and talks without modifying a single character, making it perfect for your first run.

Analogy: A new partner's first day on the job; you ask them to "read the code and tell me what this part does." You wouldn't throw a core module at them for refactoring right away—listen to them explain it first, and you'll immediately know if they understood it and are reliable. Asking Codex to explain code is this "day one" probe.

Whether using the CLI or the App, type this in the input box (use plain language, no need to remember formats):

Explain what main.py is doing, in terms a beginner can understand

Press Enter. Codex will read main.py itself—you don't need to manually attach or upload the file; it reads the relevant files automatically in the agent loop. Then it will explain in plain language: it defines an add function that takes two arguments, a and b, and returns their sum.

Running this step successfully means two things are verified: Codex is installed correctly with a valid login state, and it is actually reading real files on your computer. The foundation is solid; now you can let it modify files.

Divide Codex prompts into three types to keep things clear:

Prompt Type	What It Does	Example	Risk
Explaining	Understand and explain code	"Explain this code"	Zero risk; does not touch files
Modifying	Edit existing code	"Add type annotations to this function"	Modifies files; must review diff
Generating	Write new code	"Add a test case"	Creates/modifies files; must review diff

Whenever I enter a new project, my first prompt is always "explain the structure of this project." First, it confirms Codex can read it correctly; second, the map it draws is often clearer than my own file browsing—a nice bonus of explanation tasks.

💡 Summary in one sentence: Start with "explaining" tasks to verify Codex—confirm it reads your files correctly before letting it modify code; modifying and generating tasks will require reviewing the diff later.

---

04 Core Action: Reviewing the Diff (The Most Critical Section)

Here comes the core: letting Codex modify code for real. This section is the key to safety; my one-hour incident happened because I didn't handle this part well.

Continuing the session, type:

Add type annotations to the add function in main.py, and add basic error handling

Let's clear up a common misunderstanding first—under default settings, Codex modifies files in the workspace directly; it does not pause to prompt you for every single file it changes. Why? Section 02 explained that in the default Auto mode (workspace-write sandbox + on-request approval), reading, modifying files, and running commands inside the workspace are "in-bounds actions," which the sandbox allows by design, so it executes them without interrupting you. Only "out-of-bounds" actions—such as modifying files outside the workspace or accessing the internet—will pause to ask you. In other words, its default rhythm is:

1. Locate the file to modify (here main.py), and apply the modifications directly in the sandbox.
2. Present what it changed as a diff (difference comparison)—printed in the terminal, or viewable with git diff.
3. You act as the gatekeeper: scan the diff, keep it if it is correct, tell it to change it back if it is wrong, or roll back with Git (covered in the next two sections).

So is "reviewing the diff" still important? Absolutely—it just moves from "approve-before-edit" to "review-after-edit." Codex applies the edits to disk and presents the diff to you; scanning this is your quality check. If you find a mistake, the edits are not committed yet, and you can roll them back with a single command. So the default mode is not "skipping your review" but "modifying first for you to review via diff and Git."

⚠️ Running git diff and Git rollbacks require that your project is a Git repository. If you haven't run git init yet, git diff cannot compare versions, so you won't see the changes—make sure the repository is clean with git status before letting it work. The "Hands-on" section below will guide you to git init a checkpoint first before letting Codex edit. (The diff printed directly in the Codex terminal is unaffected and will display anyway.)

Analogy: A colleague commits changes to a temporary branch and asks you to review. They modified the code without waiting for your nod, but the changes are on a branch, not merged into the main branch—you scan where they edited, merge it if satisfied, or tell them to roll it back if not. Codex defaults to this kind of colleague who "edits first, presents the diff, and lets you decide via diff and Git," and the diff is what it presents.

⚠️ Want to "prompt before editing / only plan without modifying"? That is not the default mode; you must tighten permissions: run /permissions in the session to switch to read-only (read and analyze only, ask before editing), or say "give me a plan first, do not edit." The default Auto mode edits directly and lets you gatekeep after.

How to Read a Diff

A diff is a line-by-line comparison of "before" and "after." To read it, just remember:

• Lines starting with - / colored red are old lines to delete
• Lines starting with + / colored green are new lines to add
• Unmarked lines are unchanged context, helping you locate the changes

Your main.py will likely change from:

def add(a, b):
    return a + b

to something like this (exact code may vary, as long as the logic is correct):

def add(a: float, b: float) -> float:
    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
        raise TypeError("a and b must be numbers")
    return a + b

It added type annotations (a: float) and basic error handling (raise TypeError(...)). Scan the diff and ask yourself three questions:

1. Did it edit the place I asked it to? (Don't let it touch B when you asked it to edit A)
2. Do I understand and agree with the added logic?
3. Did it delete anything I wanted to keep?

If the answer to all three is "yes," keep the changes. If not, tell it to modify it in the session, or roll back with Git (covered in the next two sections). This scan is "reviewing the diff"—it takes less than ten seconds, but it is the biggest divide between beginners and pros.

When Will It Stop to Ask You?

Under default Auto settings, editing files in the workspace does not prompt for approval, so you won't see an "approve/deny" prompt for adding type annotations here—the edits are applied directly and the diff is printed. When does the "approve/deny" prompt show up? Only when it needs to take an out-of-bounds action—typically:

What Codex Wants to Do	Under Default Auto Settings	What You Will See
Read / edit files in workspace	Runs directly, does not interrupt	Usually no prompt; prints diff after editing
Run commands in workspace (e.g., tests)	Runs directly, does not interrupt	Usually no prompt
Run out-of-bounds commands (e.g., install packages)	Pauses to ask first	"Approve / Deny" prompt
Edit files / access network outside workspace	Pauses to ask first	"Approve / Deny" prompt

When you see the "Approve / Deny" prompt, select accordingly: approve if you understand and feel safe; deny and explain if something is wrong. Different entries have slightly different wording, and some offer an "approve and don't ask again this session" option.

A golden rule for beginners: do not loosen permissions to the maximum (like never or full access) when starting out. I learned this the hard way—once set to the loosest settings, it won't ask for out-of-bounds actions, modifying five or six files in one go without you reviewing, leaving you unable to separate what you wanted from what it added on its own. The lesson is: the less familiar you are, the more you should retain the "ask before out-of-bounds + review diff after edit" checks.

⚠️ Sandbox modes and approval policies are adjustable (Section 02 covered read-only/workspace-write and on-request/never; 15 Permissions in Detail will cover them further). Tightening them (like read-only) requires approval even for editing files; loosening them (like never/full access) skips prompts even for out-of-bounds actions. Confirm you trust the task before loosening permissions.

💡 Summary in one sentence: Under default settings, Codex edits files in the workspace directly and prints the diff, prompting you only for out-of-bounds actions; reviewing the diff checks if it edited the right place, if the logic is sound, and if it deleted anything important; do not max out permissions on your first run, keep the gates.

This diagram maps out the logic: list requirements → Codex analyzes → edits files in sandbox. Workspace actions (green path) apply directly without asking; out-of-bounds actions (red path) pause to ask you. After editing, it reaches the "review diff" step—commit with Git if satisfied, explain changes in the session or roll back with Git if not, routing back to try again.

---

05 Rejection Is Not the End: Follow Up to Try Again

Beginners often assume "denying" or "rejecting" means the task is aborted and you must start over. No. Rejection is an opportunity to "change direction and try again."

Codex works in a thread (Thread)—defined officially as a session containing your prompts, model outputs, and tool calls. A thread can span multiple turns of conversation. So whether you deny an out-of-bounds request or dislike a diff, the session context remains, and you can just explain what to change next.

Analogy: A dish is not to your liking; you don't leave the restaurant—you tell the waiter "this is too salty, please make a milder version." The kitchen remembers the order context and your previous instructions; it only modifies what you are unhappy with. Rejecting a diff and explaining what to change is this "send it back to the kitchen" move, which is very cheap.

Here is a real example from last week: I asked Codex to add caching to a function, and the diff showed it importing a third-party library I hadn't installed. I denied the change and prompted:

Do not import third-party libraries; use Python's built-in functools.lru_cache instead

It withdrew the plan, rewrote it using the standard library, presented a clean diff, and I approved it. We never exited the session or re-explained the requirements—that is the convenience of "reject and follow up."

Keep this mindset shift in mind:

❌ What Beginners Assume	✅ The Reality
Rejection = task aborted, effort wasted	Rejection = tell it to change direction and try again
If unhappy, I must edit it myself	Explain what is wrong in plain language, and it rewrites
Restart session whenever it fails	Multi-turn iterations in the same thread preserve context

💡 Summary in one sentence: Disliking a diff (or denying a request) is not the end, it is a "send it back" move—explain what is wrong in the same thread, and Codex will adjust its edits without exiting or starting from scratch.

---

06 What if Edits Are Applied? Git Is Your Ultimate Undo Button

If you click approve without looking closely (like I did) and the edits are applied to disk—should you panic? No, as long as you did one thing: created a Git checkpoint.

This is an official recommendation in the Codex quickstart: "Codex will modify your codebase; we recommend creating a Git checkpoint before and after every task so you can roll back easily." The undo button is Git, not a built-in feature of the tool.

Analogy: Saving your game before a boss fight. You save before the fight; if you lose, you don't start the game from the beginning—you load the save. git commit is this save point you create before letting Codex edit—if it breaks things, you load the save and try again.

What to do? Before letting Codex edit, run in the project directory (only run git init the first time):

git init
git add -A && git commit -m "savepoint before codex"

If it breaks things and you want to roll back completely to the savepoint:

git restore .

⚠️ git restore . discards all uncommitted changes in the workspace, reverting to the last commit. Only use it if you want to completely discard Codex's changes; if you want to keep some correct edits, do not run this broad command; use the turn-based method below.

If you only want minor adjustments, the easiest way is to tell Codex to revert it in the session—it remembers what it edited in the thread:

I am unhappy with the last change, please revert main.py to how it was before

Compare the two undo options to choose:

Undo Option	How to Use	Scenario	Limitations
Prompt "revert it"	Explain to Codex in the session	Just edited, unhappy with a few spots	Relies on its understanding; not permanent
Git Rollback	commit before starting, git restore . if it fails	Reverting cleanly to a verified state	Requires making commits; restore is all-or-nothing

My rule: always run git commit before letting Codex edit anything important. This habit has saved me more than once—when it modified a configuration file beyond recognition, I didn't bother reviewing; I ran git restore and adjusted my prompts, which took three seconds. Git is your ultimate shield.

💡 Summary in one sentence: Don't panic if Codex breaks things—git commit to save before editing, and git restore . to load if it breaks; ask it to "revert it" in the session for minor tweaks, but leave permanent rollbacks to Git.

---

07 Hands-on 1: Running the Complete Loop in the CLI (5 Mins)

Reading is not enough. This section provides a step-by-step guide with expected outputs using the CLI. Open your terminal and follow along.

Step 1: Create a toy project and create a Git checkpoint (Mac / Linux)

mkdir hello-codex && cd hello-codex
echo 'def add(a, b):
    return a + b' > main.py
git init && git add -A && git commit -m "initial version"

Windows users: run mkdir and cd as above, create main.py using Notepad with the Python code, and run the Git commands.

Expected output: hello-codex contains main.py (with the add function), and there is one Git commit. You can run ls (or dir on Windows) to verify.

Step 2: Launch Codex in the project directory

codex

Expected output: The Codex interactive interface appears with the input prompt at the bottom. If it prompts you to log in, return to 03 · Installation and Login to complete the login process.

⚠️ Always launch codex in the project directory; do not start it in your home directory or desktop. Codex treats the directory you start it in as the workspace—where it reads and edits. This is the first trap beginners fall into.

Step 3: Ask it to explain the code (zero-risk probe)

Explain what main.py is doing, in terms a beginner can understand

Expected output: Codex reads main.py and explains in plain language that it defines a function to add two numbers. Seeing it explain the add function correctly = file access verified. Success.

Step 4: Let it edit code and review the diff

Add type annotations to the add function in main.py, and add basic error handling

Expected output: Under default settings, Codex edits main.py directly and prints the changes as a diff (red - for deletions, green + for additions) in the terminal. Review it using the three questions in Section 04. If it requests out-of-bounds actions, click Approve only after reviewing.

Step 5: Verify edits on the disk

Exit Codex (press Ctrl + C or type /exit as prompted), and check the file:

cat main.py

(On Windows PowerShell, use type main.py)

Expected output: main.py has type annotations (like a: float) and error handling (raise TypeError(...)). It matches the diff you approved = complete loop verified. Congratulations!

To see exactly what changed from a Git perspective, run:

git diff

Expected output: The terminal prints a diff matching what you saw in the Codex session. The terminal diff matches the file edits, confirming transparency.

💡 Summary in one sentence: The CLI loop has five steps—create a project and commit → launch codex → explain code to probe → edit code and review diff → verify changes with cat/git diff. Remember to start it in the project directory, and commit before editing.

---

08 Hands-on 2: Running the Same Task in the Desktop App

For those who prefer a graphical interface, the Desktop App turns the commands into clicks. Note: The Desktop App is only for macOS and Windows; Linux has no App for now (Linux users follow the CLI guide above).

The rhythm of the App is identical to the CLI, replacing terminal commands with UI clicks while keeping the "review diff" step unchanged. Follow the official quickstart:

1. Open the Codex App, log in—using a ChatGPT account or API key (03 covered the difference).
2. Select Project Folder—choose the folder where you want Codex to work. For this practice, choose the hello-codex folder (or create a new empty directory). Your history will list this project if you used the App/CLI before.
3. Verify Local is selected—before sending the first message, make sure Local is selected (the exact location depends on the UI version), so Codex edits files on your machine instead of the cloud. This is easily missed by beginners.
4. Send your first message—type your requirements into the input box:

Explain what main.py is doing, in terms a beginner can understand

Once it explains it correctly, send the edit prompt:

Add type annotations to the add function in main.py, and add basic error handling

Expected output: Under Local settings, the App edits files directly on your machine and presents what it changed in the review pane. The official docs explain that this pane reflects uncommitted changes in your Git repository. This is where the App is more convenient than the CLI—the graphical diff is easier to read, with buttons to stage, commit, or discard changes right next to it. If satisfied, commit it; if not, ask it to revert or discard the changes.

The official quickstart suggests creating a Git checkpoint before and after editing in the CLI/IDE paths to roll back easily; the App has built-in Git tools, letting you stage and commit directly in the UI.

CLI or App? Here is a comparison to help you choose:

Dimension	CLI (Command Line)	Desktop App
Platform	✅ Mac / Windows / Linux	❌ Mac / Windows only
Barrier to Entry	Requires typing commands, can be intimidating	✅ Click-and-run, beginner-friendly
Reviewing Diffs	Plain text diff in terminal; sufficient	✅ Graphical review pane; cleaner
Multi-tasking	Open multiple terminal windows	✅ Switch between multiple projects side-by-side
Core Process	Prompt → Edit → Review diff	Identical, just via a graphical interface

My usage: I stay in the CLI for coding and running commands (fits my habits, cross-platform); but if a task has many changes and a long diff, I switch to the App to review the diff, since the graphical pane is much easier to read than terminal text. Once logged in, both are usually available (subject to official auth rules), so choose what fits you.

💡 Summary in one sentence: The Desktop App turns the task into clicks (Mac / Windows only); make sure Local is selected before sending prompts. Its review pane is great for reading long diffs, but the core process of "Codex edits, you review the diff" is identical to the CLI.

---

09 The Complete Loop in One Diagram

Let's conclude this article's loop with a diagram—whether you use the CLI or the App, you run through this loop:

The most important part to focus on is the review diff split: Codex edits files in the sandbox and presents the diff; keep it if you understand it, ask it to rewrite or roll back with Git if not—this "human gatekeeper" step is the safety valve of your collaboration with Codex. My one-hour incident was caused by skipping this.

💡 Summary in one sentence: The first task boils down to one loop—prompt → Codex edits in sandbox → you review diff → keep or roll back. Hardcode the "review diff" step into your process to avoid repeating my mistake.

---

10 Summary

In this article, you completed a real task: running your first task in Codex—from project creation and startup to explaining code, editing, and reviewing the diff, covering both the CLI and App paths.

Let's review the steps:

Step	Action	Key Point
Create Project	mkdir + create file + git commit	Practice on a toy first; save before editing
State Requirements	Plain language, the more specific the better	Ask for a plan first for large tasks; do not edit blindly
Explain	"Explain main.py"	Zero risk; verify it reads files correctly
Edit	"Add type annotations to..."	Default mode edits directly and displays the diff; you gatekeep after
Review Diff	Scan: right place? logic sound? deleted anything?	The divide between beginners and pros; do not skip
Rollback	"Revert it" / git restore .	Git is your ultimate undo button

You should now be able to: launch Codex in the CLI or App, use natural language to have it read and modify code, read the diff and decide whether to keep or discard changes, and roll back edits if they go wrong.

This loop—prompt → inspect diff → keep / modify / roll back—is the core of all your work with Codex. More advanced features (MCP, subagents, skills, automation) will build on this foundation. And the most critical action to keep in muscle memory is "reviewing the diff"—don't spend an hour learning it the hard way.

💡 Summary in one sentence: The core of your first task is simple—prompt → Codex edits → you review the diff → keep or roll back. Default settings edit directly and let you gatekeep via diff and Git; switch to stricter modes if you want to approve before editing.

---

The next article 07 · Desktop App Overview: you've got a taste of the App in this article, but it can do much more than editing code: multi-project management, worktree isolation, built-in browser, automated tasks... The next article will explore the Desktop App. Ask yourself: did you find the graphical review pane in the App cleaner than terminal text? If so, you will likely love the next article.

---

Recommended Reading

• Non-interactive Mode codex exec: Running Codex in scripts and CI
• Cloud Codex: Outsourcing tasks to the cloud and waiting over coffee
• Getting Started with the CLI