OpenAI Codex is an AI coding agent that can inspect a project, edit files, run commands, test changes, review code, and help developers move from an idea to a reviewable result. This guide explains what Codex is, how it works, where to use it, how its models and plans differ, and how to use it without giving an AI agent more access than it needs.
What Is OpenAI Codex?
OpenAI Codex is an AI agent designed to help people write, review, and ship code. The word agent matters because Codex is not limited to answering a question with a code block. When it has the required access, it can inspect a repository, search for relevant files, edit code, run terminal commands, execute tests, review the resulting changes, and continue working when the first attempt fails.
A traditional coding assistant often waits for the developer to choose a file and ask for a snippet. Codex can accept a broader objective such as:
Investigate why password-reset links expire immediately. Reproduce the problem, identify the root cause, implement the smallest safe fix, add a regression test, run the relevant checks, and summarize every changed file.
That instruction describes an outcome rather than a single line of code. Codex can then work through the engineering loop: understand the system, plan, change, test, inspect, and report.
Code generation is only one part of software engineering. The harder work is understanding an existing system, preserving behavior, validating changes, managing risk, and producing evidence that the result is ready for review. Codex is valuable because it can participate in more of that complete loop.
The Old Codex Versus Modern Codex
The name Codex has been used for two related but different generations of OpenAI technology. The original Codex was known mainly as a model that translated natural-language instructions into code. It became closely associated with early AI code completion.
Modern Codex is broader. It combines advanced models with an agent harness, repository access, terminal tools, local and cloud environments, Git workflows, review interfaces, skills, plugins, subagents, and permission controls.
| Area | Earlier Codex concept | Modern Codex |
|---|---|---|
| Primary role | Generate or complete code | Carry out reviewable coding tasks |
| Project awareness | Usually limited to supplied context | Can inspect repositories, files, and instructions |
| Tool use | Mostly text output | Can use terminal, Git, tests, browser tools, and integrations |
| Validation | Often left to the user | Can run checks and revise its work |
| Delivery | Code snippet | Diff, test results, review notes, or pull request workflow |
How Codex Works
Codex generally follows an agent loop. The exact sequence depends on the selected surface, model, permissions, and task, but the workflow usually contains six stages.
Receive a defined objective
The user states what should change, what must remain unchanged, and how success will be verified. Vague instructions force the agent to invent requirements.
Inspect the available context
Codex reads repository structure, source files, configuration, tests, documentation, logs, and project-specific instructions such as AGENTS.md.
Develop a plan
For larger tasks, Codex can divide the work into smaller steps. Some modes can delegate independent parts to subagents and collect their findings into one result.
Use tools and modify the project
Depending on permissions, Codex can search files, edit code, run shell commands, use Git, inspect a local application, consult documentation, or connect to supported services.
Validate the result
Codex can run tests, type checks, linters, builds, browser checks, or other project tools. When a check fails, it can inspect the failure and attempt a correction.
Present reviewable evidence
The final handoff may include a summary, changed files, a diff, commands run, test results, remaining risks, and suggested follow-up work.
Where Can You Use Codex?
OpenAI provides several Codex surfaces. They use the same general agent concept, but each one is suited to a different working style.
Codex in the ChatGPT desktop app
The desktop experience can work with local projects, files, terminals, diffs, worktrees, browser tools, and longer-running tasks after the user grants the required permissions.
Best for: a visual command center for local and parallel work.
Codex web
Codex web supports cloud-based work without requiring a local installation. Availability and features can depend on the user's plan, rollout, workspace settings, and integrations.
Best for: cloud tasks, remote access, and review from a browser.
Codex CLI
The command-line interface runs in a project directory and can inspect files, edit code, execute local development commands, review changes, and support non-interactive workflows.
Best for: developers who live in the terminal.
Codex IDE extension
The IDE experience lets developers include open files and selected code in a prompt, review edits in place, and hand longer tasks to the agent without leaving the editor.
Best for: focused implementation beside the code.
Codex cloud tasks
Cloud tasks run in isolated environments and can work in parallel. Users can inspect logs, review a summary and diff, request revisions, or open a pull request when the result is ready.
Best for: longer tasks and independent parallel work.
Pull request review and automation
Codex can review GitHub pull requests, follow repository guidance, post findings, and run through supported GitHub workflows or the official Codex GitHub Action.
Best for: adding an automated review layer before merge.
What Can OpenAI Codex Do?
1. Explain an unfamiliar codebase
Codex can map a repository, identify entry points, trace data flow, explain authentication, locate build commands, and highlight high-risk areas. This can shorten onboarding time, but the explanation should still be checked against actual runtime behavior.
2. Build features across multiple files
A feature may require changes to the user interface, API, database layer, tests, and documentation. Codex can coordinate those edits when the objective and constraints are clear.
3. Investigate and fix bugs
Codex can reproduce an error, trace its cause, implement a focused correction, and add a regression test. The quality of the investigation improves when the prompt includes reproduction steps, expected behavior, actual behavior, logs, screenshots, and recent changes.
4. Refactor existing code
Codex can remove duplication, split oversized modules, improve type coverage, modernize patterns, and migrate dependencies. Refactoring without strong tests remains risky because the repository may not contain enough evidence to prove that behavior was preserved.
5. Write and improve tests
Codex can create unit, integration, regression, and browser tests. A better instruction defines the behavior and edge cases to protect instead of asking only for a higher coverage percentage.
6. Review code changes
Codex can examine a local diff, commit, branch comparison, or GitHub pull request. High-value review should focus on functional defects, security boundaries, data loss, race conditions, error handling, regressions, and missing tests rather than cosmetic preferences.
7. Update documentation
Codex can update README files, setup instructions, API references, migration notes, release notes, architecture documents, and troubleshooting guides. Documentation should be validated against the actual implementation rather than trusted because it sounds polished.
8. Automate repeated technical work
With non-interactive execution, skills, hooks, plugins, access tokens, and CI integration, Codex can support repeatable tasks such as release checks, dependency updates, documentation maintenance, change summaries, test-failure investigation, and security review.
Codex Models: GPT-5.6 Sol, Terra, and Luna
Codex is a product environment, while the selected model is the reasoning engine inside that environment. At the time of this update, OpenAI recommends three GPT-5.6 models for Codex.
| Model | Positioning | Best use | Tradeoff |
|---|---|---|---|
| GPT-5.6 Sol | Flagship model | Complex coding, research, computer use, security, and difficult open-ended work | Uses more time and tokens than lighter choices |
| GPT-5.6 Terra | Balanced everyday model | Routine implementation, analysis, debugging, and general tool use | Less depth than Sol on the hardest tasks |
| GPT-5.6 Luna | Fast and lower-cost model | Clear, repeatable, high-volume, and tightly scoped tasks | Not the best choice for ambiguous, high-risk decisions |
Higher reasoning effort may improve results on difficult tasks, but it also increases time and token use. Start with the default setting and increase reasoning only when the work genuinely requires more planning, cross-checking, or judgment. Ultra-style multi-agent modes are useful only when the task can be divided into meaningful independent parts.
codex --model gpt-5.6-solcodex exec -m gpt-5.6-terra "Review the current changes"Is OpenAI Codex Free?
Codex is included across ChatGPT plans, including Free and Go, but included usage, available models, cloud features, integrations, and rate limits vary. Paid plans generally provide higher limits and broader access, while credits can extend supported usage after included allowances are reached.
| Plan category | General expectation | Important limitation |
|---|---|---|
| Free and Go | Entry access to Codex with limited usage | Lower allowances and fewer premium capabilities |
| Plus | More regular individual use across supported surfaces | Rate limits and shared agentic allowances still apply |
| Pro | Higher limits for heavier individual use | More access does not make inefficient prompts inexpensive |
| Business, Enterprise, and Edu | Workspace controls, governance, and organization-level options | Availability depends on contract, configuration, role, and policy |
| API key usage | Usage-based local or scripted workflows where supported | Separate API billing and security responsibilities apply |
A short prompt is not automatically cheap. A request such as "improve the whole application" can trigger broad repository reading, many tool calls, repeated tests, and extensive output. A focused task with a clear definition of done is usually easier to validate and more efficient.
How to Install Codex CLI
OpenAI provides a standalone installer for macOS and Linux. Run the following command in a terminal:
curl -fsSL https://chatgpt.com/codex/install.sh | shOpen a project directory and start Codex:
cd /path/to/your/project
codexThe first launch will ask you to sign in with ChatGPT or use another supported authentication method. Inside an interactive session, these commands are especially useful:
| Command | Purpose |
|---|---|
/init |
Create an AGENTS.md instruction file |
/status |
Show the current session configuration |
/permissions |
Choose what Codex is allowed to do |
/model |
Select a model and reasoning effort |
/review |
Review current changes and surface issues |
How AGENTS.md Improves Codex Results
AGENTS.md is a repository instruction file that Codex reads before it begins work. It can define build commands, test requirements, architecture rules, security boundaries, formatting expectations, and completion criteria. More specific AGENTS.md files can provide directory-level guidance.
The file should be compact and operational. A long policy document full of vague advice can bury the rules that matter.
# Project Instructions
## Development rules
- Follow the existing architecture.
- Do not add production dependencies without approval.
- Preserve backward compatibility unless the task explicitly changes it.
- Do not refactor unrelated files.
## Validation
- Run npm test after changing JavaScript or TypeScript files.
- Run npm run lint before completion.
- Add a regression test for every confirmed bug fix.
## Security
- Never commit credentials, secrets, tokens, or private keys.
- Do not weaken authentication or authorization checks.
- Ask before changing database schemas or production configuration.
## Completion report
- Explain the root cause or implementation approach.
- List every modified file.
- Report commands and tests executed.
- Identify unresolved risks or unverified assumptions.Put permanent repository rules in AGENTS.md. Put task-specific requirements in the prompt. Mixing everything into one huge file makes the instructions harder to maintain and easier to ignore.
How to Write Better Codex Prompts
Codex performs best when the instruction resembles a clear engineering ticket. A strong prompt usually contains five parts.
Weak prompt
Fix the dashboard.
Improved prompt
Investigate why the dashboard cards overlap below 768 pixels. Preserve the current desktop layout, avoid new dependencies, and do not change the data-loading logic. Reproduce the issue at 360, 390, 768, and 1024 pixels. Implement the smallest maintainable fix, run the relevant tests and build, and report the root cause, changed files, validation results, and any remaining visual risk.
A reusable Codex prompt template
Objective:
[Describe the exact result you need.]
Context:
[Explain the relevant project area, current behavior, and known evidence.]
Constraints:
- [What must remain unchanged]
- [Dependencies or technologies that are not allowed]
- [Actions that require approval]
Validation:
- [Tests to add or run]
- [Build, lint, type-check, or browser checks]
- [Specific edge cases]
Completion report:
- Explain the approach or root cause.
- List every changed file.
- Report commands and results.
- Identify unverified assumptions and remaining risks.Practical Codex Workflows
Workflow 1: Understand a repository before editing
Inspect this repository without changing any files. Explain the architecture,
entry points, data flow, authentication process, build commands, test commands,
and the five areas with the highest maintenance or security risk. Cite the
specific files that support each conclusion.Workflow 2: Fix a confirmed bug
Reproduce the reported error, identify the root cause, and implement the smallest
safe correction. Add a regression test that fails before the fix and passes after
it. Do not refactor unrelated code. Run the relevant tests, lint, type checks, and
build. Summarize the evidence and remaining uncertainty.Workflow 3: Review current changes
Review the current uncommitted changes. Focus on functional defects,
authorization failures, data loss, race conditions, broken error handling,
performance regressions, and missing tests. Ignore minor style preferences unless
they create a real maintenance or correctness risk.Workflow 4: Add a feature
Add CSV export to the attendance report. Preserve the existing PDF export and API
response. Do not add dependencies. Cover commas, quotation marks, empty values,
line breaks, and Unicode learner names. Run the relevant tests and build. Report
all modified files and any data-formatting risks.Workflow 5: Improve performance with evidence
Measure the slow report-generation workflow before changing it. Identify the main
bottleneck, implement one focused improvement, and compare before-and-after
results using the same input. Do not trade correctness for speed. Explain the
measurement method and limitations.Workflow 6: Create a school automation
Build a Google Apps Script workflow that validates form submissions, generates a
document from an approved template, exports a PDF, emails the requester, and logs
the result in a tracking sheet. Prevent duplicate generation, avoid exposing
personal data in logs, and provide installation, authorization, testing, and
rollback instructions.Codex Versus ChatGPT and Traditional Code Autocomplete
| Capability | Traditional autocomplete | Regular ChatGPT conversation | Codex |
|---|---|---|---|
| Explain concepts | Limited | Strong | Strong |
| Generate snippets | Strong | Strong | Strong |
| Inspect a full repository | Limited | Depends on supplied files and tools | Core workflow |
| Edit several files | Limited | Environment dependent | Core workflow |
| Run terminal commands and tests | No | Environment dependent | Yes, with permission |
| Review a diff or pull request | Limited | Possible with supplied context | Dedicated workflows |
| Work in cloud environments | No | Not the main coding workflow | Yes |
| Prepare reviewable project changes | No | Limited | Primary purpose |
OpenAI currently describes Codex as the coding-focused agent, while ChatGPT Work is a separate experience for longer research and deliverable tasks. The boundary can feel less obvious as the same model family, plugins, and agent technology appear across products, but the intended workflows remain different.
Security, Sandboxing, and Permission Controls
A coding agent can execute commands and modify files. That makes it more operationally powerful - and more dangerous - than a chatbot that only returns text. Codex uses sandboxing, approvals, network controls, workspace policy, and tool permissions to limit what the agent can do.
Sandbox
Defines what files, processes, and system resources the agent can technically access.
Approval policy
Defines which actions can run automatically and which require explicit user approval.
Network control
Limits internet access and reduces uncontrolled communication with external services.
Workspace policy
Lets organizations govern models, plugins, connectors, roles, retention, and access.
Minimum security practices
- Open only the repository or folder required for the task.
- Keep network access disabled unless the work genuinely needs it.
- Do not place production credentials in prompts, files, logs, or AGENTS.md.
- Use branches, worktrees, test environments, and current backups.
- Review database migrations, authentication changes, and deployment scripts manually.
- Approve the narrowest action that solves the immediate problem.
- Inspect the final diff instead of trusting the summary.
- Require independent review for high-risk, privacy-sensitive, or regulated systems.
Limitations and Risks of Codex
Codex can produce convincing but incorrect code
Fluency is not proof. A clean diff can still contain a subtle logic error, security flaw, or broken edge case.
Tests can create false confidence
An agent may write tests that confirm its own implementation rather than the actual business rule. Test quality matters more than a coverage number.
Weak repositories limit reliable automation
Missing documentation, inconsistent architecture, obsolete dependencies, and poor tests leave the agent with less evidence about intended behavior.
Broad prompts waste usage and increase review burden
"Improve everything" has no measurable finish line. It encourages unrelated changes, larger diffs, longer runs, and harder verification.
Context is incomplete
Important rules may exist in people's heads, external systems, private conversations, or production behavior that the repository does not contain.
Generated complexity can accumulate
Codex may solve a small problem by adding abstractions, dependencies, configuration, or generic frameworks that the project does not need.
More autonomy increases the cost of a mistake
An agent can modify several files or run destructive commands faster than a person. Permissions, review, rollback, and environment isolation are therefore essential.
Overdependence weakens technical judgment
A user who cannot evaluate the output becomes dependent on a system they cannot supervise. Codex should amplify understanding, not replace it.
Best Practices for Using Codex
- Start with a clean Git state. Commit or stash existing work so agent changes can be isolated and reversed.
- Separate investigation from implementation. For risky tasks, first ask Codex to inspect and propose a plan without editing files.
- Define what done means. State the expected behavior, constraints, validation commands, and edge cases.
- Keep each change small. Small diffs are easier to test, review, understand, and roll back.
- Use AGENTS.md for durable rules. Store build commands, review expectations, and repository conventions in one maintained place.
- Use the least powerful model and reasoning level that works. Reserve the most expensive modes for tasks that genuinely require depth or parallel delegation.
- Require evidence. Ask for commands run, test output, file references, measurements, and unresolved assumptions.
- Review the diff line by line. The summary is a navigation aid, not a substitute for inspection.
- Test the real user flow. Passing unit tests do not guarantee that the application behaves correctly in the browser or in production.
- Keep a human accountable. A named person should own the decision to merge, publish, deploy, or process sensitive data.
Can Non-Programmers Use Codex?
Yes. Natural-language instructions make Codex useful for administrators, analysts, teachers, designers, researchers, and small teams that need lightweight software or automation. OpenAI reported in June 2026 that non-developers were a growing portion of Codex users.
Examples of practical projects include:
- Google Apps Script form and certificate workflows
- School dashboards and reporting tools
- Spreadsheet validation and data-cleaning utilities
- Simple reading, inventory, attendance, or tracking applications
- Website components and responsive layout repairs
- Document-generation and email automation
The barrier to producing software is lower, but the barrier to operating software safely still exists. Non-programmers may not recognize insecure data handling, silent failures, maintainability problems, licensing issues, or deployment risks. For systems that affect money, privacy, safety, grades, employment, or public services, independent technical review remains necessary.
Frequently Asked Questions About OpenAI Codex
Is Codex part of ChatGPT?
Yes. Codex uses a ChatGPT account and is available through supported Codex surfaces, including Codex in the ChatGPT desktop app, Codex web, Codex CLI, and the Codex IDE extension. Access and features vary by plan, rollout, application version, and workspace policy.
Is OpenAI Codex free?
Codex is included across ChatGPT plans, including Free and Go. Usage limits, models, integrations, and cloud capabilities differ by plan.
Does Codex use ChatGPT credits?
Supported Codex usage can draw from included plan allowances and then from purchased ChatGPT credits where flexible usage is available. Consumption depends on the model, input, cached input, output, tools, and task complexity.
Can Codex edit files on my computer?
Yes, when used through a supported local environment and after you grant access. The available files and actions are restricted by the selected workspace, sandbox, permissions, and approval policy.
Can Codex run terminal commands?
Yes. Codex CLI and supported local Codex environments can run commands within their configured sandbox and approval rules.
Can Codex build a complete application?
It can build substantial parts of an application and may complete a well-scoped project end to end. Production readiness still requires security review, testing, deployment controls, monitoring, maintenance planning, and accountable human approval.
Can Codex work with GitHub?
Yes. Codex supports GitHub-connected cloud work, pull request review, issue and pull request delegation, and an official GitHub Action for selected automated workflows.
Does Codex require internet access?
Not for every local task. Many repository tasks can run with network access disabled. Internet access may be needed for dependency installation, current documentation, remote services, or cloud integrations.
What is AGENTS.md?
AGENTS.md is a project instruction file that gives Codex durable guidance such as build commands, test requirements, architecture rules, review standards, and security boundaries.
Which Codex model should I use?
Use GPT-5.6 Sol for difficult, open-ended, high-value work; Terra for balanced everyday tasks; and Luna for clear, repeatable, high-volume work. Use the lowest reasoning level that reliably produces the required result.
Is Codex safe?
Codex includes sandboxing, approvals, network controls, and workspace policies, but no control can guarantee that every generated change is correct or safe. Least privilege, testing, backups, and human review remain essential.
Will Codex replace software developers?
Codex can automate more implementation and review work, but software engineering still requires problem definition, architecture, product judgment, security ownership, stakeholder coordination, maintenance, and accountability. It is more likely to change the developer role than remove the need for responsible technical leadership.
Final Verdict
OpenAI Codex represents a shift from AI-assisted typing to AI-assisted software engineering. It can work across a larger portion of the development cycle: repository exploration, implementation, testing, review, documentation, and automation.
Its greatest benefit is not simply faster code generation. Its real value is the ability to carry a defined objective through several technical steps and return a reviewable result.
That same autonomy creates the central risk. A tool that can edit files and execute commands can also make a larger mistake more quickly. Codex should therefore be treated as a capable technical agent, not an infallible developer.
The best Codex users will not be the people who stop thinking. They will be the people who define problems precisely, limit access carefully, demand evidence, and know when a plausible result is still not safe to ship.
Official Sources and Further Reading
- OpenAI Codex product page
- Using Codex with your ChatGPT plan
- Codex CLI documentation
- Codex model guide
- Codex pricing and feature availability
- Codex IDE extension
- Codex cloud tasks
- AGENTS.md documentation
- Codex best practices
- Codex code review in GitHub
- Codex for every role, tool, and workflow
Product features, model access, prices, and plan limits can change. This article was checked against official OpenAI sources on July 16, 2026.