OpenAI Codex Training Guide

Codex is part of the OpenAI product family and works with ChatGPT account access where your plan and organization allow it. It is different from ordinary chat because it can work in a project context. That context may include files, folders, repositories, terminal output, browser previews, screenshots, or connected tools. The first lesson is not "turn everything on." The first lesson is "choose the right boundary."

• Goal: Tell Codex what outcome you want, such as "explain this project" or "draft a plan."
• Workspace: Open an approved folder or repository. For training, use a practice folder with non-sensitive files.
• Permission: Start with inspection and planning. Approve editing, commands, browser use, sending, publishing, merging, or deployment only when the purpose is clear.
• Evidence: Ask Codex to cite files, list assumptions, explain what it checked, and say what it did not check.

Your first task should be low risk and easy to review. A good first prompt is not a command to build, deploy, or change records. It is an inspect-first request. This lets you see how Codex reads context and communicates before you let it make changes.

Goal: Help me understand this practice workspace.
Context: Use only the files in this training folder.
Constraints: Do not edit files, run destructive commands, send anything, publish anything, or connect to external tools.
Done when: Give me a plain-English summary of what is here, what files matter, what questions you have, and what a safe next task would be.

After Codex responds, check whether it stayed inside the task, named the sources it used, separated facts from assumptions, and gave you a next step you can understand.

Earlier versions of this guide mixed some practical and advanced topics into the introductory flow. Those topics are useful, but they do not belong inside onboarding. They now live in Codex 102 and Codex 103 so the learning path is cleaner.

The 102 loop is: define the task, choose the Codex surface, provide sources, require a plan, approve a narrow action, validate the result, and capture evidence. This is the same logic used in the broader course sections on Where Codex Fits, Prompting, Verification, and Team Guidance.

Reference: OpenAI Academy Codex 102.

In practice, this loop is not always linear. Codex may inspect the workspace and ask a clarifying question. The learner may revise the goal, narrow the source list, or decide that the task should stop. That is normal. A disciplined 102 operator treats each loop as a chance to improve the work package before allowing more authority.

Skills are reusable instructions for repeated work. A personal skill can live under a user's Codex skills folder. A team skill can live inside a repository when the team wants the workflow to travel with the project. The 102 workshop preview includes practical skill creation patterns, including use of the skill creator and a reusable change-brief example.

Reference: OpenAI Codex Skills.

A skill should be written like an operating procedure. It should say when to use it, what inputs it needs, what steps Codex should follow, what output format to return, and what evidence must be present before the learner accepts the result. A skill that only says "make a good report" is not a real reusable workflow. A stronger skill says which files to inspect, what assumptions to list, what source citations to include, and when Codex should stop for approval.

• Personal skill: useful for one learner or one operator who repeats the same work across projects.
• Repository skill: useful when a team wants consistent instructions for a project or workflow.
• Skill contents: task purpose, required inputs, step-by-step process, output format, examples, and verification expectations.
• Review rule: a skill can improve consistency, but it does not remove human review or policy approval.

Skill outline example:
Name: change-brief
Purpose: Turn a code change or PR into a business-readable review brief.
Inputs: PR link or diff, business goal, risk priorities, test output, relevant ticket.
Steps: inspect diff, identify behavior change, map to requirement, review tests, list risks.
Output: summary, changed behavior, evidence, risks, recommendation, open questions.
Stop when: permissions, customer data, security policy, deployment, or merge authority is unclear.

MCP is a way to connect Codex to approved tools or data sources. In practical terms, it gives Codex a structured route to information or actions outside the current folder. That makes it powerful and useful, but it also means access needs to be intentional.

References: OpenAI Codex MCP and Codex CLI MCP reference.

A 102 learner should be able to explain three things before using MCP: what tool is being connected, what Codex is allowed to do with it, and how the learner will confirm the connection is working. The Codex 102 preview shows this pattern with an OpenAI Docs MCP setup and a check using the MCP command inside Codex.

For a business learner, MCP should be understood as a controlled bridge. If the bridge leads to official documentation, the main risk is whether the learner cites the right source and version. If it leads to private systems, the risk expands to permissions, sensitive data, actions, auditability, and policy ownership. The same technical mechanism can have very different business risk depending on what it connects to.

