Run your first Codex task

A first Codex task is one small, real change whose success a test can prove: Codex reads the repository, edits files inside its sandbox, runs the project’s test command, and reports what it did. The Codex CLI is the reference surface. The desktop app, the IDE extension, and Codex cloud run the same agent with different isolation and review.

This page is for developers who have installed Codex, signed in, and now face an empty composer. The tempting first prompt is “refactor the auth module”, and it returns a 14-file diff you cannot judge. A better first task ends in a test that fails without the change and passes with it, so you can accept the result on evidence instead of reading every line.

What you’ll walk away with from your first Codex task

• A checklist for choosing a first task that a test can prove.
• A first-task prompt with acceptance criteria, a plan checkpoint, and a report format, plus a variant for repositories without an HTTP layer.
• The exact commands for Codex CLI 0.157.1 to run the task interactively, in a Git worktree, headless, and in Codex cloud.
• A five-minute verification routine, including a check that the new test can actually fail.
• Recovery steps for the ways a first task usually goes wrong.

Before you start: what has to be in place

1. Codex runs and you are signed in. codex doctor reports no errors. If it does, work through installation and authentication first.

2. The working tree is clean. Codex edits real files, and Git is your undo. Commit or stash anything in progress:

   git status --short        # should print nothing

3. You know the project’s test command and it passes today. Run it once yourself. If the suite is already red, Codex cannot show you that it turned it green.

4. Optional but worth it: an AGENTS.md. Run /init inside Codex to draft one, then correct the test command and folder layout by hand. Set up AGENTS.md for Codex explains what to put in it. Since codex-cli 0.150.0, a project you have not marked as trusted does not supply its AGENTS.md, so answer the trust prompt when Codex first opens the repository.

Pick a first task that a test can prove

The best first task has one observable behaviour, touches one to three files, and has an existing test runner to prove it. That keeps the diff small enough to check in minutes and gives you an objective signal.

Good first task	Poor first task	Why
Fix a missing error path in one API route and add a test for it	“Improve error handling everywhere”	One behaviour, one test; the broad version has no finish line
Handle an edge case in a pure function (empty list, null, time zone)	Migrate the project to a new framework	A pure function is testable in isolation; a migration needs a plan first
Add input validation to one endpoint, with a 400 test	Redesign the database schema	Validation is reversible; a schema change needs a migration and review
Add a missing test for an untested branch	“Make the tests faster”	“Faster” has no acceptance criterion

The walkthrough below uses the first row. It exercises everything a first task should: reading the codebase, finding a concrete defect, editing code, writing a test, and running commands in the sandbox.

Write the prompt: outcome, constraints, and proof

A first-task prompt states the outcome, fences the scope, and says what evidence ends the task. The plan checkpoint in the prompt below costs one extra turn and catches a wrong direction while it is still a paragraph of text.

Copy-paste prompt: fix one error-handling gap with a test

Find one error-handling gap in this project's API routes: a place where an
exception can crash the request handler or return a misleading status code.

Before you edit anything, reply with: the file and line, an input that triggers
the problem, the fix you propose, and the test you will add. Wait for me to reply "go".

After I reply "go":
1. Write the test first and run it. It must fail for the reason you described.
2. Make the smallest fix that makes it pass. Touch at most 3 files.
3. Do not modify, skip, or delete any existing test.
4. Run the full test suite.

Finish with: files changed, each command you ran with its exit code, and the name
of the new test.

If the project has no HTTP layer, point the same structure at a pure function. The shape stays the same: locate, propose, wait, test first, fix, report.

Copy-paste prompt: handle an edge case in a pure function

Find one function in src/ that returns a wrong result or throws on an edge case:
an empty collection, a null or undefined argument, a zero, or a date near a
daylight-saving change. Show me the input, the current output, and the expected
output before you change anything, and wait for "go".

After "go": add a failing test for that input, fix the function with the smallest
change, keep every existing test untouched, and run the whole suite. Report the
files changed and each command with its exit code.

Run the task in the Codex CLI

The CLI shows every file read, command, and approval as it happens, which makes it the clearest place to watch a first task.

1. From the repository root, start Codex in a new managed Git worktree so the change cannot touch your main checkout:

   codex --worktree

   Plain codex also works and edits your current checkout. With --worktree, the change lives in that worktree, not in the directory you started from, so run the verification checks further down from inside it: git worktree list in your main checkout prints its path. Either way, once you trust the repository and unless your config says otherwise, Codex runs with the on-request approval policy and the workspace-write sandbox: it can edit and run commands inside the workspace, and it asks before writing elsewhere or using the network.

