The Ultimate Agent Coding Workflow on Codex

The Problem#

The target is a large enterprise line-of-business application, the same one from our Copilot, Claude Code, and Claude plus Pi projects. Its shape is public there, so we can reuse the numbers: 10,000+ functions across 1,000+ files in 22 modules, backed by PostgreSQL, with over a decade of accumulated business logic. Module interdependencies, application-layer data isolation, validation rules, and undocumented gotchas all live in that history. Very little of it is discoverable from the file an engineer happens to be editing.

Generic AI coding assistants fail here for a reason that has nothing to do with model quality. They generate syntactically valid code that breaks foundational platform concepts, crosses data-isolation boundaries, or misses a module-specific rule that is not in the current file. The structural relationships between functions (who calls what, where complexity concentrates) are invisible to any tool that treats code as text.

The naive fix is a bigger context window with more of the codebase pasted into the prompt. That is the wrong diagnosis. You do not need the model to hold ten thousand functions in its head. You need it to know which twenty functions matter for the task in front of it, why they exist, and what happened the last time someone touched them. That is an organization problem, and everything below is an answer to it. Documenting the same answer on Codex matters because Codex gives you strong parts and no assembled pipeline, so the runtime decides how much you build yourself, and here you build the orchestrator.

What We Built#

On Codex, the workflow is the same roster of narrowly scoped agents, but there is no in-runtime orchestrator to dispatch them. The idiomatic build is an external process, an OpenAI Agents SDK program or a Pydantic AI v2 orchestrator, that drives Codex as an MCP server and treats each stage as a spoke. It sits on top of the same six-layer stack. Every layer already existed as a pattern. The contribution here is assembling them into one coherent harness and showing that the architecture survives the orchestrator leaving the agent entirely. The pattern language is the composable set Anthropic describes in “Building effective agents” [1]: a non-coding orchestrator that dispatches scoped workers, and an evaluator that checks their output. We covered the agent-definition side of this in Building Effective Claude Code Agents.

Figure 2 - The Six-Layer Stack: Orchestration topology decides who dispatches whom, the knowledge substrate is what agents read, traceability records what happened, the compounding layer governs what the system may learn, the safety stack catches what slips through, and economics decides which model runs each role. Each layer is independent, so any one can be upgraded in place. On Codex the topology layer moves the orchestrator outside the agent, and the safety layer splits into an advisory ring and a real OS boundary.