• Low-risk learning use: connect to a documentation source so Codex can cite official references.
• Moderate-risk team use: connect to read-only repository, issue, or documentation tools for review support.
• Higher-risk business use: connect to ticket, email, CRM, data warehouse, or operational systems that may contain confidential data.
• Restricted use: any connection that can update records, send messages, change permissions, deploy, or touch regulated data.

GitHub review belongs in 102 because it is practical and evidence-rich. A pull request already has the diff, comments, checks, branch, and merge decision. Codex can help find serious issues, explain risk, and suggest a focused fix. The human reviewer still decides what is valid and whether the change is ready.

Reference: OpenAI Codex Review.

@codex review
Prioritize correctness, security, privacy, regression risk, missing tests, and user impact.
Use the repository guidance.
Return findings first, ordered by severity, with exact references and verification suggestions.

When Codex reviews a pull request, the best output is not a long list of opinions. It is a short set of high-signal findings. A finding should tell the reviewer where the issue is, why it matters, how it could fail, and how to verify the fix. If Codex cannot explain impact, the reviewer should treat the finding as a question rather than a blocker.

An advanced Codex workflow usually has several moving parts: a business owner, a technical owner, source systems, workspace boundaries, a prompt or skill, a validation plan, and a decision artifact. Before automating it, run it manually enough times to know where mistakes happen.

References: OpenAI Codex Worktrees and OpenAI Codex Automations.

A strong advanced workflow has an operating shape that can be explained in one page: trigger, input sources, workspace, agent roles, actions allowed, actions blocked, validation checks, evidence artifact, approver, and exception path. If the team cannot describe those items, the workflow is not ready to scale.

Multi-agent work is useful when different perspectives should be separated before the final decision. For example, one reviewer can focus on security, another on tests, another on maintainability, and another on business requirement coverage. The value is not that every agent is automatically right. The value is that the human reviewer receives structured viewpoints and can compare them.

Reference: OpenAI Codex Subagents.

A mature 103 workflow requires a reconciliation step. Codex should summarize agreements, disagreements, high-severity findings, false positives, and items that need human judgment.

Role separation is useful because one review perspective can miss what another catches. A security reviewer may focus on data exposure and permission checks. A test reviewer may focus on missing coverage and edge cases. A business reviewer may ask whether the change actually satisfies the requirement. The reconciliation step should not average the findings. It should identify which findings are decision-relevant.

Automation should come after the team understands the workflow. If the manual process is unclear, automation will make confusion repeat faster. A good advanced automation has a trigger, input boundary, output format, validation check, owner, approval gate, and audit trail.

References: OpenAI Codex Automations and OpenAI Codex Hooks.

• Safe candidate: weekly documentation freshness report with no automatic publishing.
• Higher-risk candidate: recurring PR fix workflow that proposes patches but does not merge them automatically.
• Restricted candidate: production data changes, external sending, or deployment automation without mature controls.

The safest automation pattern is draft-first. Codex can prepare a report, proposed PR, review summary, migration checklist, or status update, then pause for a human decision. That pattern gives the team speed without hiding accountability. Production-impacting automation should come later, and only after the organization has strong evidence that the workflow is stable.

Automation readiness prompt:
Evaluate this recurring workflow for automation readiness.
Return:
1. Stable inputs
2. Required approvals
3. Actions safe to automate
4. Actions that must remain human-owned
5. Evidence to log every run
6. Failure and exception handling
7. Go / revise / do not automate recommendation

At 103, governance is part of the workflow design. The organization should know which teams may use Codex, which data is approved, which tools are allowed, when approvals are required, how evidence is stored, and how repeated mistakes become durable guidance.

References: OpenAI Codex Governance and OpenAI Codex Managed Configuration.

The best scaling pattern is workflow by workflow. Start with a small number of approved use cases, capture evidence, update guidance, then expand. Do not equate maturity with giving Codex maximum freedom. Maturity means the right amount of authority for the task and the right level of review for the risk.

The OpenAI Academy guide says Codex is designed to accelerate builder productivity and move toward more autonomous execution of software tasks. For a business audience, the deeper point is that Codex changes the work system around software. It affects how requirements are written, how technical discovery happens, how defects are investigated, how evidence is gathered, and how reviews are prepared.

Codex should be understood through five operating capabilities:

