Reach for the Codex SDK when exec runs out of room

Everything in this chapter has run through codex exec: one prompt in, one result out, one exit code the calling script reads. That shape carries an enormous amount - the monthly report, the transaction check, both reproducible in CI. For most automation it’s all you’ll ever need. This last lesson is about the cases where it isn’t, and about not reaching for heavier machinery before you have to.

The line where a shell script buckles

codex exec is stateless per call and composes through the shell: you chain runs with &&, branch on exit codes, pipe output between them. That works beautifully right up to the point where the logic between the stages gets real. Picture budgetcli’s check growing up: recategorise the new transactions, then if anything crossed a budget, draft an alert; if a test failed, open a fix and re-run only the affected suite; gate each stage on the previous one actually producing the artefact it promised. Express that in shell and you’re soon writing fragile glue - parsing prose to decide what happens next, hoping a stage finished before the next one starts, with no record of why the run took the path it did.

The heuristic to carry: if the job fits in a shell script, keep it in codex exec. Once you’re writing more than a few stages with real conditional logic between them - typed validation at the boundaries, structured handoffs, a trace you can read after the fact - you’ve outgrown the CLI, and that’s when the SDK earns its setup cost.

What the SDK buys you beyond exec

The Codex SDK is the programmatic interface for controlling coding-focused Codex threads - the thing you move to when your application needs more control than a one-shot shell command. It starts, continues, and resumes Codex work from server-side TypeScript or Python:

• Programmatic lifecycle control. Start a thread, run a prompt, continue it, or resume it later without parsing terminal output.
• Application integration. Put Codex inside a server-side CI service, internal tool, or engineering workflow while keeping the coding task in Codex.
• A real thread boundary. Keep related turns together when they need shared context, and create a new thread when the task should start clean.

The SDK is not a replacement for a general workflow engine, and it does not automatically provide typed handoffs, quality gates, or traces. Put those controls in your surrounding application and validate them with ordinary program logic. For broader multi-agent orchestration where Codex is one specialist, the official guidance is to run Codex CLI as an MCP server and orchestrate it with the Agents SDK. Keep the Approvals & sandboxing posture explicit for every process you launch.

Note

The current SDK docs list the TypeScript package @openai/codex-sdk for Node 18+ and the Python package openai-codex for Python 3.10+. Method signatures and options remain versioned API surface, so check the official SDK documentation before pinning symbols. This lesson deliberately teaches the decision - when to cross over - not a code listing that will drift.

When not to reach for it

The SDK is more setup than a shell script: a language runtime, the framework wired in, the pipeline expressed in code. Don’t pay that cost early. Two cheaper tools usually win first:

• If the workflow is a linear sequence the agent just follows - do this, then this, then this, no branching - that’s a Skill, a markdown procedure, not a pipeline. You already have that pattern in your toolkit from the CSV-import skill.
• If it’s a single self-contained task, however involved, it’s still a codex exec call. One prompt, one result. The report and the transaction check both live here, and most of your automation will too.

Reach for the Codex SDK when you need programmatic control of Codex threads or need to embed Codex in another service. Reach for the Agents SDK only when you are building a broader orchestrated workflow and Codex is one specialist inside it. Keep deterministic validation in your application rather than assuming either SDK turns a model response into a reliable test verdict.

The week, made reflex

That closes the automation chapter - and very nearly the week. You started with an inherited budgetcli you didn’t trust, and you’ve now got it producing its own monthly report and checking its own transactions, unattended, reproducibly, with the sandbox and approval discipline carrying the full weight that used to sit on you watching the screen. The headless command, the CI posture, the determinism flags, and the line where you’d graduate to the SDK - those are the whole automation toolkit.

What’s left is to make all of it second-nature - to stop assembling these pieces from scratch each time and turn them into the handful of habits you reach for without thinking: the daily profiles, the prompting reflexes, the editing ergonomics that make Codex feel like part of how you work rather than a thing you operate. That’s the final chapter.