Build with Codex on Windows

Set up your Windows tools

Start with tools that let you run commands, edit files, and save changes. If you have already followed the Windows Setup Guide, check the versions below and move on to chapter 2.

For the Windows 11 workflow in this guide, use:

• Windows Terminal: The window where you type commands. Choose PowerShell 7 as its default profile.
• PowerShell 7: The shell that runs your commands. It installs alongside the older Windows PowerShell that comes with Windows.
• Git for Windows: Records versions of your files so you can review changes and return to a saved point.
• A way to use Codex: Choose the VS Code extension, Codex in the desktop app, or the Codex CLI in your terminal. You only need one to start.

# Install PowerShell 7 and Git via winget
winget install --id Microsoft.PowerShell --source winget
winget install --id Git.Git -e --source winget

Run those installation commands only for tools you need. Then close and reopen Windows Terminal. Run pwsh --version and git --version; each should print a version number, with PowerShell showing version 7. The Git setup steps cover your commit name, email, and line-ending settings.

Open the main project folder

A repository is a project tracked by Git. Its root is the top-level folder, usually where you find the README, .git, and setup files. Open this folder in your editor or Codex so the starting location matches the project you want to work on.

cd "C:/Projects/StoreApp/src/api"
codex

cd "C:/Projects/StoreApp"
codex
# Target files via relative paths: src/api/auth.ts

Check your location: In a Git repository, run git rev-parse --show-toplevel to see its root folder. The codex examples assume the CLI is installed; in the desktop app or VS Code, open the same folder through the interface.

Save project instructions in AGENTS.md

Use AGENTS.md for instructions you want Codex to reuse, such as how to run tests, which folders matter, and which conventions to follow. Keep it short and specific to your project.

Save the file as AGENTS.md in your project root. Codex reads these instructions when it starts; files closer to its working directory can add or override project guidance. See the official AGENTS.md guide for details.

Use the template: Copy or download it below, adapt the rules, and add your project’s actual setup and test commands. If an AGENTS.md already exists, edit it instead of replacing it. After saving, start a new Codex session and ask it to summarize the project instructions.

# AGENTS.md - Project Instructions

## 1. Project Overview
Read the README for setup steps and the purpose of this project.
Follow the existing code structure and naming conventions.

## 2. General Principles
- Read the relevant files before editing them.
- Preserve useful comments, types, and documentation.
- Keep existing behavior unless the task asks you to change it.
- Complete the requested feature; do not present placeholder behavior as finished.
- Reuse existing dependencies when they meet the need.

## 3. Windows Environment Rules
- Use forward slashes (/) in prompts and cross-platform paths.
- Save text files as UTF-8 with LF line endings.
- Use PowerShell 7+ for the commands in this project.

## 4. Verification Requirements
- Use the setup, test, lint, and build commands documented in this repository.
- Run the checks relevant to the change and any required project checks.
- Review the changes for mistakes and unrelated edits.
- Report commands run, results, and checks you could not complete.
- Describe any manual checks still needed.

## 5. Completion Standard
End each task with:
1. What changed and why
2. Files created or modified
3. Checks run and their results
4. Known limitations or remaining work

Describe the result you want

Explain what you want people to be able to do after the change. Add the relevant file or screen, any limits, and a way to tell whether it works. A few clear sentences are often enough.

If you are unsure how to describe the task, ask Codex to inspect the project and help you define it. The official best practices guide has more advice on task context and planning.

"Make my dashboard responsive and clean up the header."

Improve the dashboard header in src/components/Header.vue.

- At widths below 768px, put navigation in a menu that opens and closes.
- Keep search and the existing links working.
- Make the menu usable with a keyboard and expose its open state to screen readers.
- Check widths of 375, 768, 1280, and 1920px.
- Keep the rest of the dashboard unchanged.

Read the component and its styles first, then make the change.
Report what you changed and how you checked it.

Break larger tasks into smaller steps