• Comprehension: It can inspect unfamiliar code, documentation, logs, or outputs and explain structure, intent, and dependencies.
• Transformation: It can turn requirements into drafts, code changes, tests, migration plans, documents, and summaries.
• Execution: When permitted, it can run commands, operate tools, use browsers, and perform multi-step workflows.
• Validation: It can run tests, compare outputs, capture screenshots, review diffs, and explain risks.
• Coordination: It can work in threads, resume prior context, use instructions, and support parallel subtasks.

The business lesson is that Codex does not merely "write code." It compresses the distance between a business question and a reviewable output. That output might be a patch, test result, technical explanation, PR review, spreadsheet analysis, slide deck outline, or formal recommendation.

The Academy guide identifies GPT-5-Codex as purpose-built for Codex and guided coding. The business implication is not simply "a stronger model." It changes which tasks are realistic to delegate. A more steerable model can follow tighter instructions. Adaptive reasoning means simple work can stay fast while complex work can take more time. Strong code review capability makes it useful before, during, and after implementation. Image input matters for frontend work because a screenshot, mockup, bug image, or UI state can become concrete context.

The same request can be low risk or high risk depending on where it runs. A request to "review this diff" inside a GitHub pull request is review-oriented and visible. The same request inside a local folder with uncommitted changes may require the user to decide what should be shared, committed, or ignored. A request to "summarize these emails" depends on whether Codex has authorized access to an app connection, an export file, or only a pasted excerpt.

Use four practical questions before choosing where to use Codex:

1. Where does the source material live? Repository, PR, local folder, email, browser, spreadsheet, transcript, design image, or document.
2. What action is needed? Explain, draft, edit, test, operate a browser, inspect desktop UI, create an output, or review.
3. What must be auditable? Diffs, source citations, command output, screenshots, review comments, formulas, or decision log.
4. What authority is required? Read-only analysis, local edit, PR comment, outbound message, production deployment, or external publication.

The Academy guide names advanced CLI and CI/CD workflows as stretch uses. In plain English, this means Codex can help with repeatable command-line work when the input, permissions, output format, and review gate are clear. It does not mean "let Codex do anything automatically."

For business users, the critical point is that automation shifts risk from "one person clicked a button" to "a workflow can repeat." Therefore, automated Codex use should have narrow scope, explicit credentials handling, controlled environment variables, logged output, and a human review step before production impact.

Advanced task pattern:
Input: failing test output, target directory, and expected behavior.
Instruction: propose and implement the smallest fix.
Constraints: do not change public API, do not add dependencies, do not touch unrelated files.
Output: summary, diff, tests run, residual risks.
Gate: open PR or produce patch for human review; do not merge automatically.

The Academy page links to a Codex demo described as a way to understand the basics of using Codex and how the IDE extension, Codex web, and code review work together. That is an important operating lesson: Codex is not only one screen. A practical workflow may begin in an IDE, move to Codex web for delegated work, and return to GitHub for review evidence.

A strong learner should be able to explain not only what each option does, but why the demo combines them: coding, delegated execution, and review are connected stages in the same delivery lifecycle.

The Codex manual's goal, context, constraints, and done criteria pattern is simple, but it is not shallow. It is a compact management discipline. Good prompts do the same work as a good assignment memo: they define the mission, provide the relevant background, make boundaries explicit, and describe acceptable proof.

A semi-technical business user does not need to write like an engineer. They need to write like a clear operator. The most common failure is not a lack of technical vocabulary. It is failing to say what should happen, why it matters, what should not happen, and how the result will be reviewed.

Use plan-first work when the task has ambiguity, risk, multiple files, multiple reviewers, unclear requirements, sensitive data, production impact, or uncertain tool access. The point of planning is not delay. It is preventing Codex from filling gaps with assumptions.

Goal: Prepare a migration plan for moving customer notifications from the legacy service to the new messaging service.
Context: Inspect the repository first. Focus on notification creation, retry logic, templates, and tests.
Constraints: Do not edit files yet. Identify risks around billing, compliance, and customer-facing copy.
Done when: Provide a phased plan, files likely affected, test strategy, rollback approach, and questions that need human answers.

Use the approved migration plan. Implement phase 1 only: add tests around current notification behavior and document existing retry rules.
Do not change runtime behavior.
Done when tests pass and the summary lists changed files, tests run, and remaining phases.

