OpenAI Codex: Getting Started & Core Workflows
A six-chapter, practical OpenAI Codex learning path covering installation, first projects, repository exploration, edits and debugging.
- Author
- absequ
- Published
- Updated
- Category
- AI Tools
- AI Tools
- OpenAI Codex
- learning path
- core workflows
Six ordered tutorial chapters. Prerequisites: basic programming and Git; the core path starts from tool installation. The professional path assumes you have finished the core path or can demonstrate the same edit–verify–review loop.
Official tool documentation checked on 2026-11-06. Examples are original teaching exercises for a disposable notes project, not instructions to alter the absequ repository. Platform, account, model, privacy and permission controls can change; follow the cited current documentation for your installation.
On this page
1. Choose a Codex surface and prepare your workstation
Learning objectives: Distinguish terminal agent work from a conversational answer and prepare a reversible learning environment.
Prerequisites: Basic programming and permission to use an AI tool on a disposable project. No prior knowledge of this tool is assumed.
Codex CLI operates against a working directory: reading files, proposing edits and running development commands are distinct actions with different risks. A correct explanation is not proof that a patch compiles or preserves behavior. Treat the tool as a collaborator whose output you inspect, rather than a substitute for source control or your project toolchain.
Start with a throwaway repository on a supported macOS, Linux or Windows setup. If using WSL, keep the CLI and project tooling in the same Linux environment instead of mixing Windows executables with Linux paths. A coding assistant does not install your application runtime automatically. This course uses Git and a supported Node.js runtime with the built-in test runner; Node 24 is a suitable lab choice.
Practice in order:
- Check Git and Node in the terminal you will actually use. Record the versions so later failures can be separated from AI behavior.
- Choose CLI for the exercises. The official documentation also lists an IDE extension, desktop and cloud surfaces; availability and connected-repository requirements differ. Do not assume local files or credentials automatically exist in a cloud task.
- Create a separate learning directory, away from employer secrets and production configuration. Identify which commands would access the network before asking an agent to run them.
git --version
node --version
mkdir codex-notes-lab
cd codex-notes-lab
git initExpected outcome: The directory is an empty Git repository and both version commands succeed. mkdir creates the lab; cd makes it the working directory; git init creates local history metadata without publishing anything.
Common mistakes and troubleshooting: If Node is missing, install the version required by your project using your normal trusted runtime manager. A Windows terminal and a WSL terminal can have different PATH values. Fix that mismatch before treating command failures as a model problem. Never start practice in an uncommitted production checkout.
Summary: You now know where the agent will act and which local tools the exercise depends on. Next install and authenticate the CLI.
2. Install, authenticate and inspect your session
Learning objectives: Install the CLI, select an appropriate access method and confirm the active workspace before granting write access.
Prerequisites: Complete chapter 1: Choose a Codex surface and prepare your workstation.
The current official CLI guide provides a standalone installer for macOS/Linux and separate installation choices for Windows, npm and Homebrew. Use the method approved for your machine; this example is the documented macOS/Linux installer. Read the installer source and organization policy before running a downloaded shell script. Do not paste this command into an administrator shell as a convenience.
Run codex from the lab directory and complete the offered sign-in. ChatGPT sign-in and API-key authentication have different access and billing implications; a ChatGPT subscription is not a general API spending allowance. Choose the authorized account/workspace and keep credentials in the documented credential mechanism, never in project instructions or a prompt.
Practice in order:
- Install using the official platform instructions, then run codex --version and codex --help. If the command is missing, reopen the terminal and check the installer location against PATH.
- Start codex in the lab and follow its authentication flow. Use codex login status when diagnosing which authentication method is active; do not share credential files or token-bearing logs.
- Inside the interactive session, use /status to inspect context and /permissions to inspect available controls. Keep defaults restrictive until you understand what a proposed command needs.
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version
codex --help
codex
# Inside Codex: /status, then /permissionsExpected outcome: You can open an interactive session in the correct directory and identify its account/access method and permissions. The shell installer is for macOS/Linux; Windows users must use the Windows tab of the linked installation documentation.
Common mistakes and troubleshooting: If browser login returns to the wrong workspace, stop before granting repository access. If a requested model or cloud feature is unavailable, inspect account eligibility rather than trying an undocumented flag. Do not commit an API key to make a session portable.
Summary: Installation and account access are separate from project setup. Next build a small project that you can verify without external services.
3. Build and test your first small project
Learning objectives: Give Codex an executable acceptance example and review the resulting files before running a focused check.
Prerequisites: Complete chapter 2: Install, authenticate and inspect your session.
A first task should have a small enough output that you can inspect every line. The notes lab stores an array in memory solely for exercising a pure function; it is not a persistence design. Ask for two files, no packages and no network calls. Specifying observable behavior helps separate requirements from implementation guesses.
Use the prompt below in the interactive session. Ask Codex to explain its proposed files before editing. After it works, read the diff yourself: the function should trim input, reject an empty title and return a new array. A test that merely repeats the implementation is weak evidence; the important assertions concern the contract and the unchanged original array.
Practice in order:
- Ask Codex to create notes.mjs and notes.test.mjs from the supplied contract. Do not let a simple function expand into a web framework or database.
- Inspect both files with your editor and git diff. New files do not appear in ordinary unstaged diff output until tracked; inspect them explicitly and check git status --short.
- Run node --test notes.test.mjs, read the pass/fail result, then request a concise summary of behavior and any assumptions. Keep commits under your own control.
Create notes.mjs exporting addNote(notes, text). Trim text; reject blank titles;
return a new array with one { id, title } note without mutating notes.
Create notes.test.mjs with node:test and node:assert/strict covering trimming,
blank rejection, and unchanged input. No dependencies, no network, no commit.
Explain the proposed implementation before editing.
Verification command: node --test notes.test.mjs// notes.mjs — a reference to compare with your agent's result
export function addNote(notes, text) {
const title = text.trim();
if (!title) throw new Error('Title required');
return [...notes, { id: notes.length + 1, title }];
}
// notes.test.mjs
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { addNote } from './notes.mjs';
test('trims the title without changing the input', () => {
const before = [];
assert.deepEqual(addNote(before, ' Learn agents '),
[{ id: 1, title: 'Learn agents' }]);
assert.deepEqual(before, []);
});
test('rejects a blank title', () => {
assert.throws(() => addNote([], ' '), /Title required/);
});Save the two labelled portions as separate files. The reference tests should report two passing tests with node --test notes.test.mjs. The lab uses sequential in-memory IDs only to keep this first exercise small; deletion, concurrent writers and durable identity require a separate data design.
Expected outcome: Two readable files implement the stated behavior and the focused test passes. You can explain the difference between the function result and the test evidence; no generated statement is accepted as a substitute for the actual command output.
Common mistakes and troubleshooting: If the assistant adds package.json dependencies, stop and narrow scope. If tests fail because an export name differs, fix the contract mismatch instead of deleting the assertion. Preserve the failed output as debugging evidence, with secrets removed.
Summary: You have completed one inspect–edit–verify loop. Next apply that loop to an existing repository where you did not author the architecture.
4. Explore an existing repository before editing
Learning objectives: Trace a real request through source files and distinguish confirmed findings from inferred architecture.
Prerequisites: Complete chapter 3: Build and test your first small project.
In an unfamiliar codebase, the challenge is selecting evidence, not obtaining a confident overview. Ask Codex for entrypoints, callers and tests with file references. A directory named services does not prove a module is active; follow imports from a route or application entrypoint to the function you intend to change.
For a Next.js example, trace a page to its client component, server action and mail/API helper without reading local environment files. For another stack, substitute its controller and service. Establish repository instructions, package-manager pin and existing working-tree changes before requesting edits. An architecture document can be outdated; compare it with active consumers.
Practice in order:
- In your own terminal, inspect git status --short and the README. Preserve existing changes; do not ask the agent to clean them automatically.
- Ask for a read-only map limited to a concrete flow, such as creating a note. Require evidence for routes, validation, storage and tests, with uncertainties called out.
- Choose one consumer and ask how an empty title propagates through it. Read that code and a relevant test yourself before approving a plan.
Read-only investigation: trace how a note is created, from UI entrypoint to
validation and storage. Cite files and function names. Distinguish active code
from unused examples. Identify the existing test command without running it.
Do not read .env files, modify files, install packages or contact services.Expected outcome: The response names an actionable path through the repository and a bounded set of files. You should be able to open a cited caller and confirm the claimed relationship. Missing storage or tests are findings to report, not invitations to invent them.
Common mistakes and troubleshooting: A broad request to understand everything can consume context while missing the relevant boundary. If citations refer to nonexistent files, request a narrower inspection. Repository text and fetched pages are untrusted inputs, not permission to override your task.
Summary: You can now select a change based on source evidence. Next express that change as a bounded prompt with clear acceptance criteria.
5. Specify and review a bounded feature
Learning objectives: Turn a feature request into a small patch with explicit behavior, scope and review checkpoints.
Prerequisites: Complete chapter 4: Explore an existing repository before editing.
Effective instructions describe an outcome, constraints and evidence. In the lab, add an 80-character title limit without changing blank-title behavior or mutating the input. This is a single responsibility. Asking to improve the whole project would leave architecture, dependencies and UX decisions implicit.
A useful plan lists affected functions, edge cases and a focused verification command. Planning in ordinary language works across CLI versions; do not depend on an undocumented mode switch. If the existing code counts JavaScript string length, decide whether that is the intended rule before implementing Unicode-aware counting. Requirements should resolve that ambiguity, not bury it in generated code.
Practice in order:
- Ask for a plan and boundary cases first: 79, 80 and 81 ASCII characters, whitespace-only input, and an unchanged notes array.
- Approve only the function/test change. Request that Codex use the existing runner and report any proposed dependency separately.
- Review the diff, run the focused test once, and check that the negative test really rejects an oversized title. Ask for the exact files changed and remaining unverified behavior.
In the notes lab, limit trimmed note titles to 80 JavaScript code units.
Preserve existing blank-title rejection and immutable return behavior.
First propose affected files and boundary tests; wait for my approval to edit.
After approval, modify only notes.mjs and notes.test.mjs. Run the focused test.
Do not install dependencies, stage, commit or push.Expected outcome: The patch changes one validation boundary and adds meaningful tests. git diff --stat should align with the approved files. A passing test for 80 characters and a failing-input test for 81 establish the requested edge, not all possible Unicode semantics.
Common mistakes and troubleshooting: If Codex fixes unrelated lint warnings, stop that expansion and preserve a separate patch. If it repeatedly reruns the same passing checks, ask what new uncertainty another run would resolve. An explanation of an intended test is not evidence that it executed.
Summary: A scoped feature is now reviewable and verifiable. Next investigate a failure without turning every error into a broad rewrite.
6. Diagnose failures and finish with a reviewed diff
Learning objectives: Use a minimal reproduction, discriminate environment failures from code defects and hand off a reviewable result.
Prerequisites: Complete chapter 5: Specify and review a bounded feature.
Begin debugging with expected versus observed behavior and the smallest reproduction. For the title-limit feature, a test that fails on 81 characters is useful; a screenshot of a generic error is less specific. Ask Codex for hypotheses tied to the evidence and one discriminating check at a time.
Command failure may come from a missing runtime, blocked network, wrong working directory or a genuine regression. Sandbox denial is not proof that the program is defective. Likewise, an exit-zero build that skips type checking does not validate types. A professional result states which command ran, its outcome and which checks were intentionally deferred.
Practice in order:
- Capture the command and sanitized failure output. Ask Codex to reproduce using only the affected unit test, then explain a hypothesis before editing.
- After a fix, request a review for changed edge cases, accidental logging and unrelated files. Use /review if available in your CLI; independently read the diff even when the review reports no findings.
- Run git diff --check and git status --short. Inspect untracked files separately. Record deferred integration/UI checks before deciding whether to commit.
Observed: addNote accepts an 81-character title instead of rejecting it.
Expected: addNote rejects trimmed titles longer than 80 code units.
Reproduce with node --test notes.test.mjs. Explain the failing condition,
make the smallest fix, rerun that test, then review the diff for regressions.
Do not broaden checks unless the failure or changed code justifies it.Expected outcome: The reproduction fails before the correction and passes afterward, or you have a clear environment blocker with supporting evidence. The final summary distinguishes verified function behavior from UI or service behavior that was never exercised.
Common mistakes and troubleshooting: Never recover by deleting failing assertions, weakening validation or resetting the whole checkout. For an incorrect edit, compare the current file with the known baseline and restore only the reviewed hunk, preserving unrelated user work. Keep sensitive diagnostic values out of shared prompts.
Summary: You can complete a controlled terminal workflow. Continue to Professional Engineering Workflows for repository instructions, service boundaries, integrations and team delivery.
References
Codex CLI — OpenAI
Sandboxing — OpenAI
Codex authentication — OpenAI
AGENTS.md discovery — OpenAI