FIELD MANUAL / 18 GUIDES
Eighteen guides, one terminal-first system.
The primary track teaches how to operate Codex in a real repository. The secondary track keeps the original API architecture atlas for builders working below the CLI.
Codex CLI core
Codex CLI core course
Run the lessons in order, from installation and permissions to reusable workflows, subagents, and CI.
- 01 Read the guide↗
Foundation / 10 min / Stable
Install Codex and prove the toolchain
A reliable Codex workflow starts before the first prompt. Install from the official standalone script, identify the binary you are actually running, update deliberately, and use the built-in diagnostic report instead of guessing about configuration, authentication, Git, or terminal failures.
- 02 Read the guide↗
Foundation / 11 min / Stable
Choose authentication without leaking credentials
Codex supports ChatGPT sign-in for subscription access and API-key sign-in for usage-based local work. The safe path is to choose the flow deliberately, pipe secrets through stdin, verify the active method, and treat local auth storage like a password.
- 03 Read the guide↗
Foundation / 12 min / Stable
Run the first repository session like an engineer
The first useful Codex session begins in the right repository with a bounded permission mode and a prompt that states goal, context, constraints, and done condition. Codex can explore, edit, run checks, and report evidence, but only when the task boundary is explicit.
- 04 Read the guide↗
Safety / 14 min / Stable
Set authority before autonomy
Codex security is the combination of an OS-enforced sandbox and an approval policy. Workspace-write with on-request approvals is a practical local default; read-only is for inspection and planning. Web search does not automatically grant network access to spawned commands.
- 05 Read the guide↗
Workflow / 13 min / Stable
Control a long-running CLI session
Codex CLI exposes keyboard-first controls for live work plus top-level commands for saved-session lifecycle. Plan mode improves ambiguous work; status and diff expose state; compact preserves key context; review creates a dedicated inspection pass. Resume, fork, archive, unarchive, and permanent delete keep persisted work explicit.
- 06 Read the guide↗
Repository setup / 15 min / Stable
Make repository knowledge durable with AGENTS.md
Codex reads an instruction chain before work begins: global guidance, then project files from repository root toward the working directory. Closer guidance appears later and overrides broader guidance. AGENTS.override.md wins at a level, and the combined project guidance has a default size limit.
- 07 Read the guide↗
Repository setup / 16 min / Stable
Configure Codex by scope, not by accident
Codex resolves configuration from command-line overrides, trusted project layers, a selected profile, user config, system config, then built-in defaults. Profiles are separate files, and current model availability should be inspected live rather than frozen into evergreen advice.
- 08 Read the guide↗
Workflow / 14 min / Stable
Turn changes into reviewable evidence
Codex can implement, run checks, show the working-tree diff, and launch a dedicated reviewer. Review scopes are mutually exclusive: uncommitted work, a base-branch comparison, a commit, or custom instructions. The reviewer reports findings without changing the tree.
- 09 Read the guide↗
Extension / 16 min / Stable
Connect external systems through MCP
Codex supports local STDIO and Streamable HTTP MCP servers. CLI, IDE extension, and desktop app share host configuration. A reliable connection names its transport, authentication source, timeouts, required status, enabled tools, and approval behavior before a workflow depends on it.
- 10 Read the guide↗
Extension / 15 min / Stable
Package repeatable work as skills
Skills package instructions, references, scripts, and optional assets. Codex discovers them through concise metadata and loads full instructions only when selected. Plugins distribute skills and optional MCP connections through configured marketplaces; list and review a marketplace before installing a named plugin.
- 11 Read the guide↗
Guardrails / 17 min / Mixed: hooks stable; rules experimental
Add guardrails with hooks and rules
Hooks run trusted command handlers at lifecycle events such as PreToolUse, PostToolUse, Stop, and SessionStart. Rules decide whether matching command prefixes are allowed, prompted, or forbidden outside the sandbox. Hooks are stable; rules remain experimental and the most restrictive matching decision wins.
- 12 Read the guide↗
Automation / 19 min / Stable core; custom-agent authoring may evolve
Scale from subagents to safe automation
Subagents protect the main thread from noisy exploration and can run independent read-heavy work in parallel. For non-interactive workflows, codex exec defaults to a read-only sandbox, streams progress to stderr, and prints the final message to stdout; JSONL and output schemas support machine consumers. GitHub Actions should use the official action and narrow privileges.
OpenAI Platform / API
OpenAI Platform / API notes
Companion architecture guidance for developers building directly with OpenAI APIs and SDKs.
- 13 Read the guide↗
Platform architecture / 9 min / Stable
Make Responses the system boundary
The Responses API is the recommended starting point for new OpenAI integrations. Treat it as an application boundary—not a thin text-generation wrapper—so messages, tool calls, tool results, and future input types remain explicit.
- 14 Read the guide↗
Platform architecture / 11 min / Stable
Give every tool a narrow contract
OpenAI tools can search, retrieve files, execute code, connect through MCP, or call your own functions. Reliability comes from the boundary around each action: a small schema, explicit authority, idempotency, and a result the model can interpret.
- 15 Read the guide↗
Platform architecture / 8 min / Stable
Treat schema as user experience
Structured Outputs can constrain model responses to a supplied JSON Schema. That removes a class of parsing failures, but it does not prove that values are true, useful, authorized, or safe to apply.
- 16 Read the guide↗
Platform architecture / 12 min / Stable
Choose who owns the agent loop
An agent plans, calls tools, carries state, and may hand work to specialists. The key architecture decision is not how many agents exist—it is who owns the run loop, tool policy, state, approvals, and trace.
- 17 Read the guide↗
Platform architecture / 10 min / Stable
Design Realtime as a live system
Realtime sessions are designed for low-latency live interactions. A production voice experience is more than streaming audio: it needs a transport chosen for the client, explicit session state, interruption behavior, tool latency budgets, and recovery from partial turns.
- 18 Read the guide↗
Platform architecture / 9 min / Stable
Keep model choice at the edge
The OpenAI model catalog changes over time. Product code should ask for a tested capability profile—quality, latency, modalities, tool support, and budget—then resolve that profile through configuration and evaluations.