Add headless / non-interactive mode for Codex CLI to enable orchestration

[mathieuworoniecki]

What feature would you like to see?

Description:
I’m trying to build an orchestrator that can manage multiple Codex CLI instances in parallel. The goal is similar to ccswarm, which coordinates Claude Code as headless agents.

The problem is that Codex CLI isn’t designed for interactive automation. When I try to run it in a non-TTY or headless environment, it either panics or blocks. There’s no stable JSON event stream or API that an external tool can consume to orchestrate agents.

By contrast, Claude Code works fine in headless mode, which makes orchestration much easier.

What I need:
A supported headless mode (structured JSON I/O, no TTY assumptions), or

Documentation on a safe way to automate Codex CLI processes without fragile hacks.

Why it matters:
Without this, building orchestration layers around Codex CLI is unreliable. A proper headless mode would open the door to multi-agent coordination and experimentation.

Are you interested in implementing this feature?

No response

Additional information

No response

[ben-vargas]

Did you see the new --output-schema added to exec (headless mode) added in 0.40.0?

[mathieuworoniecki]

Hi @ben-vargas , yes, I saw but is not work for me.

For my use case (building an orchestrator similar to ccswarm), this helps, but it doesn’t fully replace a proper interactive headless mode. Codex CLI still expects a TTY for long-running interactive sessions, so orchestration is only reliable if I treat each run as a one-off exec job with its own context.

That works for batch-style orchestration, but it’s not yet possible to run multiple continuous Codex agents headlessly in parallel without hitting those TTY assumptions.

[stuxnet147]

Hello, I think you can consider the "notify" python script option. I check job completion with it.

[eadlam]

--json produces an event stream of json objects.

[orakemu]

--json produces an event stream of json objects.

thank you for this!!

[ben-vargas]

Yeah, and --experimental-json is coming soon to replace --json - check out the recent commits or ask codex to review a clone of main and dive into it for you.

[pakrym-oai]

codex exec is indeed the headless mode for Codex.