Codex · Advanced · Part 5 of 8

Working with Codex day to day: prompts, git, review, and fixing things when they go wrong

Parts 1 to 4 got you installed, safe, and set up with project memory, cost awareness and a feel for the models. This is where the advanced level starts. You can run Codex; now the question is how to get good results from it every day: what to type, how to ship a change with git, how to review it, how to steer when it goes the wrong way, and what to do when something breaks. Everything here follows the official Prompting, Best practices, Worktrees, Code review and Troubleshooting pages, with my own advice marked as such.

1. The four-part prompt

Codex is strong enough to be useful even when your prompt is not perfect. The official Best practices page says so directly. But clear prompts make results more reliable, especially in a big codebase or when the stakes are higher. The page recommends a good default: include four things.

Here is that shape as one prompt (my example, in the style of the docs):

Goal: users who log out and log back in lose their saved filters. Fix it.
Context: start with @src/session/restore.ts and the test in @tests/session.test.ts.
Constraints: do not change the public API; keep the fix minimal.
Done when: a new regression test fails before the fix and passes after, and
the existing session tests still pass.

The same page suggests choosing the reasoning effort to fit the job: low for faster, well-scoped tasks, medium or high for complex changes or debugging, and extra high for long, agentic, reasoning-heavy tasks. As of 18 October 2026 it says to use GPT-6.1 Sol when it is available to your account and client, and to start with High for GPT-6 Luna or Light for GPT-6 Astra (low in configuration). Model lineups change, so check Part 4 and the official Models page before you rely on that.

2. Explore, plan, implement, review, commit

Letting an agent jump straight to code can produce a tidy answer to the wrong question. The official Best practices page says to plan first when the task is complex, ambiguous or hard to describe. Here is the workflow I follow, built from features the docs describe:

For planning, the docs name three options:

• Plan mode. The docs call this the easiest and most effective option for most people. Codex gathers context, asks clarifying questions and builds a stronger plan before it implements anything. Toggle it with /plan or Shift+Tab. In the CLI you can add the first request inline, for example /plan Propose a migration plan for this service. Note that /plan is temporarily unavailable while Codex is already working.
• Ask Codex to interview you (section 6).
• A PLANS.md template for longer, multi-step work. The docs point to an execution-plans guide in the OpenAI Cookbook for this.

The steps as prompts (my wording):

# 1. Explore (read-only questions)
Read @src/auth and explain how sessions and login work.
Also tell me where secrets are loaded from. Do not change anything.

# 2. Plan
/plan I want to add Google sign-in. Which files change, and what is the session flow?

# 3. Implement (after you accept the plan)
Implement the plan. Add tests for the callback handler,
run the test suite, and fix any failures.

# 4. Review
/review

# 5. Commit
Commit this with a descriptive message.

A wrong assumption fixed in the plan costs one sentence. The same assumption fixed after twenty edited files costs a lot more.

3. Prompting patterns that work

The Prompting page says a useful Codex prompt “names the behavior you want, points to the relevant code or reproduction steps, preserves important constraints, and says how to verify the change.” Here is how to turn that into habits.

The Prompting page also advises starting with the result, not a detailed list of steps. Describe a process only when the process itself matters; otherwise leave Codex room to search and adjust its approach.

Give Codex richer context

• Reference files with @. In the CLI, type @ to search for a file in the workspace and add its path to your prompt. /mention src/lib/api.ts attaches a specific file. The IDE extension automatically includes your open files as context; in the CLI you mention paths yourself.
• Attach images. In the CLI, drag an image file into the terminal, or start with codex --image path (short form -i). Useful for design mockups and error screenshots. Add the behavior the image cannot show, such as hover states and validation rules.
• Run a shell command from the prompt. Prefix a line with ! and Codex runs it locally under your current approval and sandbox settings.
• Connect outside systems with MCP when the context lives outside the repo (Part 6).
• Move durable rules out of prompts. The docs list “overloading the prompt with durable rules” as a common mistake. Put those in AGENTS.md (Part 2) or a skill (Part 6).

4. Prompt recipes for everyday tasks

These come from the official Prompting page (its Codex workflows). Adapt the wording to your project.

Notice that each recipe is a short conversation, not one giant prompt. You are not expected to get it perfect the first time: ask, read, refine. The docs also note that Codex does not have to be watched step by step; the Best practices page lists “treating Codex like something you have to watch step by step” as a mistake. Use it in parallel with your own work.

5. Give Codex a way to check its work

The Best practices page puts it plainly: do not stop at asking Codex to make a change. Ask it to create tests when needed, run the relevant checks, confirm the result and review the work before you accept it. Codex can do this loop for you, but only if it knows what “good” looks like. That can come from the prompt or from AGENTS.md.

