Your first Codex task should not be the most ambitious feature you can imagine. It should teach you a workflow you can understand, verify, and reverse if necessary. This tutorial uses the desktop app as the example surface. You will begin with read-only exploration, then move to one focused, low-risk change.
By the end, you should be able to answer five questions: Which project is Codex working in? What does it plan to change? Which files did it actually change? Which checks did it run? What remains unverified?
Before you start
Choose a local practice project that meets these conditions:
- It uses Git, and there are no unexplained uncommitted changes.
- You roughly know what the working project should look like.
- It has a README or another source of setup instructions.
- The task does not involve production data, payments, secrets, account permissions, or deployment.
- You can run the checks the project already defines.
If the working tree already contains changes, identify who made them and whether they must be kept. Do not mistake a pre-existing dirty working tree for changes Codex just created.
Step 1: Open the correct project
After installing and signing in to the ChatGPT desktop app, choose Codex and open the folder or project you want to work on. OpenAI’s current Quickstart notes that the app can read and modify files in the folder you select, so choosing the folder is itself part of the permission boundary.
Do not request a change yet. Ask Codex to confirm the environment:
Read this project without modifying any files. Explain its purpose, main directories, startup command, and validation commands. List the files you actually inspected, and state what you could not verify instead of guessing.
Check the answer against the README, package.json, or other project configuration. If the directory or commands are wrong, correct the context before moving on.
Step 2: Choose a low-risk first task
A good first change is small, obvious, and easy to undo. For example:
- Fix a real typo.
- Add a missing accessible name to an existing button.
- Improve an existing error message without changing business logic.
- Add a test for one clear edge case in an existing pure function.
Do not begin by upgrading every dependency, refactoring the core architecture, migrating a database, or deploying to production. The larger the task, the harder it becomes to tell whether a problem came from the requirement, context, implementation, or environment.
Step 3: Write an acceptance-ready task
OpenAI’s best-practices guide recommends giving Codex a goal, context, constraints, and a definition of done. You can use this template:
Goal: Fix the typo in the empty-state message on the settings page.
Context: Read the project rules and the settings-page component first. Do not change other pages.
Constraints: Keep the current component structure, styles, and translation keys. Do not install dependencies or add features.
Done when: Only necessary files change; run the relevant formatting and type checks; finish with a list of changes, check results, and checks you did not run.“Do not install dependencies” and “only change necessary files” are not universal rules. They are useful for a first exercise because they reduce unexpected scope.
Step 4: Review the plan before editing
For an unfamiliar repository or a multi-step task, ask Codex to propose a plan first: which files it will inspect, where it expects to make changes, and how it will validate the result. Review three things:
- Does the plan point to the correct files and feature?
- Does it introduce unrelated refactors, dependencies, or configuration changes?
- Do the proposed validation commands really exist and fit the change?
A one-line copy fix does not need an elaborate process. But if the plan expands beyond your expectation, narrow it before any files change.
Step 5: Inspect changes and commands
While Codex works, pay attention to the files it reads, the edits it makes, and the commands it wants to run. Do not rely only on the final summary. Review the diff in this order:
- File scope: Did it touch only the files the task requires?
- Content scope: Did it preserve the project’s structure, naming, and conventions?
- Unexpected deletion: Did it remove comments, tests, translations, or earlier user work?
- Sensitive content: Did a secret, personal record, or local path enter the code?
- Reversibility: Is the Git diff clear enough to restore only this task’s changes?
If a command needs higher privileges, network access, or files outside the project, understand the reason and target before approving it.
Step 6: Run real validation
Do not treat “looks correct” as acceptance. Ask Codex to run the checks the project actually uses, such as formatting, linting, type checks, unit tests, or a build. OpenAI’s best-practices guide likewise recommends asking Codex to add tests when needed, run relevant checks, confirm the result, and review the work.
The report should distinguish among:
- a check that ran and passed;
- a check that ran and failed, including whether the failure relates to this change;
- a check that did not run because of time, permissions, or environment;
- a check the project does not provide.
“Not run” can be an honest outcome, but it cannot be reported as “passed.” If a check fails, investigate the cause before asking Codex to bypass or remove it.
Step 7: Complete the final review
Use a short checklist before committing:
- The requested behavior changed.
- The diff contains only expected files.
- The user’s earlier changes are still present.
- Relevant checks have real, readable results.
- No secrets, personal information, or temporary files entered Git.
- Nothing unverified is described as complete.
- You can explain and accept every change.
If any item remains uncertain, keep reviewing or reduce the scope instead of rushing to commit.
A complete first-task example
Suppose the README is missing the test command, but package.json already defines it. You could ask:
Read AGENTS.md, README.md, and package.json first. Confirm the real test command, then add that command only to the README development section. Do not change scripts or dependencies. Run the documentation formatting check if the project has one, show the final diff, and state which checks you did not run.This request makes Codex verify the command against an authoritative file and limits the edit to one document. It is much easier to review than “optimize my project,” which makes it a better first exercise.
If you still need the product overview, read What is Codex?. If you would rather work in a terminal, continue with the Codex CLI installation guide.
Frequently asked questions
Does my first task need to change code?
No. Explaining the project, mapping its startup flow, or locating relevant files is often a better first step. Confirm that Codex understands the environment before asking it to edit anything.
Does a prompt need to be long?
No. The goal, relevant context, constraints, and definition of done matter more than length. A small task can use a short prompt and still remain easy to verify.
Codex says the tests passed. Should I inspect the output?
Yes. Confirm that it ran the right command for the project, and check the exit status, failure count, and skipped items. A summary does not replace the actual result.
What if Codex changes the wrong file?
Stop the task from expanding, inspect the Git diff, and identify which edits belong to this task. Restore only the clearly unwanted changes from this task; do not overwrite the user’s earlier work.
When should I try a larger task?
Increase the scope after you can reliably confirm the directory, permissions, diff, and validation results, and after the project has clear rules and tests. Plan complex work first and add checkpoints.