Reusable prompt patterns help users avoid starting from a blank page. They should be adapted, not copied blindly.

Codebase orientation:
Inspect this repository and explain the business process it supports. Identify the main modules, data flow, external integrations, and highest-risk areas. Do not edit files. Cite file paths and list open questions for the product owner.

Bug investigation:
Investigate this issue using the error log, screenshot, and repository. First summarize the observed symptom and expected behavior. Then identify likely causes, propose a reproduction path, and recommend a fix plan. Do not implement until I approve the plan.

PR review:
Review this change like an owner. Prioritize correctness, security, regressions, test gaps, maintainability, and user impact. Provide findings first, ordered by severity, with file references and verification suggestions.

Business document:
Convert these notes and source files into a formal decision memo. Separate facts, assumptions, analysis, options, recommendation, risks, and next steps. Cite source files or messages for any material claim.

Spreadsheet analysis:
Analyze this workbook for variance drivers. Preserve source data. Show calculations, assumptions, exceptions, and a management-level narrative. Create a table of findings and identify what should be verified manually.

Codex output should be evaluated by the strength of its evidence. A confident explanation is a starting point, not a finish line. The evidence ladder below helps non-engineers ask better review questions.

GitHub review is valuable because the unit of work is already structured: a pull request has a branch, diff, comments, checks, reviewers, and merge rules. Codex can provide a high-signal review pass, but the reviewer should still decide whether a finding is valid, whether a fix is appropriate, and whether the PR is ready.

A strong Codex review request should say what matters most:

@codex review
Prioritize correctness, security, privacy, data integrity, regression risk, and missing tests.
Use our AGENTS.md review guidance.
Avoid low-value style comments unless they indicate a real maintainability risk.
For each finding, explain impact, exact location, and suggested verification.

For business teams, PR review evidence should answer: what changed, why it matters, what was tested, what risk remains, and who is authorized to merge.

The Academy guide highlights image input as part of Codex's guided coding value. In practical terms, screenshots and browser inspection close a gap that tests alone may miss. A UI can compile and pass tests while still being unusable, inaccessible, clipped, or visually inconsistent.

• Use screenshots when: layout, spacing, responsive behavior, text overflow, dashboards, forms, charts, modals, or visual regressions matter.
• Ask for viewport coverage: desktop, tablet, and mobile sizes relevant to the audience.
• Ask for interaction coverage: hover, focus, keyboard navigation, validation states, loading states, and error states.
• Ask for accessibility checks: labels, contrast, focus order, readable text, and non-overlapping content.

The Codex manual describes access limits, approval policies, permissions, trusted projects, managed configuration, hooks, and responsible controls. The business translation is simple: Codex can be powerful only if its authority has clear boundaries. The organization must know what Codex can read, where it can write, when it can call external systems, and when a human must approve an action.

Separate four concepts that are often blurred together:

• Capability: What Codex or a connected tool can technically do.
• Permission: What the current session, access-limit setting, app connection, or policy allows.
• Approval: When Codex must stop and ask a user before continuing.
• Accountability: Who is responsible for the outcome if the work is accepted or acted upon.

Codex can encounter untrusted instructions inside web pages, emails, tickets, dependency READMEs, documents, or logs. A malicious or irrelevant source might say "ignore previous instructions" or ask the agent to exfiltrate data. The user should treat outside content as data to analyze, not instructions to obey.

For larger organizations, Codex controls should connect to existing security, compliance, and operational processes. The Codex manual describes enterprise ideas such as managed configuration, control dashboards or APIs, admin setup, access controls, and policy enforcement. A business rollout should translate those into practical operating questions.

• Identity: Which users, roles, and groups can use each Codex option?
• Repository access: Which repositories are connected, and do branch protections still apply?
• Data policy: Which classes of information may be used in prompts, app connections, screenshots, or exports?
• Tool policy: Which tool connections, browser tools, and desktop apps are allowed?
• Approval policy: Which actions require user, reviewer, manager, security, or legal approval?
• Auditability: What logs, task summaries, PR comments, and outputs must be retained?
• Measurement: How will usage, review quality, risk, and value be tracked?

Codex customization is a stack. Each layer has a different scope and failure mode. The most mature teams do not put everything in one place. They choose the smallest durable place that matches the need.

