CODEX COURSE / 18 CLI + 06 API + 32 MONTHLY
Build a dependable Codex operating system.
Move through the CLI curriculum, then use the honest monthly archive to connect API boundaries, multimodal systems, agents, Realtime, Codex, and app UI.
Enter the terminal safely
Install, authenticate, launch in the correct repository, and choose authority before asking Codex to act.
- 01Install Codex and prove the toolchainA working Codex CLI installation with a recorded version and a repeatable diagnostic path.
- 02Choose authentication without leaking credentialsAn authenticated CLI whose account, billing boundary, and local credential storage are understood.
- 03Run the first repository session like an engineerA scoped first task completed in the intended repository with visible verification.
- 04Set authority before autonomyA permission profile matched to task impact, with no accidental full-access default.
Make the work legible and repeatable
Control a live session, encode durable guidance, configure by scope, and turn changes into reviewable evidence.
- 05Control a long-running CLI sessionA session that remains legible and steerable across planning, implementation, and review.
- 06Make repository knowledge durable with AGENTS.mdA concise, verified AGENTS.md chain that teaches Codex how this repository is built and checked.
- 07Plan Codex work by model, effort, and scopeA continuity-first Codex plan with an explicit model role, supported native effort, unchanged permission boundary, live-catalog check, and a safe fallback.
- 08Turn changes into reviewable evidenceA repeatable change-test-diff-review loop with prioritized findings and an explicit acceptance decision.
Extend, govern, and automate
Connect MCP, package skills, add guardrails, then scale independent work into subagents and safe CI.
- 09Connect external systems through MCPA verified MCP connection with a narrow tool surface and explicit startup and approval policy.
- 10Package repeatable work as skillsA narrow, testable skill with a clear trigger and a justified distribution path.
- 11Add guardrails with hooks and rulesA reviewed hook and a tested command rule that improve control without pretending to be a complete security boundary.
- 12Scale from subagents to safe automationA bounded parallel workflow and a least-privilege automation path with machine-readable evidence.
Run Codex as an observable system
Complete the CLI curriculum with headless execution, JSONL, saved-session lifecycle, Cloud tasks, sandbox policy tests, diagnostics, features, and completions.
- 13Run repeatable headless work with codex execA headless Codex job whose workspace, authority, exit status, artifacts, and retry behavior are explicit.
- 14Stream JSONL and constrain the final resultAn automation boundary that parses JSONL safely and validates one final typed result before acting.
- 15Resume, fork, archive, and restore Codex sessionsA saved-session workflow with clear lineage, reversible cleanup, and no accidental permanent deletion.
- 16Review Codex Cloud tasks before applying them locallyA remote-task workflow that preserves attempt identity, local review, and a reversible apply step.
- 17Test commands in the sandbox and audit execpolicyA repeatable permission test that distinguishes sandbox enforcement from command-policy decisions.
- 18Diagnose Codex, inspect features, and generate completionsA diagnostic procedure that identifies the failing layer and changes only the intended feature or shell integration.
Build directly on the OpenAI Platform
The original API architecture notes remain available as a separate archive and are not part of the 18-lesson CLI curriculum.
- A01Make Responses the system boundaryA request layer that can change models without changing your product contract.
- A02Give every tool a narrow contractA tool layer whose side effects can be reviewed, retried, and revoked.
- A03Treat schema as user experienceTyped model output that enters product code through a deliberate validation gate.
- A04Choose who owns the agent loopA bounded multi-step workflow with a named controller and stop conditions.
- A05Design Realtime as a live systemA realtime architecture tested against actual networks, voices, and interruption patterns.
- A06Keep model choice at the edgeA deployment that can adopt a new model through evidence and configuration rather than a rewrite.
MONTHLY TECHNICAL ARCHIVE / 32 ISSUES
Thirty-two retrospective engineering issues.
A source-checked path from API boundaries and multimodal systems to agents, Realtime, Codex, and ChatGPT app UI.
- ISSUES
- 32
- RANGE
- 2024—26
- LANG
- 03
RETROSPECTIVE / SOURCE-CHECKED
12 ISSUES
- 2024 / 01 API
Make the API request a product boundary
Start with one server-owned adapter for authentication, request IDs, timeouts, and normalized errors instead of calling the platform throughout the UI.
- 2024 / 02 PROMPTS
Version prompts like application code
Separate durable developer instructions from user input, give the task an explicit output contract, and keep prompt changes reviewable.
- 2024 / 03 MODELS
Route by capability, not by a fashionable model name
Describe each workload by modality, tool support, latency, quality, and budget, then resolve that profile to a deployable model in configuration.
- 2024 / 04 DATA
Use schema as the output contract
Structured Outputs reduce parsing ambiguity, but product code must still handle refusals, incomplete results, and domain-invalid values.
- 2024 / 05 TOOLS
Give every function tool a narrow contract
A tool definition expresses callable intent; authenticated server code must own validation, execution, idempotency, and the returned result.
- 2024 / 06 UX
Design streaming as a state machine
A useful stream distinguishes start, typed deltas, tool activity, completion, cancellation, and failure rather than appending arbitrary text.
- 2024 / 07 VISION
Treat image understanding as evidence extraction
Define what the model may infer from an image, preserve the original asset reference, and separate observation from downstream decisions.
- 2024 / 08 MEDIA
Put image generation behind an asset pipeline
Separate prompt intent, generation request, moderation state, asset storage, metadata, and editorial acceptance into observable stages.
- 2024 / 09 AUDIO
Build transcription around timestamps and uncertainty
Treat transcription as a media-processing job with upload validation, language context, segmentation, speaker policy, and correction workflow.
- 2024 / 10 AUDIO
Design synthetic speech as a disclosed interface
Choose voice, format, chunking, playback, and interruption behavior as product decisions, then disclose that the voice is AI-generated.
- 2024 / 11 RETRIEVAL
Separate retrieval from generation
Embeddings support semantic comparison; a production retrieval layer also needs chunk ownership, metadata filters, freshness, citations, and deletion.
- 2024 / 12 OPERATIONS
Move tolerant workloads to batch processing
Batch work needs stable custom identifiers, immutable input manifests, per-item status, result reconciliation, and bounded replay.
RETROSPECTIVE / SOURCE-CHECKED
12 ISSUES
- 2025 / 01 RESPONSES
Use Responses as the agentic application boundary
Typed input and output items let messages, reasoning, tool calls, and tool results remain distinct across a multi-step request.
- 2025 / 02 STATE
Choose conversation state explicitly
Decide whether the application resends history, chains response identifiers, or uses a conversation resource, and make that choice visible in data policy.
- 2025 / 03 TOOLS
Treat web search as cited retrieval
Search results are volatile evidence: preserve source URLs, distinguish retrieval time from event time, and show citations near claims.
- 2025 / 04 RETRIEVAL
Build file search with ownership and freshness
A hosted retrieval tool still requires corpus governance: ingestion status, metadata, access filters, citations, refresh, and deletion.
- 2025 / 05 TOOLS
Use code execution as a disposable compute cell
Send bounded inputs, define expected artifacts, and validate outputs outside the sandbox before they enter business workflows.
- 2025 / 06 ASYNC
Make long-running responses an asynchronous job
Background work needs a job identifier, polling or streaming policy, cancellation, expiry, idempotent consumption, and a user-visible status.
- 2025 / 07 SAFETY
Insert approval at the side-effect boundary
Classify tools by impact and pause before external messages, purchases, destructive writes, credential use, or privilege changes.
- 2025 / 08 MCP
Treat MCP servers as external principals
Inventory server identity, transport, authentication, exposed tools, data returned, approvals, and failure behavior before enabling it.
- 2025 / 09 AGENTS
Name the owner of the agent loop
The controller must own turns, tools, state, approvals, stop conditions, and traces; specialists receive narrow tasks and typed results.
- 2025 / 10 AGENTS
Make every handoff a typed delegation
A handoff carries one goal, bounded context, allowed tools, authority, deadline, output shape, and the next owner.
- 2025 / 11 OBSERVE
Trace decisions without logging secrets
Connect run, turn, model, tool, handoff, approval, latency, usage, and terminal outcome with stable correlation identifiers.
- 2025 / 12 EVALS
Make evaluation the release gate
Define representative inputs, human-readable criteria, automated graders where appropriate, and a baseline before changing the system.
RETROSPECTIVE / SOURCE-CHECKED
08 ISSUES
- 2026 / 01 REALTIME
Design Realtime as a live distributed system
Transport, session configuration, turn detection, interruption, tools, reconnect, and terminal states jointly define the experience.
- 2026 / 02 REALTIME
Keep browser Realtime credentials ephemeral
A server-authenticated session bootstrap lets the browser establish media transport without receiving the long-lived platform key.
- 2026 / 03 CODEX
Start Codex in a bounded repository
The working directory, task, sandbox, approval policy, and definition of done should be explicit before the coding agent edits files.
- 2026 / 04 CODEX
Encode repository truth in AGENTS.md
Durable guidance should name architecture boundaries, commands, conventions, and verification without replacing the current task.
- 2026 / 05 CODEX
Separate configuration, sandbox, and approval
Configuration chooses defaults, the sandbox enforces filesystem and network limits, and approvals govern exceptional authority.
- 2026 / 06 CODEX
Choose MCP for live access and Skills for repeatable method
MCP connects authenticated external tools and context; a Skill packages instructions, scripts, references, and a trigger for a reusable workflow.
- 2026 / 07 CODEX
Parallelize evidence, not conflicting writes
Subagents need independent ownership and result contracts; headless CI needs fixed permissions, machine-readable output, and isolated credentials.
- 2026 / 08 APPS
Add a UI to an MCP tool without moving trust into the browser
The MCP server owns tool truth and authorization; the embedded component renders state and requests actions through a narrow bridge.