# Run your first Codex task

URL: https://developertoolkit.ai/en/codex/quick-start/first-task/
Description: Run a first real Codex task end to end: pick a task a test can prove, prompt with acceptance criteria, run it in the CLI or cloud, and verify the diff.

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](/en/codex/quick-start/installation/), 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](/en/codex/quick-start/installation/) and [authentication](/en/codex/quick-start/authentication/) first.

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

   ```bash
   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](/en/codex/quick-start/agents-md/) 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**

```text
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**

```text
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:

   ```bash
   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.1 Sol is Codex's bundled default since codex-cli 0.159.1 (2026-09-29), 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](/en/ecosystem/models/) 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](/en/codex/quick-start/error-recovery/) 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:

```bash
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:

```text
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](/en/codex/quick-start/configuration/) covers both, and [running Codex non-interactively](/en/codex/automate/non-interactive/) 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](/en/codex/build/app-mastery/) 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](/en/codex/quick-start/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](/en/codex/automate/cloud-environments/) walks through the setup. Then start the task from [chatgpt.com/codex](https://chatgpt.com/codex) or from the terminal. `codex cloud` is marked experimental in 0.157.1:

```bash
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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   codex review --uncommitted
   ```

   Fix or disprove each finding that matters. [Review Codex's changes before you commit](/en/codex/quick-start/review-workflow/) 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**

```text
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](/en/codex/quick-start/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](/en/codex/quick-start/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 |

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](/en/codex/quick-start/agents-md/) — 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](/en/codex/quick-start/review-workflow/) — Triage review findings, keep only the good hunks, and commit on evidence.
- [Isolated Codex tasks with Git worktrees](/en/codex/automate/worktrees/) — Run several tasks at once without them touching each other or your main checkout.
- [Build your first feature with Claude Code](/en/claude-code/quick-start/development-workflow/) — 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](/en/workflows/test/protect-the-oracle/) — Stop an agent from editing the tests that judge its work.