• Write or update tests for the change.
• Run the right test suites, plus lint, formatting and type checks.
• Confirm the final behavior matches the request, for example by re-running the repro steps.
• Review the diff for bugs, regressions and risky patterns (section 9).
• Ask for evidence, not claims. “Report the commands and results” is a good ending for a prompt.

The docs list “not letting the agent see its work” (no details on how to run build and test commands) as a common mistake. The fix is a few lines in AGENTS.md: your build, test and lint commands, and what “done” means. If you cannot verify a change, do not ship it. That one is my rule, not the docs'.

6. Big feature? Let Codex interview you

If you have a rough idea but are not sure how to describe it, the docs suggest asking Codex to question you first, challenge your assumptions and turn the fuzzy idea into something concrete before writing code. A prompt in that spirit (my wording):

/plan I want to build [brief description]. Interview me first.
Ask about technical choices, edge cases, concerns and tradeoffs.
Challenge my assumptions. Don't ask obvious questions.
When we're done, write a short spec to SPEC.md.

7. Git with Codex: branch, commit, pull request

Codex works inside your git repository, and the desktop app has git actions built in. Here is the flow, and where you stay in charge.

Tips that make this smoother:

• Write your repository etiquette in AGENTS.md (Part 2): branch naming, commit style, PR expectations, build and test commands. The Best practices page lists “PR expectations” among what a good AGENTS.md covers.
• Keep approvals tight. Part 1 covered approvals and the sandbox. The docs advise starting with the default permissions and loosening them only for trusted repos. You can change them mid-session with /permissions.

8. Worktrees and parallel chats

The Best practices page lists “running live tasks on the same files without using Git worktrees” as a common mistake. A git worktree is a second checkout of your repository. Each worktree has its own copy of every file, but they all share the same .git history, so you can work on several branches at once. Codex worktrees let several chats run in the same project without interfering with each other. They only work in projects that are part of a Git repository.

In the desktop app

1. In a new chat, select Worktree under the composer. Optionally pick a local environment to run setup scripts.
2. Choose the starting branch below the composer. It can be main, a feature branch, or your current branch with unstaged changes.
3. Submit your prompt. Codex creates a worktree from that branch. By default it is in a “detached HEAD” state, so it does not pollute your branches.
4. Choose where to keep working: stay on the worktree and select Create branch here, or select Hand off to move the chat and code into your Local checkout.

Think of Local as the foreground and Worktree as the background. A few facts worth knowing:

• One branch, one place. Git allows a branch to be checked out in only one place at a time. If a branch is on a worktree, you cannot also check it out locally. If you plan to check it out locally, use Hand off instead of keeping it in both places.
• Ignored files do not come along. Worktrees start from files checked into Git. For ignored setup files such as .env, add a .worktreeinclude file at the repository root listing the paths or .gitignore-style patterns to copy. It applies to local managed worktrees made by the app, not ones you create yourself from the command line.
• Cleanup. By default Codex keeps your most recent 15 managed worktrees, and you can change that in settings. It will not auto-delete a worktree with a pinned chat, an in-progress chat, or a permanent worktree. Before deleting one, it saves a snapshot and offers to restore it.

In the CLI

The CLI has a --worktree flag (start in a new managed Git worktree; local execution only) and a /worktree slash command, which lets you start a new chat or continue the current one in a new worktree. It is unavailable while a task is running. Parallel chats can also use subagents (Part 6); the rule stays the same: do not let two chats change the same files.

9. Code review: local changes and pull requests

The docs treat review as a first-class part of the loop. There are two different tools, and the Code review page keeps them apart: the built-in /review command reviews changes in your Git checkout, and the Code Review plugin works with pull requests.

Review local changes with /review

Type /review in the CLI, the app composer or the IDE extension. It only appears when the open project is inside a Git repository. Codex starts a dedicated reviewer that reads the diff and reports prioritized, actionable findings without changing your working tree. The CLI presets are:

Apply fixes, then run /review again to confirm they are resolved. By default the review runs in the current chat; the app has a Detached setting under Settings > General > Code review to start a separate review chat, and you can set review_model in config.toml to use a different model for reviews. From a script, codex review runs a non-interactive review with --uncommitted, --base BRANCH or --commit SHA (Part 7).

The app's review pane

The review pane reflects the state of your Git repository, not just what Codex edited. By default it shows Unstaged changes; switch to Staged, Commit, Branch (diff against your base branch) or Last turn (only the most recent assistant turn). To leave line-specific feedback, hover a line, select +, write your comment, and then send a message to the chat. The docs advise making your intent explicit, for example “Address the inline comments and keep the scope minimal.” The pane requires a project inside a Git repository.

Review a pull request