2. Leave the model alone for now. GPT-6 Astra is Codex’s bundled default since codex-cli 0.153.4 (2026-09-04), and its default reasoning effort in Codex is low. If the plan in step 4 comes back shallow, raise the effort to medium or high with /model before you consider another model. The models hub covers when a different model is worth it.

3. Paste the first-task prompt and press Enter.

4. Read the plan. Check that the file and line exist, that the triggering input is plausible, and that the proposed test exercises that input. If any of the three is vague, ask for it before you reply go.

5. Answer approval prompts deliberately. A request to reach the network or write outside the repository during a small fix usually means the approach is wrong, so decline and redirect. Recover from Codex errors explains each approval choice.

6. When Codex reports back, inspect the result without leaving the session:

   • /diff shows the Git diff, including untracked files.
   • /review runs a separate review pass over your current changes and lists the issues it finds.

To script the same task, for example to repeat it across several services, use codex exec. It runs without the interactive UI and writes the final report to a file:

codex exec --sandbox workspace-write -o first-task-report.md "$(cat first-task-prompt.txt)"

first-task-prompt.txt holds the prompt without the “wait for go” step, because nobody answers in a headless run, and a plan checkpoint left in by mistake stalls the run. The headless variant replaces that paragraph with an instruction to state the evidence and carry on:

Find one error-handling gap in this project's API routes: a place where an
exception can crash the request handler or return a misleading status code.

State the file and line, an input that triggers the problem, the fix you
propose, and the test you will add first, then proceed:
1. Write the test first and run it. It must fail for the reason you described.
2. Make the smallest fix that makes it pass. Touch at most 3 files.
3. Do not modify, skip, or delete any existing test.
4. Run the full test suite.

Finish with: files changed, each command you ran with its exit code, and the name
of the new test.

-o (--output-last-message) saves the final message, and --json streams every event as JSONL if you want to parse the run. If your config.toml already selects a permission profile with default_permissions, drop --sandbox: OpenAI states that the profile and legacy sandbox systems “do not compose”. Configure Codex covers both, and running Codex non-interactively covers codex exec in depth.

Run the same task in the desktop app, IDE, or Codex cloud

The agent is the same on every surface. What changes is where it runs, how you watch it, and where you review the diff.

Desktop app

On macOS or Windows, codex app launches the desktop app and opens its installer if the app is missing. From a running CLI session, /app continues that session in the app. The app has no Linux build.

Open the project, start a thread, and paste the same prompt. Use the app when you want several threads running side by side in separate worktrees and a review pane for each diff. The Codex desktop app guide covers threads, worktrees, and the review pane.

OpenAI’s README still calls it the Codex App; since 2026-07-09 it ships as the Codex mode of the ChatGPT desktop app, according to Neowin (secondary source).

IDE extension

Open the project in VS Code or Cursor with the Codex extension installed (installation covers the editors), open the Codex panel, and paste the prompt.

Use the IDE when the task is tied to what is on screen: select the route handler first and say “the selected handler” in the prompt. From the CLI, /ide pulls the current selection, open files, and other editor context into a terminal session. Review the result in the editor’s source-control diff view, then run the verification routine below in the terminal.

Codex cloud

Codex cloud runs the task in a remote container on a copy of your repository, so it keeps going when your laptop sleeps. It needs a cloud environment with your dependencies installed first; Codex cloud environments walks through the setup. Then start the task from chatgpt.com/codex or from the terminal. codex cloud is marked experimental in 0.157.1:

codex cloud exec --env ENV_ID "$(cat first-task-prompt.txt)"
codex cloud list                 # find the task id and its status
codex cloud diff TASK_ID         # read the diff locally
codex cloud apply TASK_ID        # apply it to your working tree

Codex cloud works on the branch as it exists on the remote: the current branch by default, or the one you pass with --branch. Local commits you have not pushed are not in the task, so push first.

Replace ENV_ID with the environment id that codex cloud shows, and TASK_ID with the id from codex cloud list. Add --attempts 2 to exec to get two independent attempts and keep the better one. Compare them with codex cloud diff TASK_ID --attempt 2 and apply the one you keep with codex cloud apply TASK_ID --attempt N. Once applied, the cloud change goes through exactly the same local checks as CLI work.

Verify the result without reading every line

