How to Use OpenAI Codex: CLI Setup, Bug Fixing, Tests, and Code Review

Generating a function is different from modifying a working repository. A reliable coding workflow also needs reproducible failures, bounded changes, tests, and diff inspection. OpenAI Codex is a coding agent designed to work within development environments.

This hands-on guide covers Codex CLI setup, a deliberately broken Python project, AGENTS.md instructions, a targeted bug-fixing prompt, regression tests, and code review.

An original conceptual workflow diagram, not a screenshot of a Codex execution.

Documentation checked: November 4, 2026. The Python example was tested separately with Python 3.13.5: three of four initial tests failed, and all four passed after applying the reference fix. The autonomous Codex workflow itself was not run.

1. What makes Codex different from regular AI chat?

Traditional AI chat can analyze the snippets you provide or draft code for you to copy into a project. With the appropriate permissions, Codex can explore repository files, apply edits, run development commands, and present changes for inspection.

Codex is not guaranteed to produce correct code. The key is to define what it may change and how its work will be verified.

2. Choose an environment and install Codex CLI

Codex is available through its CLI, IDE integrations, desktop Codex mode, and cloud-based workflows. A terminal-first environment makes commands and code changes easy to observe. IDE integration is useful when you want to work directly alongside open files.

Codex is included across ChatGPT plans, including Free and Go, with different usage limits. Codex Cloud has separate eligibility requirements and is not included with Free or Go. Consult the current ChatGPT plan availability.

Prerequisites

You'll need Git, Python 3, and a ChatGPT account. Node.js and npm are required only if you use the npm installation method. The practice commands below target macOS, Linux, or WSL2 shells.

Installation

Install via npm:

Alternatively, use the standalone installer.

macOS / Linux:

Windows PowerShell:

Review installer scripts before executing them, especially on managed workstations. These installation options are listed in the official Codex repository.

Start Codex from your project directory:

Follow the sign-in flow for your ChatGPT account. API-key authentication is also supported, but API billing should not be confused with subscription usage.

Useful interactive commands include:

Enter these inside the Codex interactive composer, not a regular shell. Features may differ between installed versions. The current list is in the developer commands documentation.

3. Create a small Python project with a real bug

We'll build a function that calculates exponential backoff delays. This is a pure calculation example; it does not perform network requests.

Our specification is:

Attempts start at one, and an attempt below one must raise ValueError.

Create a fresh repository:

Write the buggy implementation

Create retry.py:

The function uses a one-based attempt number directly as the exponent. The first delay is therefore 1.0 second rather than the required 0.5 seconds. It also accepts zero instead of raising an error.

Write regression tests

Create test_retry.py:

Create a .gitignore file so Python bytecode caches don't clutter the working tree:

Run the tests:

The initial fixture was executed with Python 3.13.5. Three of four tests failed: the first attempt, the second attempt, and invalid attempt zero. The capped-delay test passed.

This failing test suite gives us a reproducible starting point instead of a vague complaint about broken code.

4. Add repository instructions with AGENTS.md

Codex recognizes an optional AGENTS.md file that describes how work should be performed in a repository. Put the testing command and important constraints in this file rather than repeating them in every prompt.

Create AGENTS.md in the project root:

Codex can also discover relevant instructions in nested directories. These files guide agent behavior; they are not filesystem or network security controls. For those, use the sandbox and approval settings. Read the AGENTS.md documentation for discovery rules.

Save the baseline in Git:

This commit intentionally includes failing tests so we can inspect the resulting patch later. Git needs a configured author identity to create the commit.

5. Ask Codex for a bounded bug fix

Run codex from the project root. Then submit this task:

This prompt provides the observed failure, behavioral requirements, scope restrictions, and an objective acceptance criterion.

With a suitable environment and permissions, Codex can explore the relevant files, implement the fix, execute the test suite, and report its actions. Inspect your own session logs and diff rather than assuming that an agent's success message proves correctness.

Reference implementation

A correct fix may look like this:

Subtracting one from the exponent aligns the calculation with one-based attempt numbering. The guard rejects invalid values.

This reference solution was run independently on Python 3.13.5 and passed all four tests. It is not a captured Codex-generated patch.

6. Inspect the diff and verify the result

After Codex finishes, inspect your local working tree:

Check whether only retry.py changed. Ensure that the agent did not modify tests to hide failures, introduce dependencies, or perform unrelated refactoring.

The interactive Codex interface provides /diff and /review. From a normal terminal, you can ask for a review of uncommitted changes:

According to the command reference, this review target includes staged, unstaged, and untracked changes.

A review can surface missed bugs, but it does not replace tests, security checks, or human judgment. Passing these four tests establishes only the behavior that these tests assert.

7. Use Codex in VS Code or in the cloud

If you prefer an IDE workflow, install the Codex extension in VS Code and sign in. With retry.py open, you could ask:

The IDE experience makes it convenient to inspect code, prompts, and resulting diffs in one editing environment. See the Codex IDE documentation.

For cloud tasks, open Codex, connect an eligible repository, and prepare an environment with the required tools and permissions. Review the cloud execution logs and diff before applying the result. Cloud environments may need separate dependency and credential configuration. See Using Codex Cloud.

8. Practical safeguards for production development

• Start with the smallest permissions needed. Avoid disabling sandbox and approval safeguards just to finish a task faster.

• Protect regression tests. If test changes are necessary, review and approve the reasoning separately.

• Keep secrets outside the agent's reach. An instruction not to read API keys is not a substitute for isolation and least-privilege credentials.

• Separate planning from implementation. For migrations or broad refactors, ask for an impact analysis and a verification plan first.

• Know the limits of your tests. This example tests backoff calculation only, not jitter, retry limits, network failure handling, or end-to-end behavior.

Conclusion

A practical way to start with Codex is to reproduce a small bug, specify the exact scope of work, and establish verification you control.

The workflow is reproduce → instruct → implement → inspect diff → retest → review. Codex can take on repetitive implementation work while developers remain responsible for deciding whether a change is correct and safe.

Official references

• Codex GitHub repository and installation

• Codex CLI

• Developer commands and code review

• AGENTS.md project guidance

• Security and permissions

• Codex plan availability

한국어 버전: OpenAI Codex 사용법: CLI 설치부터 버그 수정·테스트·코드 리뷰까지