• In the app: open Code Review from the sidebar, connect your source account, and select a pull request or paste its link. Summary shows the description, activity, comments and checks. Changes shows the diff with comments. Select Review with Codex to start a review in a new chat. You can also ask questions such as Walk me through this pull request. Focus on the default filter and what happens when there are no matching issues. and then Show me the code path and tests for the no-matches case.
• Your team's rules: select the Review instructions gear or edit Settings > Code Review to give criteria and a reporting format that apply to your reviews.
• On GitHub itself: comment @codex review on a pull request. Codex reacts and posts a standard GitHub review that flags only P0 and P1 issues. You can add focus, such as @codex review for security vulnerabilities and security concerns. This needs Codex code review enabled for the repository, and automatic reviews can be turned on in Codex settings. Add a ## Code Review Rules section to the closest AGENTS.md to steer what it checks.

10. Steering, queueing and long-running work

You do not have to wait for Codex to finish before you speak. The Prompting page describes two behaviors for a message you send while Codex is working:

Other keys from the CLI reference worth knowing: press Escape twice with an empty composer to edit your previous message and fork the chat from that point; Up and Down restore draft history; Ctrl+R searches prompt history; Ctrl+O (or /copy) copies the latest finished output; Ctrl+C or /exit closes the session. If background commands are running, /ps lists them and /stop stops them. I did not find a documented shortcut that only interrupts the current turn, so check /keymap and the shortcut list for your version.

Long-running work with /goal

For work that may take many steps, give Codex a clear outcome, constraints and a definition of done, and keep related work in one chat. Type /goal in the CLI, the desktop app or the IDE extension. The goal text becomes both the first prompt and the completion criteria. In the CLI:

/goal Migrate this codebase from JavaScript to TypeScript. Preserve existing
behavior, compile in strict mode without explicit `any` types, and make the
full test suite pass.

/goal            (view the current goal)
/goal edit       (revise it)
/goal pause      (pause)   /goal resume   /goal clear

The docs say a good goal has three elements: an outcome (the result, not just the activity), constraints (tools, boundaries, things to avoid) and verification (tests, measurements or review criteria that prove it is done). Goal text must be non-empty and at most 4,000 characters; for longer instructions, put them in a file and point the goal at it. Starting a goal does not grant broader access: the same sandbox and approval policy apply, and it pauses when it needs a decision. For local work, turn on Prevent sleep while running in settings so your Mac stays awake.

11. Projects, chats and resuming

The Best practices page says to keep one chat per coherent unit of work, and lists “using one chat for an entire project” as a mistake because it bloats context. If the work is still the same problem, staying in the same chat preserves the reasoning trail. Fork only when the work truly branches.

• Projects in the app. The Projects view holds local projects that connect to folders on your computer. A project can have several folders; the primary folder is where new chats start, and where Codex finds AGENTS.md, skills and config.toml. Start a separate chat for each distinct outcome. You can pin, rename, search and archive chats.
• Projects in the CLI. The directory where you start Codex is the project. Run codex from the folder you want, or pass --cd (-C).
• Resume a saved chat. Run codex resume for a picker, codex resume --last for the most recent chat from the current directory (add --all to include other directories), or codex resume SESSION_ID. Inside the CLI, use /resume. If the saved directory differs from yours, Codex asks which to use; tui.resume_cwd can remember the answer.
• Fork. /fork (or codex fork) creates a new chat while preserving the original transcript.
• New chat. /new starts a fresh chat in the same CLI session; /clear clears the terminal and starts a new chat too.
• Check state. /status shows the active model, approval policy, writable roots and token usage.

The chat keeps its transcript and recorded working directory, but Codex reads files from the current working tree. So keep durable guidance in AGENTS.md or checked-in docs, not only in a chat.

12. When something goes wrong

Install and login problems were covered in Part 1. These are the problems you can hit once Codex is running. They come from the official Troubleshooting page unless I say otherwise. First, the general stuck-chat routine from that page: (1) check whether Codex is waiting for an approval, (2) open the terminal and run a basic command like git status, (3) start a new chat with a smaller, more focused prompt.

13. Wrap-up, glossary and links

1. Write prompts with a goal, context, constraints and a “done when”.
2. Plan first (/plan) unless the change is one sentence.
3. Always give Codex a check to run, and review with /review and /diff before you commit.
4. Use worktrees so parallel chats never edit the same files.
5. Steer with Enter, queue with Tab, and use /goal for long work.
6. One chat per outcome; when stuck, check approvals and git status, then start fresh.

Next, Part 6 extends Codex: connecting outside tools with MCP, skills, plugins and subagents, and choosing between the CLI, IDE extension and desktop app. If you want to revisit models and plans first, that was Part 4.

Links and official docs

• Prompting
• Best practices
• Slash commands in Codex CLI
• CLI command reference
• Worktrees
• Code review
• Use Codex in GitHub
• Long-running work
• Projects and chats
• Troubleshooting