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

Resolved 💬 7 comments Opened Sep 25, 2025 by mathieuworoniecki Closed Oct 24, 2025

💡 Likely answer: A maintainer (pakrym-oai, contributor) responded on this thread — see the highlighted reply below.

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_

View original on GitHub ↗

7 Comments

ben-vargas · 9 months ago

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

mathieuworoniecki · 9 months ago

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 · 9 months ago

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

eadlam · 9 months ago

--json produces an event stream of json objects.

orakemu · 9 months ago

--json produces an event stream of json objects.

thank you for this!!

ben-vargas · 9 months ago

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 contributor · 8 months ago

codex exec is indeed the headless mode for Codex.