For a larger feature, agree on a short sequence of steps. Check each part as it becomes usable. This makes it easier to spot problems and change direction without redoing the whole feature.

For example, a new profile form might follow these steps:

1. Define the data: Agree on the profile fields and validation rules. Check that the data definitions fit the project.
2. Build the behavior: Add saving and validation, then test valid and invalid input.
3. Connect the screen: Build the form and its loading, success, and error messages. Try it as a user.
4. Review and save: Run the required checks, inspect the changes, and commit the working result.

A small text edit or simple fix may only need one step. Match the amount of planning to the size of the task.

Ask Codex to investigate first

When a bug is unclear or a change affects several parts of the project, ask Codex to inspect the code and explain what it finds before editing. If you want to review the plan first, say so explicitly. For a straightforward task, you can ask it to inspect and then proceed.

Investigate why the app keeps redirecting to sign-in after a session expires.
Do not change files yet.

1. Read src/auth/session.ts and src/api/client.ts.
2. Follow what happens when the server returns HTTP 401 (unauthorized).
3. Explain the likely cause, with the relevant file locations.
4. Say what evidence is missing if you cannot confirm the cause.
5. Propose a fix and a way to test it. Wait for me to review the plan.

Check the result with tests

Ask Codex to run checks that show the requested behavior works. A useful completion report names the commands it ran, their results, and anything it could not test. A summary alone does not show whether a test was executed.

Use the commands your project documents. These are examples for different toolchains; you do not need to run or install all of them:

• Tests check behavior: Examples include npm test, pytest, cargo test, and dotnet test.
• Type checks find incompatible values: Use the project’s configured TypeScript or Python type-check command, if it has one.
• Lint and formatting checks catch common mistakes: Examples include npm run lint and ruff check ..
• A build checks that the app can be packaged: For projects with a build script, this might be npm run build. Exit code 0 means the command succeeded.

Try asking: “Run the checks relevant to this change. List each command and its result. If a check fails or cannot run, explain why. Tell me what still needs a manual check.” For a bug fix, include a check that reproduces the original problem and confirms it is resolved.

Save and review your work with Git

A Git commit is a saved version of your tracked files. Before a substantial change, review and commit the work you want to keep. After Codex finishes, use the diff—the line-by-line list of changes—to decide what to accept.

# 1. Check what has already changed
git status
git diff
git diff --staged

# 2. Stage only the files you reviewed (replace this example path)
git add -- "src/profile.ts"
git diff --staged

# 3. Save the reviewed changes
git commit -m "checkpoint: before profile validation"

# 4. After Codex completes the task, review its changes
git status
git diff
git diff --staged

Run these commands from your project root and review the output at each step. git status includes untracked files; open those separately because git diff does not show their contents. If there is nothing to commit, your current commit is already the checkpoint.

If a change needs undoing: Follow the recovery steps in chapter 12. Save work you want to keep before discarding anything.

Set clear limits for the task

Tell Codex which task it can complete and which actions need your involvement. For example, you can allow it to edit a feature and run local tests while reserving deployment or changes to live data for a separate decision.

A practical task brief can cover three things:

• Work it can do: Read relevant files, make the requested edits, and run the project’s local checks using test data.
• Limits to follow: Name any files, dependencies, or behavior that should stay unchanged.
• Actions to confirm: State whether it may publish, push commits, install dependencies, or change shared services. Be specific about what is already authorized.

Example: “Fix profile validation and run the local tests. Keep the public API unchanged. Do not deploy or change the shared database.” Start with Codex’s default permissions; written instructions describe your intent, while sandbox and approval settings control tool access.

Give Codex the details of the bug

Describe what you saw and how to reproduce it. You can share a suspected cause, but label it as a guess so Codex can check it against the code.

Include the steps you took, what you expected, what happened instead, and the error message or stack trace. Add relevant versions, such as the browser or runtime, and remove passwords, access tokens, and personal data from logs before sharing them.

The profile form saves twice when I double-click Save.