The roster is the proven Copilot pipeline, split further for parallel review: an explorer, a planner, an implementer, a code-reviewer and a security-reviewer running in parallel, a documenter, a skill-capture agent, a skill-validator that acts as a gate, and a skill-builder. The cognitive separation between the agent that writes code and the agent that reviews it is load-bearing, because a single agent grading its own work ships the security holes it just wrote. On Codex each role is a stage agent defined in a .codex/agents/*.toml file with its own model, its own sandbox_mode, and its own mcp_servers, and skills are native SKILL.md files. The code graph, wiki, and issue history reach the agents as per-agent MCP servers, because Codex is a native MCP client in both directions and can also run as an MCP server itself.

KEY INSIGHT: Splitting the developer and the reviewer into two agents with no shared memory is not process overhead. It is the cheapest security control in the stack, because an independent reviewer catches the exact class of bug a self-grading agent is blind to. The runtime does not change that; on Codex it just means the reviewer is another spoke the external orchestrator dispatches, not a nested child.

Most of those layers are more than a pattern we cite: each is carried by a component we built, measured, and published as its own project, and this workflow is the assembly of those measured parts. Eight such instruments span the knowledge substrate and the layers beneath it. They are runtime-neutral by design, so the same eight carry the Codex build; what Codex changes is that the orchestrator around them is external code you assemble, covered later. The table below names the instrument behind each layer, links its project page, and gives the headline number we measured on it.

Key Results#

The Copilot pipeline proved the seven-stage shape. The Claude Code rebuild added the four layers the first version lacked, and the Pi build recovered nested teams. The Codex build keeps every one of those layers and inverts the topology: the orchestrator becomes external code, the concurrency narrows to the review fork, and security splits into an advisory ring and a real OS boundary.

The Development Workflow#

The staged pipeline is unchanged from what the Copilot workflow proved: research plus doc, then plan plus doc, then code, then review plus doc, then skill capture, then knowledge capture, then an issue comment plus doc. What changed is the mechanics of the handoff underneath. On Codex there is no native pipeline, so the external orchestrator is the state machine: it reads a work list, dispatches each stage to a fresh Codex stage agent over MCP, and moves the durable output of one stage into the input of the next. This mirrors Anthropic’s guidance for long-running agents: a non-coding initializer or orchestrator, repeated stateless coding sessions, and progress written to files and commits rather than held in a single swelling context [2].

Figure 3 - The Seven-Stage Pipeline: Each stage produces a durable artifact (a research note, a plan, a diff, a review, a skill, a wiki entry, an issue comment) that becomes the next stage’s input. The artifacts are files, so a stage can be re-run or resumed without replaying the whole session. The review stage forks into a code-reviewer and a security-reviewer that rejoin before documentation. On Codex the external orchestrator owns the sequence, so the pipeline is a program you write, not a runtime feature you configure. The amber arrows run backward: a failing test or a rejected review routes to the planner for another research-and-refine pass, and only verified work moves forward.

The important property is that state lives on disk, not in a conversation. A research agent writes a findings file, the planner reads it cold and writes a plan, the implementer reads the plan cold and writes code. Each agent starts from a clean context and a written brief, which is why the pipeline can run for hours without a long session slowly forgetting its own early decisions. On Codex this discipline is not just good practice, it is the substrate the external orchestrator coordinates over: because Codex ships no seven-stage state machine, the durable artifacts on disk are how one stage’s output becomes the next stage’s input, and a restart resumes from files rather than from a lost session.

On paper that reads like a conveyor, and it is not one. The pipeline iterates, and the loop runs through the planner. The implementer’s definition of done includes running the tests, and a failing test does not move forward, it routes back to the planning stage with the failing output attached. The planner owns the diagnosis. It can send the explorer back out for more research, and it can decide to instrument the code, adding debug statements for terminal inspection or setting breakpoints and stepping through the failure, to gather the evidence the first plan lacked. The refined plan goes back to the implementer, which applies the changes, re-runs the tests, and verifies the fix actually worked. Only a verified change reaches review, and review findings travel the same road: a rejected diff goes back through the planner rather than to an ad hoc patch. You write the orchestrator on Codex, so this loop is not a convention you hope the agents follow. It is a branch in your state machine. The verify step returns a typed verdict, pass routes forward to review, fail routes back to the planner stage agent with the failing evidence attached, and that branchable-verdict shape is exactly what Pydantic AI v2’s structured outputs give you. Every pass leaves an amended plan and a fresh findings note on disk, so the iteration stays as traceable as the pipeline itself.

The Knowledge Substrate#

Underneath the pipeline are four kinds of memory that do not substitute for one another. Getting this taxonomy right is the sharpest part of the whole design, because conflating any two layers produces silent retrieval failures.

• Structural memory is the code graph. We run CodeGraphContext (CGC), an open-source code-graph tool we adopted and fixed rather than built. Our contributions were Neo4j node-conversion fixes, logger bug fixes, Windows PATH compatibility, and a portable .cgc bundle system. It parses the source into a Neo4j graph exposed over MCP, so an agent can ask “who calls this function” and get an exact answer, not a similarity guess. It re-indexes on save, never rots, and is exempt from the refinement gate because it is deterministic. On Codex it mounts as a per-agent MCP server, one entry in each stage agent’s mcp_servers.
• Semantic memory is a file-based domain wiki: the why behind a workaround, the business rule behind a data model, what tenant isolation means in this specific codebase. This is knowledge you cannot infer by reading the code.
• Episodic memory is the issue history: one dated entry per ticket, capturing what happened and why, so a returning agent starts warm instead of re-discovering a dead end. On Codex the issue history is one of the MCP servers you build, because there is no native episodic layer.
• Procedural memory is skills: progressive-disclosure files that describe how to run a repeatable task. The library splits into two families, both load-bearing. Engineering skills encode the codebase’s coding conventions and its API reference surfaces, the exact call shapes of internal services and third-party SDKs. Domain skills encode how the business actually works in this system: how orders flow, how invoicing runs, how credits apply. They are living files, not one-time documentation. When an agent working in one of those areas discovers something a skill missed, the skill-capture stage feeds that discovery back into the skill, so the library sharpens with every ticket it touches. Codex reads the same SKILL.md format, so the procedural layer ports with a path move rather than a rewrite.

Figure 4 - Four-Layer Memory: The code graph holds the shape, the wiki holds the why, the issue history holds what happened on a specific ticket, and skills hold how to perform a task, from coding conventions and API call surfaces to domain procedures like orders, invoicing, and credits. Each layer has a characteristic wrong-use pattern (a procedure buried in the wiki, domain lore stuffed into a skill) that degrades retrieval when boundaries blur. On Codex the four layers mount as per-agent MCP servers and identity lives in AGENTS.md.

The agents do not pick a retrieval method at build time. We hand them every tool and let the loop choose, cheapest mode first: navigational (read the wiki and issue-history index first, because a documented answer beats a fresh investigation), then structural (the code graph for exact call chains and blast radius), then textual (grep for literal strings the graph does not model), then semantic escalation only when the cheaper passes fail. The navigation map that makes that first rung cheap is one we packaged as MapKit, built on the upstream DOX/AGENTS.md pattern rather than invented, where we measured 2.1x fewer context tokens per edit against reading raw files.

Figure 5 - The Retrieval Ladder: Retrieval climbs from cheapest to most expensive. Navigational lookups answer most questions from an already-written index. Structural queries hit the code graph for exact relationships. Textual grep covers literal strings. Semantic vector search is the last rung, reached only when the first three fail, not the default.

This is where we take our most contrarian position: a vector database is premature by default on this codebase. Embedding pipelines cannot keep pace with an active team’s change rate, and the code graph plus grep plus a wiki index already covers structure and lookup. When a vector layer does earn its place, it belongs over the wiki prose, never over the code, and only on a named pain signal, such as the wiki outgrowing what an index and grep can serve. Building it speculatively buys a staleness and security problem in exchange for a capability you were not yet using. The runtime does not move this line: the substrate is identical on Codex, which is the whole point of documenting it once and reusing it.

KEY INSIGHT: On a live codebase, retrieval quality comes from letting the agent climb a cheap-first ladder, not from bolting a vector store onto everything. Earn the vector layer with a real pain signal, and put it over prose, never over code the graph already models.

Traceability and the Self-Improving Loop#

This is the biggest single upgrade over the Copilot workflow, which had no trace layer at all. Traceability is what turns the back half of the pipeline (review, skill capture, knowledge capture) from a manual chore into a self-improving loop.

We capture every session as a trace. On Codex the emission is native but the destination takes work. Codex exports OTLP natively, which lands in OpenAI Traces without configuration, but OTLP carries spans, not LangSmith run trees, so the LangSmith spine is a shim: you point Codex’s OTLP export at LangSmith’s OpenTelemetry ingest and own the span correlation into one pipeline-run trace. The payoff is the same as on the other runtimes: the append-only event log becomes the agent’s identity, and runs are replayable, forkable, and portable. We built the harvest side of this as TraceKit, which reads a coding session’s transcript into a cost curve and a reliability scorecard, catching 17 of 17 process faults that an output-only check misses.

Figure 6 - The Self-Improving Loop: Every session emits a trace, on Codex through native OTLP export to OpenAI Traces and, over OpenTelemetry, to LangSmith. A two-phase loop reads those traces, first identifying recurring issues, then generating candidate fixes. The fixes are proposed edits to skills and to the domain wiki, which is exactly the skill-capture and knowledge-capture stages automated. The gate is what keeps the loop from feeding on its own noise.

The loop itself is simple to state. Trace the runs, then run a two-phase pass over them: identify recurring failure modes, then generate fixes as proposed edits to skills and to the wiki. That is the skill-capture and knowledge-capture stages, automated, and we described the general shape of a system that improves its own agents in our writeup When AI Builds AI. The one non-negotiable is that the proposed edits pass through a gate before they land, the subject of the next section. A self-improving loop with no gate does not improve; it compounds its own mistakes.

One boundary deserves a hard guard. Any stage that reads an issue tracker or an error log is a prompt-injection surface, because hostile text can ride in through a ticket body. The issue-comment stage needs a safety classifier in front of routing, so a poisoned ticket cannot steer the agent. The classifier we built for that boundary is Ingest-Guard, which caught 85.0% of injections at 0.0% false positives keyless in our tests, with 0 of 40 payloads leaking through.

Orchestration#

This is where Codex differs most, because the orchestrator is not in the runtime at all. Codex gives you strong stage agents, native MCP, per-agent model routing, and headless execution through codex exec --json, but it ships no seven-stage state machine and no gates. So the orchestrator is external code: an OpenAI Agents SDK program or a Pydantic AI v2 process that drives Codex as an MCP server and dispatches each stage as a spoke around a single hub. The topology is a star, and it is capped: Codex subagents run at max_depth=1, so there are no grandchildren, and the only concurrency inside the pipeline is the parallel review fork.

Figure 7 - The Star Topology: An external orchestrator framework sits at the hub and drives Codex as an MCP server. Seven stage agents hang off it as spokes, each a .codex/agents/*.toml file with its own model, sandbox, and MCP servers. Nesting is capped at one level, so there are no grandchildren, and the only concurrency inside the pipeline is the fork into the parallel code-reviewer and security-reviewer. Codex recovers neither Claude Code’s flat-native simplicity nor Pi’s nested teams; its shape is a hub and spokes you wire yourself.

The strongest current framework for that external hub is Pydantic AI v2, and it maps onto this architecture unusually cleanly. Its typed, schema-validated structured outputs are the stage gates and the refinement gate, because a gate is a branchable typed verdict object. Its agent delegation and graphs are the seven-stage sequence and the parallel review fan-out. Its durable execution with first-class human-in-the-loop approval is the restart-safe run and the gate that pauses for a person. Its Logfire and OpenTelemetry emission is the trace spine, and its MCP client is how the substrate mounts. It reached general availability in mid-2026 with a stated three-month breaking-change window, so we treat it as promising rather than settled, and note that its path to LangSmith is an OpenTelemetry bridge rather than a native sink.

Two orchestration cautions carry across from the research. The first is a warning: flat equal-role agents do not scale. Cursor has reported that 20 peers sharing a coordination file collapse to the throughput of 1 to 3 under lock contention, and that the cure is role separation into a planner, a sole-owner executor, non-coordinating workers, and an independent judge [3]. We treat that figure as Cursor’s self-reported finding, not a universal law, but the shape matches everything we have seen, and a star of scoped stage agents is exactly that role separation. The second is parallel fan-out via git worktrees, one worktree per work item, so parallel file mutation never collides and a plain git merge resolves two half-solutions mechanically. On the Codex CLI that pattern needs care, because the CLI shares a single ~/.codex session directory and parallel lanes can cross-contaminate, so worktree isolation is a pattern to enforce, not a native guarantee. We present it as an architectural pattern, not a benchmarked result.

The model map is held constant to isolate the harness effect. Opus 4.6 runs the two low-volume, high-leverage roles, the orchestrator and the planner. Sonnet 4.6 runs the high-volume verifiable roles: implementer, reviewers, documentation, and the skill roles. Codex is OpenAI-native, but its model_providers configuration lets the stage agents run Anthropic models, so the same constant map holds on Codex and the comparison across runtimes stays clean. On a metered API that split is also a cost control, which the economics section returns to. We walked through the multi-agent handoff mechanics in more depth in Multi-Agent Pipelines.

Compounding Without Slop#

The system is allowed to learn, but only through a gate, because agents lack the pain bottleneck that stops a human from writing bad documentation. A person who writes a misleading wiki page eventually gets burned by it while an agent does not. Left ungated, the loop feeds on itself: the wiki page an agent gets wrong today is the source the next agent reads as established fact tomorrow, and the error is re-copied and amplified on every pass after that. That is the ouroboros problem, named for the serpent drawn eating its own tail, and compounding slop is what it produces.

The gated refinement loop runs after review. It proposes three things: skill edits, wiki-page edits, and an always-written issue-history entry. The issue-history entry is ungated, because it is episodic fact and low blast radius. The skill and wiki edits are gated, either by a human or by a capped validator agent. On Codex the gate is a typed verdict object the external orchestrator branches on, which is exactly what Pydantic AI v2’s structured outputs give you. We built that loop as FlywheelKit, which compounded 1 to 4 gotchas across 3 harvests while blocking a plausible-but-wrong rewrite at the gate, and the definition-of-done check behind it as the Deterministic Gate Harness, where 0 phases advanced without evidence across 6 gated runs and the same workflow ungated shipped 4 broken artifacts.

Figure 8 - The Three-M Gate: A proposed edit auto-applies only when all three risks are absent. Megaphone asks whether a wrong update broadcasts widely, Money whether it touches anything financial, and Meaning whether it corrupts a shared context file other skills depend on. Any one present routes the edit to human review. The criterion is blast radius, not confidence.

The gate criterion is blast radius, captured as the three-M test. Megaphone asks whether a wrong update broadcasts widely. Money asks whether the change touches money. Meaning asks whether it corrupts a shared context file other skills depend on. The loop auto-refines only when all three are absent, and routes everything else to a human. For model specialization, the sellable pattern is the teacher-model pattern: a stronger teacher watches a cheaper student fail, writes a skill that captures the fix, and the student executes from that skill thereafter. Full custom reinforcement-learning distillation is real, but it fails the practicality test for a typical mid-market client with no GPU infrastructure, so it stays a reference rather than part of the workflow we ship.

KEY INSIGHT: Give a self-improving system a blast-radius gate, not a confidence threshold. Confidence is what a wrong agent has too much of. Blast radius is what actually determines whether a bad edit costs you a typo or a corrupted shared context file.

Quality, Safety, and Economics#

Safety is a stack, not a reviewer. Each layer catches what the others miss, and on Codex the second layer carries a caveat you cannot skip: its hooks are advisory, so the real boundary is the operating system.

The first layer is adversarial verification: the checker re-derives the answer and ignores the worker’s self-report, so a confidently wrong result gets caught at any rank, including the orchestrator’s own. We wrote about this red, blue, and referee structure in our adversarial testing series, and the fresh-context judge we built for it is RubricGate, which took task success from 0/3 to 3/3 at 1.00 judge precision and recall on our labeled sample. The second layer is two-ring security, and here Codex is explicit in a way that matters: its PreToolUse and permission hooks are advisory, not a hard boundary, so a SOTA security frame cannot rest on the hook alone. The real enforcement boundary is the OS sandbox_mode, and the advisory hooks ride inside it as an early-warning ring. A separate security-reviewer stage agent still checks tenant isolation, parameterized SQL, OWASP categories, and auth boundaries at review time. The third layer is hard action gates: a typed SDK is the agent’s only door to mutate state, and a deterministic execution step catches the false-completion failure where an agent reports done with nothing committed. Governing how much autonomy each role earns, the Trust-Ladder Deployer runs four eval-gated rungs whose auto-demote kept 7 bad writes out of production. The last discipline is to prune scaffolding as models improve, because a verifier written around a model limitation that has since been fixed can start doing harm.

Figure 9 - The Two-Ring Security Model: The real enforcement boundary is the outer ring, the OS sandbox_mode. The inner ring, Codex’s PreToolUse and permission hooks, is advisory: it can warn and shape behavior, but it is not the wall. A request passes the advisory ring and then must clear the OS boundary before it reaches application state, and a security-reviewer stage agent still checks the code that runs. The lesson is to never treat an advisory hook as the boundary on a runtime that calls it advisory.

On economics, the rule is to route by dollars per task, not dollars per token. The flagship model runs planning and hard code, a mid tier runs by default, and the cheap tier runs mechanical labeling and knowledge chores. Two mechanics keep the bill down and both have vendor-direct backing. Anthropic’s prompt caching reads cached input at 10% of the normal input rate, a 90% discount on repeated context [4]. Lean tool design matters because tool definitions themselves eat the context window: Anthropic measured tool-definition token loads in the tens of thousands, with a five-server setup of 58 tools costing roughly 55K tokens before a single call is made, and its Tool Search Tool with deferred loading cut that by about 85% in Anthropic’s own measurement [5]. That capability is in beta, not general availability, so we treat it as a near-term optimization rather than a shipped default.

Figure 10 - Routing by Dollars per Task: The two low-volume, high-leverage roles (orchestrator and planner) run on the flagship tier. The high-volume verifiable roles (implementer, reviewers, documentation, skills) run on the cheaper tier. The routing target is cost per completed task, not cost per token, because a cheap model that loops ten times is not cheap. On Codex the tiers are wired through model_providers, and on a metered API the routing is a hard budget lever.

Codex meters every token, so the model map that was a convenience on Max is a budget line here. That is why Opus is confined to the two low-volume, high-leverage roles: on a flat-rate plan you can afford to be generous with the expensive model, and on a metered one you cannot. The re-feed problem is the other cost lever, because the dominant token cost in a coding session is the output of tool calls, the file reads, git status dumps, test logs, and JSON blobs the agent pulls in, not the prompt you write. That lever cuts in this runtime’s favor. Sebastian Raschka, who writes the Ahead of AI newsletter, ran one open-weight model across three harnesses on an identical task set and found that Codex used the fewest input tokens of the three while Claude Code used by far the most, with a single Claude Code run burning roughly 578k input tokens against 4.5k of output across 25 turns [6]. That is one author’s five-task private benchmark, so we read it as directional rather than definitive, and a leaner harness shrinks the re-feed bill rather than removing it. The mitigation is a reversible, type-aware compression layer between the agent and the model: compress each tool result by content type (AST-strip for code, field-prune for JSON, smart-filter for shell), cache the original, and leave a retrieve(id) escape hatch so nothing is lost. Tejas Chopra, an engineer at Netflix, laid out this pattern in his Headroom talk at the Linux Foundation’s Open Source Summit North America, and noted that AST compression matters more when the agent reads raw files than when it works through an LSP [7]. Codex reads raw files, so AST compression applies, and our implementation plugs in as an MCP server or proxy between the tool and the agent. We built that measured implementation as ContextLedger, which unifies three patterns we had arrived at independently and recorded a 44.0% tool-output token reduction, fully reversible, on a real 127-payload session at roughly a 1% retrieve rate. To be precise about provenance: we built ContextLedger and the 44% is our own measurement, while the compression pattern itself is Chopra’s Headroom work. On a metered runtime that reduction is money, and it stacks with the prefix caching above rather than replacing it.

KEY INSIGHT: The biggest token line in a coding agent is the output of its tool calls, not the prompt you write. Compress that output reversibly and by content type, and you cut the bill at its actual source while losing nothing, because the original is one retrieve(id) call away.

Figure 11 - Tool-Output Compression: A large raw tool result passes through a content router into a type-aware compressor (AST-strip for code, field-prune for JSON, smart-filter for shell). A compact payload goes to the Codex stage agent carrying a retrieve(id) handle, while the original is cached in a store. On Codex the layer plugs in as an MCP server or proxy between the tool and the agent, and the measured result on a real session is a 44% reduction in tool-output tokens, fully reversible.

What Transfers#

The thesis of this whole build is that the architecture is runtime-neutral. The roster, the four-layer substrate, the gates, and the traceability spine are identical no matter where the coding agent runs. What differs per runtime is only how each affordance is provided, whether native, ported, or built by hand. Claude Code provides nearly all of it natively and flat. Pi recovers nested teams. Codex provides strong parts and no assembled pipeline, so the orchestrator becomes external code, which is the shape every non-Claude-native runtime shares.

Figure 12 - The Portability Matrix: The same workflow ports across five runtimes. Claude Code is native across the board but flat, Claude plus Pi adds nested teams and deeper hooks at the cost of a metered bill, and Codex, OpenCode, and Cursor each provide the affordances differently, with the orchestrator living outside the agent for every non-Claude-native runtime. The architecture is the constant; the wiring is the variable.

There is one cross-runtime finding worth stating plainly, because it lands on Codex with an extra twist. Newer Claude models are being tuned toward Claude Code’s own edit tool, which means running Claude inside a third-party harness can degrade its custom tool-schema calling. Armin Ronacher, who builds the Pi harness, reported exactly this effect and Simon Willison relayed it: the newest Claude models get the edit intent right, then append invented fields to Pi’s edit-tool schema, so the harness rejects the malformed call and the model retries [8][9]. Ronacher’s proposed cause, reinforcement-learning post-training toward Claude Code’s own search-and-replace edit tool, is his theory rather than an Anthropic-confirmed mechanism, and the account is a qualitative developer report with no published failure rate. On Codex the twist is that Codex’s own edit tool is apply_patch, a shape OpenAI trains its models toward, so routing an Anthropic model through Codex’s model_providers puts that model two steps from its native tool shape. The mitigation is the same as on Pi: keep the stage agent’s edit-tool schema close to what the chosen model is trained on, and validate tool calls at the boundary so a malformed call is caught and retried rather than silently mis-applied.

The same architecture ports to two more runtimes, each its own writeup: OpenCode and Cursor. For every non-Claude-native runtime the orchestrator becomes external code, and Pydantic AI v2 is the strongest current framework for that slot, the typed, model-agnostic hub this build already leans on. The pattern the Codex build makes explicit, that the orchestrator is a program you write rather than a runtime you configure, is the through-line for the rest of the series.

Conclusion#

The workflow that ran on GitHub Copilot, then on Claude Code, then on a Claude orchestrator over Pi workers, survives its move to Codex intact, because it was never really about the runtime. It is about organizing a decade of codebase knowledge into four durable memory layers, dispatching narrow agents against a written brief, tracing every run, and letting the system learn only through a blast-radius gate. Moving it onto Codex proves the point a third way: the substrate, the gates, and the safety stack port without change, while the orchestrator leaves the agent entirely and becomes an external Agents SDK or Pydantic AI v2 program driving Codex as an MCP server.

Two honest costs come with that. Codex ships no seven-stage state machine, so you build the orchestrator and both gates yourself, and its hooks are advisory, so the OS sandbox_mode has to carry the enforcement the hook cannot. Neither changes the architecture; they change what you assemble and where you put the wall. That is the entire reason to document this workflow across runtimes: the design is the constant, and each runtime tells you which parts it hands you and which you build. The next writeups take the same stack to OpenCode and Cursor, where the orchestrator stays external and the affordances shift again.

Technologies#

As a Consulting Engagement#

This is how we run a harness-engineering engagement when a client is standardized on OpenAI tooling or wants the orchestrator as their own external code rather than a vendor’s runtime. We assess the codebase, stand up the four-layer substrate as MCP servers and the trace spine, build the external orchestrator and both gates (Pydantic AI v2 is our default for that slot), put the enforcement boundary where the runtime actually enforces it, and route models by cost per task rather than cost per token. Each of the eight instruments behind the six layers is independently deployable, so an engagement can start with the layer that hurts most, whether that is token cost, agent reliability, or injection exposure, and expand from there. The Codex build is the right call specifically when a team wants the orchestrator under its own control and is comfortable owning the pipeline that Codex does not ship. If you are running coding agents against a large legacy codebase and cannot tell which scaffolding to keep and which to delete as the models improve, we are happy to talk it through or lend a hand.

The Series#

This is the third of five project writeups in the Ultimate Agent Coding Workflow series, one state-of-the-art coding harness documented per runtime:

1. The Ultimate Agent Coding Workflow on Claude Code: the flat, fully native build on Max, where the code graph, skills, hooks, and tracing are all first-class.
2. The Ultimate Agent Coding Workflow on Claude + Pi: the hybrid that puts a Claude orchestrator over Pi workers to recover nested teams and deeper TypeScript hooks.
3. The Ultimate Agent Coding Workflow on Codex (this writeup): the external OpenAI Agents SDK or Pydantic AI v2 orchestrator driving Codex as an MCP server in a star topology, with a two-ring security model.
4. The Ultimate Agent Coding Workflow on OpenCode: an external TypeScript SDK conductor over a headless server, with a native permission frame and model-agnostic routing.
5. The Ultimate Agent Coding Workflow on Cursor: the two-tier, IDE-first variant with native worktrees and a bolt-on trace spine.

References#

[1] E. Schluntz and B. Zhang, “Building effective agents,” Anthropic Engineering, December 19, 2024. https://www.anthropic.com/engineering/building-effective-agents

[2] J. Young, “Effective harnesses for long-running agents,” Anthropic Engineering, November 26, 2025. https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

[3] Cursor, “Towards self-driving codebases,” Cursor Blog, February 5, 2026. https://cursor.com/blog/self-driving-codebases

[4] Anthropic, “Prompt caching,” Claude Platform Documentation, 2026. https://platform.claude.com/docs/en/docs/build-with-claude/prompt-caching

[5] Anthropic, “Introducing advanced tool use on the Claude Developer Platform,” Anthropic Engineering, 2026. https://www.anthropic.com/engineering/advanced-tool-use

[6] S. Raschka, “Using Local Coding Agents,” Ahead of AI, June 27, 2026. https://magazine.sebastianraschka.com/p/using-local-coding-agents

[7] T. Chopra, “Headroom: A Context Optimization Layer for LLM Applications,” Open Source Summit + Embedded Linux Conference North America 2026, The Linux Foundation, Minneapolis, MN, May 19, 2026. https://www.youtube.com/watch?v=UOWSHg18cL0

[8] A. Ronacher, “Better Models: Worse Tools,” Armin Ronacher’s Thoughts and Writings, July 4, 2026. https://lucumr.pocoo.org/2026/7/4/better-models-worse-tools/

[9] S. Willison, “Better Models: Worse Tools,” Simon Willison’s Weblog, July 4, 2026. https://simonwillison.net/2026/Jul/4/better-models-worse-tools/