Your first session with an AI coding agent should be a controlled experiment, not a leap of faith. Give Codex one small, reversible job, watch exactly what it does, and stop before anything reaches production. This walkthrough covers a complete first cycle: read the repository’s rules, establish a clean starting state, request a single bounded change, review the diff, run the checks you already have, and roll back cleanly if needed. Capabilities such as command execution, sandboxing, and approval prompts vary by product surface, plan, model, and administrator policy, so confirm setup details in the official quickstart documentation. For background, start with our Codex overview.
Pick a task that is easy to reverse
Not all first tasks are equal. Choose one that meets all of these criteria:
- Touches one or two files, ideally one unit of behavior
- Has obvious correctness: a typo fix, a rename, a docstring clarification, a missing test
- Lives in a repo with existing tests, or at least a build you can run
- Requires no new dependencies, no schema changes, no secrets, no deployment
Good examples: fixing a misspelled function name, tightening an ambiguous comment, or adding a test for behavior that already works. Poor examples: anything touching authentication, billing, infrastructure, or files without test coverage. If you would hesitate to let a brand-new teammate do it unsupervised, save it for a later session.
Read the rules, then establish a clean baseline
Most repositories document their conventions in a README, a contributing guide, or an agent instruction file such as AGENTS.md if the project provides one. Reading these first means Codex starts from your project’s real standards instead of guesses.
Then confirm the repository is in a known-good state before Codex writes anything:
git status
git switch main
git pull
git switch -c codex-first-task
pytest # or npm test, go test ./..., mvn test — whatever this repo usesIf the baseline already fails, fix or note that first; otherwise you cannot tell Codex’s changes from pre-existing problems. Never run a command you do not recognize—check the README or CI configuration to find the project’s real test command.
Request one bounded change
Vague prompts produce vague diffs. State the task, the scope, what is off-limits, and how to verify. Adapt this template:
Task: Rename the misspelled function `recieve_user_input` to
`receive_user_input` across the repository.
Scope:
- Update the function definition and every call site.
- Do not change behavior, formatting, or any unrelated files.
- Do not install dependencies or edit configuration.
Verification:
- Run the existing test suite and report the result.
- Summarize the diff in two or three sentences.The “do not” lines do real work: they fence the change so the diff stays small enough to review. For more patterns—scope fencing, verification clauses, follow-up prompts—see our guide on writing better prompts for Codex, and cross-check phrasing advice against the official prompting documentation.
Review the diff before running anything new
When Codex finishes, read the diff before accepting or building on it:
git diff --stat # which files changed, and how much
git diff # the changes themselvesWork through this checklist:
- Only the files you expected appear in the diff
- No secrets, tokens, or
.envfiles are present - The change matches the request—no drive-by refactors
- No dependency, build, or CI edits you did not ask for
- Names, comments, and docs updated consistently where relevant
If something is off, discard that file’s changes with git restore path/to/file and re-prompt with narrower wording. If the diff is clean, move on to checks.
Run the existing checks
Trust the project’s checks, not the agent’s summary. Run the same test command you used for the baseline, plus the project’s linter or build if it has one. Compare results against the baseline: the same tests should pass, and any new failure should trace to the change you requested—no others. Depending on configuration, Codex may report that it already ran the tests; verify independently anyway, because execution permissions and sandboxing differ across setups. Read any modified tests closely, too: a test rewritten to match broken behavior is a classic failure mode of AI-generated changes.
Stop before deploy, and know your rollback
For a first task, stop at a local commit. Stage deliberately so you see what you are keeping:
git add -p # review each hunk as you stage it
git commit -m "Rename recieve_user_input to receive_user_input"Do not push, open a pull request, or deploy until you have reviewed the committed result with fresh eyes. Rollback paths, from least to most drastic:
- Uncommitted changes:
git restore .discards them (irreversible for uncommitted work) - One bad local commit:
git revert HEAD, orgit reset --hard HEAD~1on a branch nobody else uses - Unsalvageable branch:
git switch main && git branch -D codex-first-taskand start over
Because you worked on an isolated branch, the worst case is deleting a branch—not repairing a shared repository.
Troubleshooting common first-run problems
| Symptom | Likely cause | First thing to try |
|---|---|---|
| Codex cannot see expected files | Wrong working directory or repo not opened | Confirm the agent runs at the repository root, then restate the paths |
| Tests fail after the change | Baseline was already failing | Re-run tests on a clean checkout and compare failures |
| Diff includes unrelated files | Prompt was too broad | Restore the unrelated files, re-prompt with explicit scope limits |
| Agent pauses to request command approval | Approval or sandbox settings require confirmation | Approve the specific command, or adjust settings per official docs |
| Output ignores project conventions | Repo rules not visible to the agent | Point it to your contributing guide or instruction file and re-run |
Limitations, privacy, and security boundaries
AI coding agents are strong at bounded, verifiable edits and unreliable at tasks without a feedback signal—large redesigns, ambiguous requirements, untested systems. Review every line; the agent’s summary is not a substitute for the diff. On privacy and security: never paste credentials, API keys, or customer data into prompts, and keep secrets out of the repository entirely. How prompts and code are processed depends on the applicable terms and your account’s or organization’s data controls, which administrators may configure differently by plan and region. In a managed environment, check internal policy before connecting an agent to any repository.
FAQ
What makes a task “low-risk”?
Single-file scope, obvious correctness, existing tests, no new dependencies, and no path to production. If a mistake would be caught by your test suite and undone with git restore, it qualifies.
Should I trust Codex when it says the tests pass?
No—verify yourself. Run the project’s own test command on the resulting code and compare against your recorded baseline. Execution environments vary by setup, so independent verification is the only reliable check.
How do I undo everything Codex did?
Uncommitted changes: git restore .. A bad local commit: git revert HEAD, or git reset --hard on your private branch. Worst case, delete the working branch; your default branch stays untouched because you isolated the work first.
Where do I find current, official instructions?
Use the official documentation for setup and quickstart steps, prompting guidance, and code review practices. Features and defaults change over time and can differ by account, plan, and administrator policy, so the official docs outrank any article—including this one.