Codex’s summary is a claim, not proof. These five checks take about five minutes and tell you where, if anywhere, your own reading is needed. You sign off; the checks decide what you look at. If you started with --worktree, run them from inside that worktree (git worktree list prints its path), or begin with /diff in the session.

1. Check the scope. The diff should match the plan you approved:

   git status --short
   git diff --stat

   A file you did not expect is the first thing to read.

2. Check that no existing test was weakened. Adjust the path to your test folder:

   git status --short -- tests/

   git status rather than git diff, because git diff ignores untracked files and a new test file would never show. Only the new test should appear, as ?? (a new file) or M (a test added to an existing file). An M or D on any other test file is the red flag. A deleted, skipped, or loosened assertion is how an agent turns a red suite green, and it never shows in a “tests pass” summary.

3. Prove the new test can fail. Temporarily remove the fix, keep the test, and run it. It must fail:

   git stash push -- src/routes/orders.ts   # the fixed source file, not the test
   npm test -- orders                       # expect a failure
   git stash pop

   Replace the path and the test filter with your own. If the fix is in a file Codex created, use git stash push -u -- <path>, because a plain stash skips untracked files. A test that passes without the fix proves nothing, so send it back.

4. Run the gates yourself. In your terminal, not in Codex’s summary: the full test suite, the type check, and the linter, for example npm test && npm run typecheck && npm run lint.

5. Run a review pass. Use /review in the session, or from the shell:

   codex review --uncommitted

   Fix or disprove each finding that matters. Review Codex’s changes before you commit covers triage and keeping only the good hunks.

If you would rather have Codex run check 3 and show you the output, ask for it explicitly:

Copy-paste prompt: prove the new test is a real test

Prove the test you added is a real oracle. Temporarily revert only your fix in the
source file, keep the test, and run that test: show me the failing output. Then
restore the fix, run the test again, and show it passing. Finally run
`git diff --stat` and confirm that no other test file changed.

Read the failing output yourself. It should fail on the assertion you expect, not on an import error or a typo.

Which Codex surface fits which task?

After the first task, choose the surface by how long the task runs and how you want to review it, not by habit.

Task	Surface	Why
A small fix you want to watch	CLI or IDE extension	Every command and approval is visible as it happens
A multi-file change you may throw away	CLI with --worktree, or the desktop app	A worktree keeps your main checkout clean; deleting it is the undo
Long-running work, or several attempts to compare	Codex cloud	Runs remotely; --attempts gives independent tries to choose from
The same task across many repositories, or in CI	codex exec	Scriptable, with the final report written to a file
A second opinion on a pull request	@codex review on GitHub	Reviews where the team already works; see GitHub integration

What goes wrong on a first Codex task?

Symptom	Likely cause	Recovery
Codex reports a gap you cannot reproduce	The plan was accepted without evidence	Ask for the triggering input as a failing test before any fix; reject a gap it cannot demonstrate
The new test passes with the fix removed	The test does not exercise the defect	Send the “real oracle” prompt above; do not merge until the test fails without the fix
Existing tests changed or disappeared	Codex made the suite pass by weakening it	git restore -- tests/, then repeat rule 3 of the prompt; add “never modify existing tests without asking” to AGENTS.md
Codex runs the wrong test command	No AGENTS.md, or it guessed	Put the exact command in AGENTS.md; start a new session so it loads
A package install or download fails	The sandbox blocks the network by default	That is the sandbox working. Install the dependency yourself, or grant the narrowest access described in error recovery
The diff sprawls across many files	The task was too broad	Discard it (git restore ., or delete the worktree) and re-run with a file limit or a smaller task
Codex repeats the same failing fix	It is looping on one hypothesis	Press Esc to interrupt, then ask for three different hypotheses, each with a check that tells them apart

Caution

Do not reach for --dangerously-bypass-approvals-and-sandbox to get past an approval prompt on a first task. It removes both the approvals and the sandbox, and it is meant only for disposable, network-restricted environments such as a throwaway container.

Where to go next after your first Codex task

Set up AGENTS.md for Codex Give Codex the test command, folder layout, and rules so the next task starts from facts, not guesses.

Review Codex's changes before you commit Triage review findings, keep only the good hunks, and commit on evidence.

Isolated Codex tasks with Git worktrees Run several tasks at once without them touching each other or your main checkout.

Build your first feature with Claude Code The same test-first first task, run in Claude Code: acceptance criteria, plan mode, and review in a fresh context.

Protecting the oracle: checks the agent cannot edit Stop an agent from editing the tests that judge its work.