What this covers
Codex is OpenAI’s “spin off a task, walk away, come back to a PR” coding agent. It runs in a sandboxed cloud environment with its own copy of your repo, which makes it great for parallel work but creates a new class of bugs around environment drift, missing secrets, and over-eager merges. This guide walks through setup, the actual task-spec format that produces reviewable PRs, and the mistakes that bite first-time users in the first week.
Who this is for
Developers who want cloud-side agentic tasks: refactors, dependency upgrades, test-writing sweeps, audit passes, anything that does not need to be co-located with your local machine. Especially useful for solo developers tired of context-switching, and for teams that want a hands-off pre-PR pass.
When to reach for it
Long-running edits that do not need to be co-located with your machine: a 30-file refactor, a dependency upgrade, a test-coverage sweep, a documentation pass. Codex is also a good fit for a full-repo sweep like auditing a React Native project with AI. Reach for Cursor or Claude Code instead when you want to watch the edits land in real time.
When this is NOT the right tool
Tasks where you need to see partial output and intervene, tight feedback loops, anything requiring secrets that the sandbox cannot access, and one-line tweaks where setup cost exceeds the savings.
Before you start
- Verify your repo’s CI passes on
main. Codex inherits the failing baseline if you start dirty. - Document the build/test commands in a README or AGENTS.md the sandbox can read. Codex needs to know how to run your tests.
- Set up the appropriate secrets for the sandbox if your tests need them (most public-facing tasks do not).
- Decide your branch naming and PR conventions so the agent’s output fits your workflow.
Step by step
- Sign in and connect your repo. If you do not yet know the codebase well, run a quick AI codebase tour first so your task spec uses real names and not guesses.
- Create a task with explicit acceptance criteria. A concrete starter task: use Codex to review your sitemap. Format the spec like a bug ticket plus a test:
Goal: Replace deprecated `request.json()` calls with `await request.json()` in `src/api/`.
Constraints:
- Do not modify any file outside `src/api/`.
- Preserve existing error-handling patterns.
- Use the project's existing async style (look at `src/api/auth.ts` for reference).
Acceptance:
- All existing tests pass.
- New test in `src/api/__tests__/json-parse.test.ts` covers the new behavior.
- No console warnings during `npm test`.- Let Codex work. It will spin a sandbox, branch, edit, run tests, and open a PR. Typical small tasks take 5-15 minutes; full-repo sweeps run 30-60.
- Review the PR like any human PR. Read every changed file. Check the test that proves the change. Run the branch locally to be sure.
- Iterate via PR comments. Codex reads comments and pushes follow-up commits. Use this for small corrections, not for rewriting the goal.
- Merge when satisfied. If you find a missed case after merge, file a new task — do not push a follow-up commit to the agent’s branch after merge.
First-run exercise
- Pick a low-stakes refactor you have been putting off — renaming a function, updating an old API call, adding a missing prop type.
- Write the task spec using the goal + constraints + acceptance format above. Do not skip acceptance.
- Run the task. Walk away for 15 minutes. Come back and review the PR cold.
- Note what the spec missed. The gap is almost always too few constraints, not too few words.
Quality check
- Did Codex respect the “do not modify outside X” constraints? Diff line counts catch this quickly.
- Did all tests pass, including ones you did not specifically mention? Look for skipped tests in the CI log.
- Did the agent introduce any “helpful” extras you did not ask for? Bonus refactors are a common failure mode and should be reverted.
- Is the PR description accurate? Codex sometimes overstates what it did. Read code, not summaries.
How to reuse this workflow
- Save task specs as templates per task type — refactor, upgrade, test-coverage, documentation. Same template, different scope each week.
- Keep an
AGENTS.mdin your repo root with build commands, test commands, coding conventions, and “never do this” rules. Codex reads it. - Log every task that produced a clean PR and every one that did not. The patterns tell you what to constrain harder next time.
- Re-test setup quarterly. Sandbox limits, secret handling, and PR conventions all evolve.
Recommended workflow
Pick task → write goal + constraints + acceptance spec → run → walk away → review PR cold → iterate via PR comments → merge or close.
Common mistakes
- Vague task descriptions like “fix the login bug.” The agent will pick a fix. It may not match your intent.
- No acceptance criteria. Without a concrete “done” test, the agent’s idea of done is not yours.
- Skipping the codebase tour for an unfamiliar repo. The spec uses real names; without them, the agent guesses and the guesses are wrong.
- Treating the PR as production-ready without review. Codex output is “PR-quality first draft,” not “merge without reading.”
- Letting Codex modify CI config or secrets handling. Scope those out explicitly in constraints.
- Running tasks in parallel on related files. Two agents touching adjacent code will conflict in unfun ways.
FAQ
- Does Codex have access to my private repos?: On supported plans, yes, via the connection step. Review the permissions before granting.
- Can it run my full test suite?: Yes, in the sandbox. Make sure dependencies install cleanly with the documented commands.
- What happens if the task fails partway?: Codex usually opens a PR with whatever it did and a note about the failure. Read the failure log, refine the spec, re-run.
- How is this different from Claude Code or Cursor?: Codex is async cloud; Cursor and Claude Code are interactive. Pick async for parallel work, interactive for tight feedback loops.
Related
Tags: #AI coding #Tutorial #Codex