AGENTS.md is where teams make Codex less generic. It should be practical and grounded in repeated friction. The strongest AGENTS.md files tell Codex how the project is organized, how to build and test, what not to touch without approval, what quality means, and how to summarize work.

# AGENTS.md Structure

## Business Context
What the application does, who uses it, and which workflows are most sensitive.

## Repository Map
Key folders, ownership areas, generated files, and directories to avoid.

## Commands
Install, build, test, lint, typecheck, visual test, and data-generation commands.

## Coding Standards
Existing patterns, dependency policy, accessibility expectations, error handling, logging, and naming.

## Review Standards
How Codex should report changes: business impact, files changed, tests run, risks, and assumptions.

## Stop Conditions
When to pause: secrets, migrations, production data, legal copy, external messages, destructive commands.

Do not turn AGENTS.md into a vague values document. Codex benefits most from concrete commands, examples, boundaries, and review requirements.

Model Context Protocol, often shortened to MCP, and app connections let Codex work with external tools or private data when authorized. This is the bridge from "Codex can see a folder" to "Codex can work with a business system." Examples include GitHub, Gmail, Google Drive, Slack, documents, spreadsheets, custom internal APIs, or databases through approved tools.

The business rule is straightforward: live tool connections create live approval questions. A tool connection should have a purpose, owner, permission model, and review expectation. For example, an email connection may be approved for summarizing and drafting but not for sending without explicit approval. A database connection may be approved for read-only analysis but not data changes.

• Good tool-connection use: "Read support ticket data through the approved tool and produce a cited trend analysis."
• Risky tool-connection use: "Connect to every system and make whatever updates seem useful."
• Good tool-connection output: source list, access boundaries, findings, drafts, and actions requiring approval.

Skills and tool packages are how repeated work becomes more than a prompt. A skill can describe a workflow such as "generate a board report from a workbook and meeting notes." A tool package can bundle skills with tools, settings, assets, or app connections. Hooks can enforce checks, such as blocking risky commands or requiring review after a tool runs. Automations can run stable recurring work.

A serious Codex rollout should not be measured only by how many people have access. Access is an input. Adoption is whether specific workflows become faster, more reliable, better documented, and easier to review. Treat Codex use cases as a portfolio with different risk and value profiles.

Good Codex metrics combine speed, quality, risk, and adoption. A single productivity number is rarely enough.

• Cycle-time metrics: request to first output, output to review, review to acceptance, time saved versus baseline.
• Quality metrics: test coverage added, review findings caught before merge, escaped defects, rework rate, documentation accuracy.
• Control metrics: percentage of tasks with evidence, percentage requiring approval, policy exceptions, high-risk task volume.
• Learning metrics: repeated mistakes converted into AGENTS.md, skills, prompts, or process changes.
• Adoption metrics: active users by role and workflow, not just total prompts.

For leadership, the best narrative is not "we used AI more." It is "we reduced discovery time by 40%, increased test coverage on touched modules, and improved PR review quality without expanding production risk."

A work order should be detailed enough to prevent guessing but short enough to use. For higher-risk work, it should become a reusable intake form.

1. Business Intent
- What decision, workflow, or user outcome does this support?
- What value is expected if the task succeeds?

2. Source Material
- Repositories, branches, PRs, tickets, documents, emails, transcripts, screenshots, logs, workbooks.
- Which sources are authoritative?
- Which sources are background only?

3. Scope
- In scope:
- Out of scope:
- Stop before:

4. Constraints
- Security:
- Privacy:
- Brand/tone:
- Architecture:
- Dependencies:
- Timeline:

5. Codex Option
- App, CLI, IDE, Web/Cloud, GitHub, browser, computer use, app connection, or tool package.
- Why this option is appropriate.

6. Evidence Required
- Tests:
- Screenshots:
- Source citations:
- Calculations:
- Diff summary:
- Assumptions and limits:

7. Human Decision
- Approver:
- Accept/revise/escalate criteria:
- Action allowed after approval:

