Codex CLI Agentic Engineering from First Principles (Daniel Vaughan)（Z-Library）
Code
Codex CLI is the most comprehensive guide to agentic software engineering with OpenAI’s command-line coding agent. Across 32 chapters, you’ll move from first principles to advanced orchestration patterns — covering prompting, AGENTS.md configuration, MCP servers, hooks, skills, sub-agents, worktrees, CI/CD integration, security hardening, and enterprise deployment. Whether you’re a solo developer looking to multiply your output or an engineering lead rolling out agentic workflows across a team, this book gives you the mental models and practical techniques to work effectively with AI coding agents. Written by Daniel Vaughan, drawing on real-world experience and community insights, every chapter includes learning objectives, worked examples, and hands-on exercises.
8
Views
Registered users can read the full content for free
Register as a Gaohf Library member to read the complete e-book online for free and enjoy a better reading experience.
Page
1
(This page has no text content)
Page
2
Codex CLI Agentic Engineering from First Principles Daniel Vaughan This book is available at https://leanpub.com/codex-cli This version was published on 2026-05-24 This is a Leanpub book. Leanpub empowers authors and publishers with the Lean Publishing process. Lean Publishing is the act of publishing an in-progress ebook using lightweight tools and many iterations to get reader feedback, pivot until you have the right book and build traction once you do. © 2026 Daniel Vaughan
Page
3
Contents Copyright and Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i Disclaimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii I Started This on a Train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii What Changed My Mind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii Who This Book Is For . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv What You Won’t Find Here . . . . . . . . . . . . . . . . . . . . . . . . . . . v How This Book Is Organised . . . . . . . . . . . . . . . . . . . . . . . . . . vi A Note on Version Currency . . . . . . . . . . . . . . . . . . . . . . . . . . vii How to Use This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Getting Your Bearings . . . . . . . . . . . . . . . . . . . . . ix Chapter 1. What Is Codex CLI? . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Before Codex: A Brief History . . . . . . . . . . . . . . . . . . . . . . . . . . 1 The Problem with Autocomplete . . . . . . . . . . . . . . . . . . . . . . . . 4 The 2026 Agentic Landscape . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Defining Codex CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Why the Terminal Matters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 The Core Proposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Chapter 2. Getting Started with Codex CLI . . . . . . . . . . . . . . . . . . 19 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 The Bigger Picture: Four Surfaces, One Agent . . . . . . . . . . . . . . . 19 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Page
4
CONTENTS Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Your First Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Interactive REPL vs. codex exec . . . . . . . . . . . . . . . . . . . . . . . 24 Where Configuration Lives . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Chapter 3. What’s New in Codex CLI . . . . . . . . . . . . . . . . . . . . . . . 27 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 The Three Themes of 2026 . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 The Model Landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Approval Mode Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 New CLI Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Enterprise Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Staying Current . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Chapter 4. Benchmarks and Real-World Performance . . . . . . . . . . . 40 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 The Benchmark Landscape . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 SWE-bench: Gold Standard to Cautionary Tale . . . . . . . . . . . . . . 43 Terminal-Bench 2.0: CLI-First Benchmarking . . . . . . . . . . . . . . . . 45 The Scaffolding Effect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 What the Numbers Actually Mean for Your Team . . . . . . . . . . . . . 48 Running Your Own Benchmarks . . . . . . . . . . . . . . . . . . . . . . . . 50 April 2026 Benchmarks: CocoaBench, HiL-Bench, and AAR . . . . . . . 52 SlopCodeBench: Measuring Quality, Not Just Completion . . . . . . . . 55 The Benchmark Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 The Other Side of Benchmarks: Agent Code Quality in Production . . 58 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Chapter 5. Competing Tools and When to Use Each . . . . . . . . . . . . . 63 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 The Decision Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Claude Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Page
5
CONTENTS Gemini CLI (Deprecated, Sunset 18 June 2026) . . . . . . . . . . . . . . . 72 OpenCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 GitHub Copilot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Kiro CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Grok Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Desktop Workstations: Codexia and the GUI Wrapper Trend . . . . . . 80 Zed 1.0 Agent Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Google Antigravity 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 VS Code Multi-Agent Architecture . . . . . . . . . . . . . . . . . . . . . . 85 The Multi-Tool Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Chapter 6. Codex in the Wild: Interfaces and Community . . . . . . . . . 93 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Usage Limits: The Hidden Variable . . . . . . . . . . . . . . . . . . . . . . 94 What the Benchmarks Actually Tell You . . . . . . . . . . . . . . . . . . . 95 The Core Personality Difference . . . . . . . . . . . . . . . . . . . . . . . . 96 Practical Handoff Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 The Power Stack: Using Both . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Team Adoption Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Interfaces: Desktop, CLI, and IDE . . . . . . . . . . . . . . . . . . . . . . . 99 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Foundations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Chapter 7. Prompting Codex CLI Effectively . . . . . . . . . . . . . . . . . . 107 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Why Codex CLI Prompting Is Different . . . . . . . . . . . . . . . . . . . . 107 The Anatomy of an Effective Prompt . . . . . . . . . . . . . . . . . . . . . 108 Task Scoping and Reasoning Effort . . . . . . . . . . . . . . . . . . . . . . 109 Iterative Prompting and Mid-Session Corrections . . . . . . . . . . . . . 111 Prompt Patterns for Common Tasks . . . . . . . . . . . . . . . . . . . . . 112 Moving Durable Context Out of Prompts . . . . . . . . . . . . . . . . . . 113 Output Control: Shaping How the Agent Communicates . . . . . . . . . 114 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Page
6
CONTENTS Chapter 8. AGENTS.md: Patterns and Pitfalls . . . . . . . . . . . . . . . . . 123 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 What AGENTS.md Is and How Codex CLI Reads It . . . . . . . . . . . . . 124 Essential Sections: Commits, Testing, Style . . . . . . . . . . . . . . . . . 128 Project-Specific Context: What to Include and Omit . . . . . . . . . . . 131 Common Mistakes and How They Manifest . . . . . . . . . . . . . . . . . 132 AGENTS.md for Monorepos and Multi-Service Repos . . . . . . . . . . . 134 Testing and Validating Your AGENTS.md . . . . . . . . . . . . . . . . . . . 138 What Not to Do: Common AGENTS.md Mistakes . . . . . . . . . . . . . 138 Starter Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 The File Map Pattern: Addressing the Navigation Failure Mode . . . . . 145 Production AGENTS.md Patterns: The openai/codex Case Study . . . 147 Empirical Adoption Data: What 2,926 Repositories Reveal . . . . . . . . 149 The .md File Ecosystem: Beyond AGENTS.md . . . . . . . . . . . . . . . 152 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Chapter 9. Approval Modes and Trust Boundaries . . . . . . . . . . . . . . 156 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 The Trust Model: What Codex CLI Can Touch . . . . . . . . . . . . . . . 156 The Four Approval Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 Auto-Approve: When to Use It and When Not To . . . . . . . . . . . . . 160 Sandboxing: Filesystem and Network Restrictions . . . . . . . . . . . . . 162 Kernel-Level vs. Hook-Based Sandboxing . . . . . . . . . . . . . . . . . . 163 Approval Mode Strategy for Teams . . . . . . . . . . . . . . . . . . . . . . 165 Programmatic Approval with PermissionRequest Hooks . . . . . . . . . 176 Guardian Failure Modes and Escalation Patterns . . . . . . . . . . . . . . 179 Deny-Read Glob Policies (v0.122.0) . . . . . . . . . . . . . . . . . . . . . . 186 Smart Approvals: Adaptive Command Policies (v0.120.0) . . . . . . . . . 187 CI Reproducibility Flags (v0.122.0) . . . . . . . . . . . . . . . . . . . . . . . 191 Granular Approval Policies (v0.122–v0.125) . . . . . . . . . . . . . . . . . . 192 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Chapter 10. Debugging and Diagnosing Agent Failures . . . . . . . . . . . 201 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Reading the Session Transcript . . . . . . . . . . . . . . . . . . . . . . . . . 202 Using Approval Mode as a Diagnostic . . . . . . . . . . . . . . . . . . . . . 203 Diagnosing AGENTS.md Failures . . . . . . . . . . . . . . . . . . . . . . . . 204
Page
7
CONTENTS Testing Commands Under the Sandbox . . . . . . . . . . . . . . . . . . . 206 Context Overflow Symptoms . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Recovering a Runaway Session . . . . . . . . . . . . . . . . . . . . . . . . . 208 Structured Logging and --debug . . . . . . . . . . . . . . . . . . . . . . . 209 Model Catalog Introspection with codex debug models . . . . . . . . 211 Codex Journal: Conversation History as Analysable Data (Preview, PR #20199) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Detecting Specification Drift with SLUMP . . . . . . . . . . . . . . . . . . 213 A Diagnostic Workflow Checklist . . . . . . . . . . . . . . . . . . . . . . . 214 The Three-Level Observability Stack . . . . . . . . . . . . . . . . . . . . . 215 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Chapter 11. Model Selection and Reasoning Effort . . . . . . . . . . . . . . 220 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 The Available Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 Multi-Provider Resilience . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 Reasoning Effort: The Second Knob . . . . . . . . . . . . . . . . . . . . . . 236 Task Taxonomy: Matching Model and Effort to Task . . . . . . . . . . . 242 Cost Modelling: Estimating Monthly Spend . . . . . . . . . . . . . . . . . 246 GPT-5.5 Prompting Patterns: Outcome-First Instructions . . . . . . . . 249 Model Selection in Automated Pipelines . . . . . . . . . . . . . . . . . . . 253 Part 2 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Beyond Local Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 The Extension Stack . . . . . . . . . . . . . . . . . . . . . . . 263 Chapter 12. MCP: Consuming and Serving . . . . . . . . . . . . . . . . . . . 264 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 MCP in 60 Seconds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 What MCP Is (and What It Is Not) . . . . . . . . . . . . . . . . . . . . . . . 266 The Architecture: Hosts, Clients, and Servers . . . . . . . . . . . . . . . . 266 MCP and A2A: Complementary Protocol Layers . . . . . . . . . . . . . . 267 MCP outputSchema: Typed Tool Outputs . . . . . . . . . . . . . . . . . . 268 MCP Tool Annotations: Risk Vocabulary for Approval Policy . . . . . . . 268 Parallel Tool Calls and External Event Injection . . . . . . . . . . . . . . . 270
Page
8
CONTENTS Connecting Codex CLI to MCP Servers . . . . . . . . . . . . . . . . . . . . 271 Connecting to Common Servers (GitHub, Browser, Database) . . . . . 273 The Context Cost of MCP: What Gets Loaded . . . . . . . . . . . . . . . . 274 Enterprise MCP: Authentication, Scoping, and Restrictions . . . . . . . 275 MCP Elicitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 Common MCP Gotchas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 Building a Simple MCP Server . . . . . . . . . . . . . . . . . . . . . . . . . 279 Serving MCP from Codex . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 Codex CLI as an MCP Server . . . . . . . . . . . . . . . . . . . . . . . . . . 281 Beyond Read-Only: Write-Back Integration . . . . . . . . . . . . . . . . . 284 Ticketing System Integration (Jira, Linear) . . . . . . . . . . . . . . . . . . 284 Communication Platform Integration (Slack, Teams) . . . . . . . . . . . 285 Bidirectional Database Patterns . . . . . . . . . . . . . . . . . . . . . . . . 286 Sandbox-Aware MCP Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 MCP Resilience and Governance Hardening . . . . . . . . . . . . . . . . . 289 Safety Boundaries for Write-Enabled Agents . . . . . . . . . . . . . . . . 290 Remote MCP Executor Stack . . . . . . . . . . . . . . . . . . . . . . . . . . 293 Docker MCP Toolkit: Containerised Tool Servers . . . . . . . . . . . . . 295 Remote HTTP MCP Transport . . . . . . . . . . . . . . . . . . . . . . . . . 298 MCP OAuth 2.1: Authenticating Remote Tool Servers . . . . . . . . . . . 300 MCP Turn Metadata (PR #21219) . . . . . . . . . . . . . . . . . . . . . . . . 302 Context Fragments as MCP Injection Points . . . . . . . . . . . . . . . . . 304 MCP Debugging and Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . 306 Parallel Tool Calls (v0.121.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 Sandbox-State Metadata (v0.125.0) . . . . . . . . . . . . . . . . . . . . . . 309 Building Custom MCP Servers: TypeScript and Python Patterns . . . . 311 MCP Namespace Cleanup (PR #21442) . . . . . . . . . . . . . . . . . . . . 315 OpenAI Developer Docs MCP Server . . . . . . . . . . . . . . . . . . . . . 316 AWS MCP Server GA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 Chapter 13. Hooks: Intercepting the Agent Lifecycle . . . . . . . . . . . . 324 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 The Hook System: Overview and Events . . . . . . . . . . . . . . . . . . . 324 SessionStart: Configuring the Environment . . . . . . . . . . . . . . . . . 331 UserPromptSubmit: Shaping Input Before the Agent Acts . . . . . . . . 332 PreToolUse: Intercepting Shell Commands . . . . . . . . . . . . . . . . . 334 PostToolUse: Observing Without Blocking . . . . . . . . . . . . . . . . . . 334
Page
9
CONTENTS Stop: Teardown and Cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Writing Robust Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 Real Hook Patterns: Enforcement, Audit, and Notification . . . . . . . . 338 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 Chapter 14. The Skills Ecosystem: Using and Writing Skills . . . . . . . . 356 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 Part 1: The Consumer’s View: Using and Browsing the Ecosystem . . . 357 Part 2: The Producer’s View: Writing Your Own Skills . . . . . . . . . . . 363 The Customisation Stack: Five Layers of Agent Configuration . . . . . 373 The Plugin System: From Skills to Distributable Packages . . . . . . . . 378 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 Scale and Automation . . . . . . . . . . . . . . . . . . . . . . 392 Chapter 15. Context Window Management . . . . . . . . . . . . . . . . . . . 393 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 The Quadratic Growth Problem . . . . . . . . . . . . . . . . . . . . . . . . 394 Thread Resume and Fork: Preserving Context Without Restarting . . . 395 What Consumes Context (and What Doesn’t) . . . . . . . . . . . . . . . . 396 The /compact Command and Automatic Summarisation . . . . . . . . 398 Background Prefix Compaction . . . . . . . . . . . . . . . . . . . . . . . . 400 Sub-Agent Delegation as Context Management . . . . . . . . . . . . . . 400 Strategies for Large Codebases . . . . . . . . . . . . . . . . . . . . . . . . . 401 Monitoring Context Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 Context Compaction Architectures: Cross-Tool Comparison . . . . . . 404 The Model Lineage Context Compaction Breakthrough . . . . . . . . . 407 Plan Mode and Fresh-Context Implementation . . . . . . . . . . . . . . . 408 Context Fragments Architecture . . . . . . . . . . . . . . . . . . . . . . . . 409 Prompt Caching: Economics of Long Sessions . . . . . . . . . . . . . . . 410 Persistent Context: The Two-Phase Memory Pipeline . . . . . . . . . . 412 MCP Memory Servers: Persistent Cross-Session Context . . . . . . . . 413 The Built-In Memory Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . 414 Memory Lifecycle Management . . . . . . . . . . . . . . . . . . . . . . . . 416 Team Memory: The Gap Beyond Individual Recall . . . . . . . . . . . . . 417 Context Failure Modes: A Taxonomy . . . . . . . . . . . . . . . . . . . . . 418
Page
10
CONTENTS ThreadStore and Session Persistence (v0.129.0-alpha.2, pre-release) . 421 GPT-5.5 Compaction Failures: Diagnosis and Mitigation . . . . . . . . . 423 Strategic Forgetting: Application-Level Context Management . . . . . 425 Specification Drift in Long-Context Sessions . . . . . . . . . . . . . . . . 427 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 Chapter 16. Sub-Agents and Parallel Execution . . . . . . . . . . . . . . . . 433 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 The Sub-Agent Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 The TOML Subagent Definition Format . . . . . . . . . . . . . . . . . . . 435 Task Decomposition: What to Parallelise . . . . . . . . . . . . . . . . . . . 436 spawn_agents_on_csv: Fan-Out Patterns . . . . . . . . . . . . . . . . . 438 Aggregating Results and Handling Failures . . . . . . . . . . . . . . . . . 439 Path-Based Sub-Agent Addressing . . . . . . . . . . . . . . . . . . . . . . . 441 Beyond Built-In Subagents: External Swarm Orchestration . . . . . . . 445 Named Exec Environments: Per-Agent Sandbox Isolation (Proposed) . 448 Exec Policy Propagation to Sub-Agents . . . . . . . . . . . . . . . . . . . . 449 Cascade Thread Archive Lifecycle . . . . . . . . . . . . . . . . . . . . . . . 450 Agent Graph Store (#19229) . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 Multi-Agent v2 Depth Unlocking (#20180) . . . . . . . . . . . . . . . . . . 451 Multi-Agent V2 Fork Semantics Hardening (May 2026) . . . . . . . . . . 452 Multi-Agent Architecture Patterns Beyond Codex . . . . . . . . . . . . . 453 Known Failure Mode: MCP Process Tree Leak . . . . . . . . . . . . . . . 456 Metric Freedom: When to Use Multi-Agent vs Single-Agent . . . . . . 459 When Not to Parallelise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464 Chapter 17. Cost Management and Quota Strategy . . . . . . . . . . . . . . 465 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465 How Codex CLI quota works . . . . . . . . . . . . . . . . . . . . . . . . . . 466 Estimating Team Costs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 Configuring Cost Ceilings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 Monitoring and Alerting with Hooks . . . . . . . . . . . . . . . . . . . . . 478 Cost-Quality Decision Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . 479 Per-Reasoning-Effort Token Consumption . . . . . . . . . . . . . . . . . 481 Prompt Caching: the Largest Single Cost Lever . . . . . . . . . . . . . . 483 Context-Usage Visibility from Plan Mode . . . . . . . . . . . . . . . . . . 484
Page
11
CONTENTS Goal Mode: Cost-Aware Long-Horizon Tasks (v0.133 GA) . . . . . . . . 485 Bedrock Pricing as an Alternative to Direct API . . . . . . . . . . . . . . . 487 Token Compression: RTK and the Cost Impact . . . . . . . . . . . . . . . 487 On-Premises Cost: Dell AI Factory and GB10 Break-Even Analysis . . . 489 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492 Chapter 18. Multi-Agent Orchestration Patterns . . . . . . . . . . . . . . . 494 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494 The Three-Tier Orchestration Landscape . . . . . . . . . . . . . . . . . . 495 Pattern 1: Sequential Gated Chain . . . . . . . . . . . . . . . . . . . . . . . 497 Pattern 2: Parallel Worker Swarm . . . . . . . . . . . . . . . . . . . . . . . 498 Pattern 3: Wave-Based Hybrid . . . . . . . . . . . . . . . . . . . . . . . . . 499 Choosing the Right Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 Pattern 4: Cross-Model Review Loop . . . . . . . . . . . . . . . . . . . . . 503 Agentmaxxing: Human-Coordinated Cross-Vendor Parallelism . . . . 506 Conversation Branching as a Supervisor Pattern . . . . . . . . . . . . . . 507 Goal Mode: From Task Execution to Objective Tracking . . . . . . . . . 510 Debugging Orchestration Failures . . . . . . . . . . . . . . . . . . . . . . . 512 Orchestration Anti-Patterns to Avoid . . . . . . . . . . . . . . . . . . . . . 514 MultiAgentV2: Custom Roles and Thread Orchestration (v0.128.0) . . . 516 Remote-Control Command: External Orchestration of Running Ses- sions (v0.130.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 Pattern 5: Iterative Repair Loops (Review-Repair-Validate) . . . . . . . 521 Multi-Agent Desktop Workspaces . . . . . . . . . . . . . . . . . . . . . . . 525 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 Chapter 19. Worktrees and Isolated Execution . . . . . . . . . . . . . . . . 532 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 Git Worktrees: A Brief Recap . . . . . . . . . . . . . . . . . . . . . . . . . . 532 Why Worktrees Matter for Agentic Workflows . . . . . . . . . . . . . . . 533 One Agent, One Worktree: The Isolation Principle . . . . . . . . . . . . . 534 Worktrees in the Codex Desktop App . . . . . . . . . . . . . . . . . . . . . 537 CLI Worktree Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 Merging Agent Work Back to Main . . . . . . . . . . . . . . . . . . . . . . 540 Worktree Lifecycle in CI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 Worktree Workflow Patterns by Team Size . . . . . . . . . . . . . . . . . 545 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
Page
12
CONTENTS Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 Chapter 20. CI/CD Integration . . . . . . . . . . . . . . . . . . . . . . . . . . 548 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548 Running Codex CLI in Non-Interactive Mode . . . . . . . . . . . . . . . . 548 The openai/codex-action GitHub Action . . . . . . . . . . . . . . . . . . 549 Automated Code Review on Every PR . . . . . . . . . . . . . . . . . . . . . 550 Test Generation on Merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 Dependency Update Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 GitLab CI/CD Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 Analytics Pipeline: CI/CD Observability Layer . . . . . . . . . . . . . . . 555 Self-Healing CI/CD: From Observation to Autonomous Remediation . 557 Project-Level Skills: The codex-pr-body Pattern . . . . . . . . . . . . . . 561 Stacked PRs as a Review-Scaling Pattern . . . . . . . . . . . . . . . . . . . 561 Structured Output and Session Resume . . . . . . . . . . . . . . . . . . . 562 Safety Strategies for CI Agents . . . . . . . . . . . . . . . . . . . . . . . . . 563 Remote Sandbox Configuration: Hostname-Pattern Policies . . . . . . 563 Hermetic Execution Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . 565 Microsoft’s Agentic DevOps Playbook . . . . . . . . . . . . . . . . . . . . . 566 Non-Interactive Pipeline Patterns: exec, resume, and StructuredOutput568 codex exec CI/CD Patterns Reference . . . . . . . . . . . . . . . . . . . . 570 AutoLoop: Bounded Optimisation in CI . . . . . . . . . . . . . . . . . . . . 573 Empirical Evidence: What 33,000 Agentic PRs Reveal About Pipeline Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 CI/CD Session Reliability: WebSocket Keepalive and Remote Connec- tions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 Chapter 21. Security Hardening . . . . . . . . . . . . . . . . . . . . . . . . . . 581 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581 The Threat Model for Agentic Systems . . . . . . . . . . . . . . . . . . . . 582 Prompt Injection: Attack Patterns and Defences . . . . . . . . . . . . . . 583 Filesystem Restrictions and Sandboxing . . . . . . . . . . . . . . . . . . . 586 Network Allowlisting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 Secret Management for Agent Environments . . . . . . . . . . . . . . . . 604 Audit Logging and Observability . . . . . . . . . . . . . . . . . . . . . . . . 608 MCP as an Attack Surface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 Supply Chain Attacks: The Axios Incident and Binary Verification . . . 617
Page
13
CONTENTS Package Registry Compromises: PyPI and npm (April–May 2026) . . . 619 The TanStack Supply Chain Attack: npm Worm and Sandbox Defence (May 2026) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 Windows Sandbox Engineering: The Four-Layer Architecture . . . . . 621 Indirect AGENTS.md Injection: Supply-Chain Poisoning of Agent In- structions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622 Automated Security Tools: Claude Security and Cursor Security Review623 Model-Level Risks: The Goblin Incident and Reward Signal Leakage . 624 CVE-2026-26268 and Comment-and-Control: Spring 2026 Agent Vul- nerabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 Enterprise Defence-in-Depth: The Five-Layer Security Model . . . . . 627 Running Codex Safely: OpenAI’s Own Deployment Model . . . . . . . . 629 Empirical Security Findings: The Amplifying.ai Benchmark . . . . . . . 632 Compliance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 636 Offline Security Validation Tools . . . . . . . . . . . . . . . . . . . . . . . . 637 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642 Chapter 22. Enterprise Deployment . . . . . . . . . . . . . . . . . . . . . . . 644 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 Distributing config.toml at Scale . . . . . . . . . . . . . . . . . . . . . . . . 645 RBAC: Three Admin Roles and Access Control . . . . . . . . . . . . . . . 646 Managed Policies: requirements.toml . . . . . . . . . . . . . . . . . . . . . 647 AGENTS.override.md: Enforcing Policy Across Teams . . . . . . . . . . 654 Onboarding an Engineering Team . . . . . . . . . . . . . . . . . . . . . . . 656 Measuring ROI: Metrics That Work . . . . . . . . . . . . . . . . . . . . . . 657 Codex Cloud vs Self-Hosted . . . . . . . . . . . . . . . . . . . . . . . . . . . 658 Multi-Cloud Provider Strategy . . . . . . . . . . . . . . . . . . . . . . . . . 659 Dell AI Factory: On-Premises Codex Deployment . . . . . . . . . . . . . 662 Agent Identity Authentication . . . . . . . . . . . . . . . . . . . . . . . . . 664 Governance Frameworks for Agentic AI . . . . . . . . . . . . . . . . . . . 665 Governance APIs and Data Pipelines . . . . . . . . . . . . . . . . . . . . . 670 The Compliance API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672 Rollout Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674 Remote Connections: Operational Guide . . . . . . . . . . . . . . . . . . 675 Hooks GA and Enterprise Governance Mapping . . . . . . . . . . . . . . 676 External Governance Frameworks: Microsoft AGT and Forrester ADS 676 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
Page
14
CONTENTS Chapter 23. Testing and Evaluation Strategy for Agentic Workflows . . 696 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696 What Makes a Test Suite Agent-Friendly . . . . . . . . . . . . . . . . . . . 697 Designing for Agent Execution . . . . . . . . . . . . . . . . . . . . . . . . . 698 The Feedback Signal Problem . . . . . . . . . . . . . . . . . . . . . . . . . . 700 Using Codex CLI to audit your test suite . . . . . . . . . . . . . . . . . . . 701 Evaluation Beyond Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . 702 Building an Evaluation Harness . . . . . . . . . . . . . . . . . . . . . . . . . 704 TDD as an Agent Feedback Loop . . . . . . . . . . . . . . . . . . . . . . . . 706 The 4-File Durable Memory Pattern for Long-Horizon Evaluation . . . 708 Agent Test Quality: TheOver-Mocking Problem and Review Benchmarks709 April 2026 Evaluation Frameworks: CocoaBench, HiL-Bench, and AAR 712 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714 Specialised Workflows . . . . . . . . . . . . . . . . . . . . . 716 Chapter 24. AI Code Review . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717 Why AI Code Review Works (and Where It Doesn’t) . . . . . . . . . . . . 717 Configuring Codex for Code Review . . . . . . . . . . . . . . . . . . . . . . 721 The /review Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723 PR Integration: Automated Review on Every PR . . . . . . . . . . . . . . 724 Structured Output Code Review with codex exec --output-schema 727 Writing Review Checklists in AGENTS.md . . . . . . . . . . . . . . . . . . 730 Human-AI Review Collaboration Patterns . . . . . . . . . . . . . . . . . . 731 The Review-Fix Loop: A Three-Level Maturity Model . . . . . . . . . . . 732 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735 Chapter 25. Frontend Engineering with React and TypeScript . . . . . . 739 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739 Frontend-Specific AGENTS.md Configuration . . . . . . . . . . . . . . . 739 Component Generation and Scaffolding . . . . . . . . . . . . . . . . . . . 742 Test Generation for React Components . . . . . . . . . . . . . . . . . . . 743 The Explorer/Worker Sub-Agent Pattern . . . . . . . . . . . . . . . . . . 745 Accessibility Audit Automation . . . . . . . . . . . . . . . . . . . . . . . . . 746 Design-to-Code Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
Page
15
CONTENTS Codex Browser Use: Visual Verification . . . . . . . . . . . . . . . . . . . 750 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752 Chapter 26. Python TeamWorkflows . . . . . . . . . . . . . . . . . . . . . . 754 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754 Python-Specific AGENTS.md . . . . . . . . . . . . . . . . . . . . . . . . . . 754 Pytest Integration and Test Generation . . . . . . . . . . . . . . . . . . . 757 Type Hints and Docstring Automation . . . . . . . . . . . . . . . . . . . . 760 uv, ruff, and Modern Python Toolchain . . . . . . . . . . . . . . . . . . . . 761 Data Pipeline Code Generation . . . . . . . . . . . . . . . . . . . . . . . . . 764 Multi-Service Python Workflows . . . . . . . . . . . . . . . . . . . . . . . 766 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768 Chapter 27. Web Search and Research Agents . . . . . . . . . . . . . . . . . 770 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770 Enabling Web Search in Codex CLI . . . . . . . . . . . . . . . . . . . . . . 770 Research-to-Code Workflows . . . . . . . . . . . . . . . . . . . . . . . . . 773 Dependency Research and Evaluation . . . . . . . . . . . . . . . . . . . . 774 Staying Current with API Changes . . . . . . . . . . . . . . . . . . . . . . . 775 Knowledge-Augmented Agents: MCP Knowledge Servers . . . . . . . . 776 Combining Web Search with Sub-Agents . . . . . . . . . . . . . . . . . . 779 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781 Chapter 28. Codebase Migration . . . . . . . . . . . . . . . . . . . . . . . . . 783 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783 Why Codex CLI Excels at Migration Work . . . . . . . . . . . . . . . . . . 783 Planning the Migration with Codex CLI . . . . . . . . . . . . . . . . . . . . 784 Incremental Migration Patterns . . . . . . . . . . . . . . . . . . . . . . . . 786 Validation Strategies During Migration . . . . . . . . . . . . . . . . . . . . 787 Migrating from Claude Code to Codex CLI . . . . . . . . . . . . . . . . . . 789 Framework and Language Version Migrations . . . . . . . . . . . . . . . 793 External Agent Migration: The Detect/Import API . . . . . . . . . . . . 794 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
Page
16
CONTENTS Architecture and Vision . . . . . . . . . . . . . . . . . . . 801 Chapter 29. The Agents SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802 What the Agents SDK Adds . . . . . . . . . . . . . . . . . . . . . . . . . . . 802 The SDK Architecture: Agents, Handoffs, Tools, and Guardrails . . . . 803 Two Orchestration Patterns: Handoffs vs Agents-as-Tools . . . . . . . 804 State Persistence: Four Strategies . . . . . . . . . . . . . . . . . . . . . . . 807 Function Tools and Hosted Tools . . . . . . . . . . . . . . . . . . . . . . . 808 Codex CLI as an MCP Server in SDK Pipelines . . . . . . . . . . . . . . . 809 Building a Designer-Developer-Tester Pipeline . . . . . . . . . . . . . . . 811 Tracing and Observability . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814 SDK vs CLI: Choosing the Right Level . . . . . . . . . . . . . . . . . . . . . 815 TypeScript SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816 Cross-Language Orchestration and Heterogeneous Model Routing . . 820 Python SDK MessageRouter: Concurrent Multi-Turn Streaming . . . . 822 The openai-codex Python SDK: Embedding the Agent Runtime . . . . 823 The OpenAI Cookbook: Canonical Tutorial Path . . . . . . . . . . . . . . 826 Streaming and Approval Pauses . . . . . . . . . . . . . . . . . . . . . . . . 827 Model Configuration and Routing . . . . . . . . . . . . . . . . . . . . . . . 829 Recent SDK Developments (April–May 2026) . . . . . . . . . . . . . . . . 830 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832 Chapter 30. Agentic Primitives Compared . . . . . . . . . . . . . . . . . . . 833 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833 The Four Primitives: Agents, Handoffs, Tools, Guardrails . . . . . . . . 833 How Codex CLI Implements Each Primitive . . . . . . . . . . . . . . . . . 834 LangChain and LangGraph . . . . . . . . . . . . . . . . . . . . . . . . . . . 836 AutoGen and CrewAI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837 Google Gemini Agents and ADK . . . . . . . . . . . . . . . . . . . . . . . . 839 Choosing a Primitives Model . . . . . . . . . . . . . . . . . . . . . . . . . . 840 Codex CLI’s Custom Agent TOML in Practice . . . . . . . . . . . . . . . . 843 What Happens When You Type codex . . . . . . . . . . . . . . . . . . . . 845 Context Health Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . 846 Runtime Architecture: Remote Control and State Management . . . . 848 Extending the Primitives: Custom Agents in TOML vs Code . . . . . . . 850 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854
Page
17
CONTENTS Chapter 31. Harness Engineering for Long-Running Agents . . . . . . . . 856 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856 What Harness Engineering Is . . . . . . . . . . . . . . . . . . . . . . . . . . 857 The WORKFLOW.md Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . 860 State Persistence Across Agent Runs . . . . . . . . . . . . . . . . . . . . . 861 Error Recovery and Resumption . . . . . . . . . . . . . . . . . . . . . . . . 862 The Proof-of-Work Principle . . . . . . . . . . . . . . . . . . . . . . . . . . 863 Symphony: A Harness in Practice . . . . . . . . . . . . . . . . . . . . . . . 864 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880 Chapter 32. The Agentic Engineering Pod . . . . . . . . . . . . . . . . . . . 882 Learning Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882 Section 1: Why Three Roles? . . . . . . . . . . . . . . . . . . . . . . . . . . 883 Section 2: The Context Architect: Human Role . . . . . . . . . . . . . . . 884 Section 3: The Value Engineer: Human Role . . . . . . . . . . . . . . . . 888 Section 4: The Quality Engineer: Human Role . . . . . . . . . . . . . . . 892 Section 5: The Pod in Practice: A Feature Lifecycle . . . . . . . . . . . . 896 Section 6: The Agentic Pod Principles . . . . . . . . . . . . . . . . . . . . 899 Section 7: Failure Modes and Pod Anti-Patterns . . . . . . . . . . . . . . 900 Section 8: Distributing the Pod with Plugins . . . . . . . . . . . . . . . . 903 Metric Freedom and Benchmark Failure Modes: Tools for the Pod . . . 905 Closing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907 Exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907 Conclusion: The Agentic Engineer . . . . . . . . . . . . . . . . . . . . . . . . 909 A Note from the Author, Or Rather, the Tool . . . . . . . . . . . . . . . . . . 913 How This Book Was Made . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913 What This Means for You . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914 The Book as Artefact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915 An Invitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915 A Face for the Voice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916 Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918 1. Research Papers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918 2. OpenAI Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919 3. Standards and Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923 4. Frameworks and Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . 924 5. Benchmarks and Evaluations . . . . . . . . . . . . . . . . . . . . . . . . 927
Page
18
6. Developer Tooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927 7. Industry Reports and Blogs . . . . . . . . . . . . . . . . . . . . . . . . . . 930
Page
19
Copyright and Trademarks Codex CLI: Agentic Engineering from First Principles Copyright © 2026 Daniel Vaughan. All rights reserved. Trademarks OpenAI, Codex, GPT-4, o3, o4-mini, and the OpenAI logo are trademarks of OpenAI OpCo, LLC. Claude and Claude Code are trademarks of Anthropic PBC. GitHub, GitHub Copilot, and TypeScript are trademarks or registered trademarks of Microsoft Corporation. Cursor is a trademark of Anysphere, Inc. React is a trademark of Meta Platforms, Inc. Python is a trademark of the Python Software Foundation. Go, Google, Google Cloud, and the Google Developer Expert logo are trademarks of Google LLC. HCLTech is a trademark of HCL Technologies Limited. O’Reilly is a trade- mark of O’Reilly Media, Inc. Slack is a trademark of Salesforce, Inc. Jira is a trademark of Atlassian Pty Ltd. All other trademarks and registered trademarks are the property of their respective owners. Rather than put a trademark symbol in every occurrence of a trademarked name, we state that we are using the names in an editorial fashion only, and to the benefit of the trademark owner, with no intention of infringement of the trademark. Disclaimer This book is an independent publication and is not affiliated with, nor has it been authorized, sponsored, or otherwise approved by OpenAI, Anthropic,
Page
20
Copyright and Trademarks ii Microsoft, or any other trademark owner mentioned herein. The information in this book is provided on an “as is” basis, without warranty. While every precaution has been taken in the preparation of this book, the author shall have no liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the instructions contained in this book or by the software and hardware products described in it.
The above is a preview of the first 20 pages. Register to read the complete e-book.
AI Reading Assistant
Whole-book reading guide from stratified index samples; jump to passages in the text
AI guide
【One-Line Pitch】
A practical field guide to working with OpenAI's Codex CLI as a real engineering tool rather than a novelty: it builds mental models for prompting, configuration, safety, and orchestration, then scales them to teams. Best for developers and engineering leads who already write code and want to multiply output without losing control of the repo.
【Book Arc】
- **Opening (~0%–13%)**: Frames the shift from autocomplete to agentic coding, situates Codex CLI in the 2026 tool landscape, and gets you installed, authenticated, and running a first session across its interfaces.
- **Early (~13%–25%)**: Builds the working fundamentals — effective prompting, AGENTS.md as durable project context, approval modes and trust boundaries, and how to diagnose agent failures from session transcripts.
- **Early–Middle (~25%–38%)**: Extends the agent's reach through model/reasoning-effort selection and MCP servers, including connecting common services, building simple servers, and enterprise authentication and governance.
- **Middle (~38%–46%)**: Covers lifecycle control and scale — hooks that intercept agent events, the skills ecosystem and plugin packaging, and context-window management with compaction and memory.
- **Middle–Late (~46%–54%)**: Moves into orchestration — sub-agents, parallel execution, multi-agent patterns, and Git worktrees for isolated execution.
- **Late–Ending (~54% onward)**: The excerpts thin out here; the blurb indicates CI/CD integration, security hardening, and enterprise deployment, but the excerpts do not cover those chapters in detail.
【Book Arc】 (reading-order map, continued as bullets)
- **Opening (~0%–13%)**: what Codex CLI is, why the terminal matters, and first-run setup.
- **Early (~13%–25%)**: prompting, AGENTS.md, approvals/sandboxing, debugging.
- **Middle (~25%–46%)**: MCP, hooks, skills, context management.
- **Late (~46%–54%)**: sub-agents, orchestration patterns, worktrees.
- **Ending (~54%+)**: CI/CD, security, enterprise rollout (per blurb; excerpts do not cover).
【Key Takeaways】
- **Agentic coding is a different discipline from autocomplete** (Opening): the book opens by arguing that the real shift is task delegation and supervision, not faster typing — which is why prompting, trust, and context get whole chapters.
- **AGENTS.md is the backbone of reliable behavior** (Early): durable project context (commits, testing, style, file maps) belongs in configuration, not repeated prompts; the book treats common failure modes and monorepo patterns as first-class.
- **Trust is a dial, not a switch** (Early): four approval modes plus filesystem/network sandboxing let you match autonomy to risk, with team-level strategies and hook-based programmatic approval for stricter control.
- **Failures are diagnosable** (Early): session transcripts, approval mode as a diagnostic, context-overflow symptoms, and structured logging turn "the agent went weird" into a checklist you can run.
- **Context is the scarce resource** (Middle): quadratic growth, compaction, thread resume/fork, sub-agent delegation, and memory pipelines are framed as engineering problems with architectures and failure taxonomies.
- **Extensibility has layers** (Middle): MCP servers, hooks, skills, and plugins form a customization stack — start with read-only integrations, then add write-back only behind explicit safety boundaries.
- **Parallelism must be earned** (Late): sub-agents and multi-agent patterns pay off for decomposable work, but the book is explicit about when not to parallelize and which orchestration anti-patterns to avoid.
- **Isolation prevents collisions** (Late): the "one agent, one worktree" principle keeps concurrent agents from stepping on each other's working tree.
【Reading Tips】
- Read Chapters 1–2 and 7–9 closely before touching anything else; prompting, AGENTS.md, and approval modes are the load-bearing skills everything later assumes.
- Skim the competing-tools chapter (Ch. 5) unless you're choosing a stack; its value is the decision framework, not the product tour.
- Treat MCP, hooks, and skills as a menu: pick the one integration your workflow actually needs and build it end-to-end rather than reading all three superficially.
- Expect version churn — the book cites specific releases and PR numbers, so verify flags against your installed version; the author flags version currency himself.
- Do the exercises in the context and orchestration chapters; those concepts (compaction, fan-out, worktrees) only click once you've hit a real failure.
【Coverage Limits】
The excerpts are dominated by the table of contents and early-to-middle chapters; CI/CD, security hardening, and enterprise deployment are named in the blurb but not detailed here, so this guide's late-book picture is thinner than the front half.
Passage locations
Page 3
or . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv What You Won’t Find Here . . . . . . . . . . . . . . . . . . . . . . . . . . . v How This...
View in text
Page 5
. . . . . . . . . 93 Usage Limits: The Hidden Variable . . . . . . . . . . . . . . . . . . . . . . 94 What the Benchmarks Actually Tell You . . . . . . . . ....
View in text
Page 8
ting to Common Servers (GitHub, Browser, Database) . . . . . 273 The Context Cost of MCP: What Gets Loaded . . . . . . . . . . . . . . . . 274 Enterprise MCP...
View in text
Page 10
ion Persistence (v0.129.0-alpha.2, pre-release) . 421 GPT-5.5 Compaction Failures: Diagnosis and Mitigation . . . . . . . . . 423 Strategic Forgetting: Appli...
View in text
Recommended for You
{{#thumbnailUrl}}
{{/thumbnailUrl}}
{{^thumbnailUrl}}
{{/thumbnailUrl}}
Loading recommended books...
Failed to load, please try again later
Tip the Site
Scan the WeChat Pay or Alipay code to tip. No login required.
WeChat Pay
Alipay