OpenAI Codex: A Practical Guide for Developers

OpenAI Codex is a software-development agent: it can inspect a repository, plan a change, edit files, run commands, test the result, and review its own diff. The useful mental model is not “a chatbot that writes code snippets,” but a teammate operating inside a bounded development environment.

Codex is available through several surfaces. The CLI is terminal-first; the IDE extension stays close to the editor; the desktop app is suited to planning, review, and concurrent work; cloud tasks move execution to a hosted environment. The interface changes, but the core loop does not: give Codex a goal and enough context, let it work, then inspect evidence that the outcome is correct.

Choose the surface around the work

This is not a permanent choice. A task can begin as a plan in the app, move into a local implementation, and finish with review in the IDE. What matters is that the environment has the code, dependencies, permissions, and verification commands the task needs.

Write a task Codex can finish

The most reliable prompt has four parts:

1. Goal — the observable outcome, not a vague activity.
2. Context — the files, errors, examples, issue, or existing behavior that matters.
3. Constraints — compatibility, architecture, safety, scope, and things that must not change.
4. Done when — tests, behavior, or checks that prove the work is complete.

Add retry handling to the billing API client.
 
Context: src/billing/client.ts and its Vitest suite. Requests currently fail
immediately on a transient 429.
 
Constraints: preserve the public method signatures, retry only 429 and 5xx,
cap the delay, and do not add a dependency.
 
Done when: the focused tests cover success, retry, and non-retryable failure;
then run typecheck and review the final diff for unrelated changes.

That prompt gives the agent room to investigate while making the finish line hard to misunderstand. For a difficult or ambiguous change, start in Plan mode or explicitly ask for a plan before implementation. Planning is most valuable when the cost of choosing the wrong direction is much larger than the cost of reading a short design first.

Put each kind of instruction in the right place

Codex has several customization layers, and reliability improves when each carries one kind of information:

• Prompt — requirements that belong only to this task.
• AGENTS.md — durable repository conventions, commands, boundaries, and definitions of done.
• Skill — a reusable workflow Codex should recognize and follow for a recurring job.
• .codex/config.toml — operational settings such as sandboxing, approvals, model defaults, and MCP servers.
• MCP — live context or controlled actions in systems outside the repository.

Do not paste your entire engineering handbook into every request. Put the stable minimum in AGENTS.md, link to deeper reference files when necessary, and keep the task prompt about the task.

Use a closed-loop workflow

The productive Codex loop has five steps:

1. Orient. Ask it to inspect the relevant code and existing conventions before editing.
2. Plan when needed. Review the proposed approach for cross-cutting or high-risk work.
3. Implement. Let it make the smallest cohesive change that reaches the goal.
4. Verify. Run focused tests first, then the broader lint, type, build, or integration checks appropriate to the risk.
5. Review. Read the diff for unintended scope, weak error handling, missing tests, and behavior that the checks did not exercise.

“Code written” is not a useful stopping condition. “The behavior changed, the regression test passes, the repository checks are green, and the diff contains no unrelated edits” is.

Keep the execution boundary deliberate

Codex separates what it is technically allowed to do from when it must ask. Sandbox settings bound filesystem and network access; approval settings govern interruptions for actions outside the normal boundary. Begin with workspace-scoped access on repositories you know, and use read-only work when you only need analysis or a plan.

Broader access is sometimes necessary — installing packages, reaching a remote API, or working across directories — but it should follow from the task. Treat external content as untrusted, keep secrets out of prompts and logs, and use version control so every edit is inspectable and recoverable.

A useful first week

Start with tasks whose results are easy to inspect: add a focused test, explain an unfamiliar module, fix a reproducible bug, or refactor a small boundary without changing behavior. Once that loop is predictable, encode repeated corrections in AGENTS.md, turn recurring procedures into skills, and connect outside systems through MCP only when they remove a real copy-and-paste workflow.

The goal is not maximum autonomy. It is a system where you can state an outcome, let the agent work inside a clear boundary, and decide whether to accept the result from evidence rather than optimism.

Official references: Codex best practices, Codex CLI, and agent approvals and security.