1. Business intent: Customers cannot complete profile setup on mobile; support volume increased.
2. Codex plan request: Inspect logs, screenshots, and profile setup code. Do not edit yet. Identify likely cause, affected files, reproduction path, and validation plan.
3. Human review: Product owner confirms expected behavior and prioritizes mobile fix.
4. Implementation request: Fix only the mobile validation issue. Preserve desktop behavior. Add or update tests if possible. Validate at mobile and desktop widths.
5. Evidence: diff, test output, screenshot notes, reproduction before/after, residual risks.
6. Decision: Accept fix, request additional testing, or escalate if root cause touches profile data policy.
7. After-action: Add a prompt pattern or AGENTS.md note for future responsive-form validation tasks.

1. Business intent: Leadership needs to understand why renewal delays increased in Q2.
2. Sources: exported CRM data, support emails, sales notes, meeting transcript, and prior Q1 deck.
3. Codex task 1: Analyze sources separately. Produce a source inventory and top hypotheses with evidence.
4. Codex task 2: Create a variance table and identify the largest drivers. Separate facts from assumptions.
5. Codex task 3: Draft a 10-slide leadership narrative with speaker notes and risk caveats.
6. Human review: Validate calculations, remove sensitive examples, confirm recommendation.
7. Decision: Approve presentation for leadership, request additional data, or escalate to revenue operations.

This example is intentionally non-code. The same Codex work principles apply: source material, constraints, evidence, review, and decision.

Codex is rooted in builder workflows, but the broader assistant pattern applies to many business tasks when the proper tools are available. The work is not "ask AI to think for me." The work is "assign a scoped transformation of source material into a reviewable output." That source material may be a repository, an email export, a Teams transcript, a Zoom chat, a spreadsheet, a Word document, a slide deck, a website, or a desktop application screen.

The capability depends on environment. Some sessions may have app connections, tool packages, browser control, computer use, document tools, spreadsheet tools, or presentation tools. Other sessions may not. A mature user learns to ask: what tools are available, what sources can be used, what actions are allowed, and what evidence will prove the result?

Email and chat are high-value because they contain commitments, objections, timelines, sentiment, risk signals, and undocumented decisions. Codex can help convert messy communication into structured operational intelligence.

Email triage prompt:
Use the authorized mailbox/search results or attached export only.
Group messages into urgent, needs reply, waiting on someone else, informational, and possible escalation.
For each item, provide sender, date, topic, why it matters, suggested action, and source message reference.
Draft replies only for the messages I mark. Do not send anything.

Meeting transcript prompt:
Summarize this transcript into decisions, action items, owners, due dates, risks, disagreements, and unresolved questions.
Separate direct transcript evidence from your interpretation.
Draft a follow-up email for review, but do not send.

Review rule: do not let a polished summary become the official record until a human confirms decisions, owners, and sensitive content.

Spreadsheet work benefits from Codex because it combines calculation, interpretation, explanation, and output generation. The key risk is unsupported narrative. Codex should show formulas, assumptions, data quality issues, and calculation logic.

Spreadsheet prompt:
Analyze this workbook for Q2 renewal-delay drivers.
Preserve source data.
Create a findings table with metric, calculation, source tab, evidence, business interpretation, and confidence.
Flag missing data, formula assumptions, and anything that needs a human finance or operations review.

Codex can help turn scattered material into formal outputs: decision memos, reports, redlines, summaries, presentations, speaker notes, and executive narratives. The serious-user standard is source traceability. Every material claim should tie to a source, calculation, or stated assumption.

Browser and desktop tasks can help when the workflow exists only in a user interface: testing a form, gathering screenshots, checking a dashboard, navigating a tool, or preparing a draft in an application. These tasks need explicit approval boundaries because UI actions can have real-world effects.

• Safe browser task: Inspect a web page, collect observations, capture screenshots, and report issues.
• Higher-risk browser task: Submit a form, make a purchase, update a record, or publish content. Require explicit approval.
• Parallel task pattern: One thread analyzes messages, one checks spreadsheet numbers, one drafts a report, and one reviews a PR. The user consolidates evidence and resolves conflicts.
• Conflict rule: Do not let multiple agents edit the same output unless ownership and merge order are clear.

Parallel work prompt:
Create three independent work areas:
1. Analyze source emails for customer themes.
2. Analyze workbook data for quantitative support.
3. Draft an executive narrative using only verified findings from 1 and 2.
Return separate evidence summaries and a final reconciliation table showing which claims are supported by which sources.