Steps: Open the profile, change the display name, then double-click Save.
Expected: One save request and one success message.
Actual: Two save requests appear in the browser Network panel.

Inspect the form and save handler, reproduce the issue, and fix its cause.
Add or update a test for repeated clicks. Report the result.

Test web changes in a browser

For a web change, open the page and try the behavior that changed. A successful build will not tell you whether a menu is cut off, a button can be reached with the keyboard, or a form shows a useful error.

Start the project using its README instructions, then resize the browser or use its responsive tools to check widths of 375px, 768px, 1280px, and 1920px. At each size:

• Check that text is readable and content is not clipped or pushed off-screen.
• Open menus, follow links, and submit forms with both valid and invalid values.
• Use Tab and Shift+Tab to move through controls. Check that focus is visible, and try Enter, Space, and Escape where appropriate.
• Check the browser Console and Network panels for errors and failed requests.

If Codex has browser tools available, ask it to perform these checks and report the widths and behaviors tested. If it cannot access a browser, have it list the checks for you to run.

Recover when a fix does not work

If a fix does not work, report the new result and ask Codex to compare it with the original problem. When repeated attempts stop making progress, pause the edits and review what has been learned.

If you choose to discard changes, use your editor’s diff view to select the specific edits. For a tracked file, git restore --source=HEAD --worktree -- "src/profile.ts" replaces its working copy with the last committed version. This discards all uncommitted edits in that working copy, including your own; any staged changes remain ready to commit. Replace the example path only after reviewing and saving the file. See Git’s restore documentation.

If you start a new Codex chat, carry over the goal, current error, checks already run, and approaches that failed. That gives the next attempt a useful starting point.

Keep project instructions up to date

When a task changes how the project is installed, run, tested, or used, update the relevant instructions in the same task. This helps you and future contributors follow the working setup.

Use README.md for setup and usage, AGENTS.md for recurring coding instructions, and API or design notes for changes to interfaces and structure. Ask Codex to check the examples it changes. A small edit that leaves these instructions accurate may need no documentation update.

Use more than one agent when it helps

Start with one agent. For a larger task, multiple agents can help when their jobs are independent—for example, one reviews accessibility while another reviews tests. Give each agent a clear goal and a specific area to inspect or change.

If agents need to edit files at the same time, give them separate working folders, such as Git worktrees. A worktree lets you check out a branch in another folder. Different branch names alone do not separate files in a shared working folder. Review and test the combined result after bringing changes together.

Ask for a focused review

Tell Codex what you want a review to focus on and what evidence to return. For example, ask for file locations, the impact of each issue, and a suggested fix. Useful review angles include:

• Structure: “Review how data moves through this feature. Point out code that is hard to understand or change.”
• Security: “Review input handling, secrets, and permission checks. Explain how each issue could affect a user.”
• Testing: “Look for missing checks around empty input, repeated clicks, failed requests, and timeouts.”
• Performance: “Find likely slow operations and explain how to measure them before changing the code.”

Add “Review only; do not edit files” when you want findings first. You can adapt more examples from the Prompt Library.

Agree on what “done” means

Tell Codex how you will decide the task is complete. Use the checklist below as a starting point, then adjust it to the project and the size of the change. Passing checks gives you evidence to review; it cannot guarantee that every possible defect has been found.

Before finishing this task:
1. Check that the requested behavior works.
2. Review the changes for unintended effects on existing behavior.
3. Finish the requested work; identify anything still incomplete.
4. Check relevant error cases and invalid input.
5. Run the project's required checks and the tests relevant to this change.
6. Run the build and type checks if this project requires them.
7. For UI changes, check the result in a browser and with the keyboard.
8. Review relevant input, secret, and permission handling.
9. Review git status, unstaged and staged diffs, and any new files.
10. Update instructions or examples affected by the change.

Report:
- What changed and why
- Files created or modified
- Commands run and their results
- Manual checks completed
- Checks not run, known limitations, or remaining work

Do not describe a check as passed if it was not run.
Separate existing failures from failures caused by this change.