Add `codex exec fork` subcommand for headless/non-interactive fork
Summary
codex fork <session_id> [prompt] is currently a TUI-only command — it requires an interactive terminal (stdin is not a terminal error otherwise) and does not support --json output. This makes it unusable in headless/programmatic contexts where codex exec is the standard entry point.
codex exec resume already exists as the headless counterpart to the interactive codex resume command. A matching codex exec fork would complete the pattern and enable programmatic session forking.
Motivation
I'm building a harness library that drives AI coding CLIs (including Codex) as child processes. The harness uses codex exec --json for queries and codex exec resume --json for session resumption. However, there's no headless path for forking a session — the internal ThreadManager.fork_thread() machinery supports it, and the app-server exposes it via JSON-RPC (thread/fork), but the exec CLI surface does not.
Currently the only workaround is spawning codex fork inside a pseudo-TTY, polling the filesystem for new rollout files to discover the forked session ID, killing the TUI, and then using codex exec resume --json <forked_id> for the actual query. This works but is fragile and slow (~6s overhead for TUI startup).
Proposed API
codex exec fork [OPTIONS] <SESSION_ID> [PROMPT]
Behavior:
- Creates a new session forked from
<SESSION_ID>(same ascodex fork) - Runs the optional
[PROMPT]in the forked session - Outputs JSONL events to stdout (when
--jsonis passed), includingthread.startedwith the new session ID - Supports all existing
execflags:--json,--sandbox,--model,-c,--ephemeral,--skip-git-repo-check, etc.
Current workaround
# Spawn codex fork with a PTY (requires native PTY support)
# Poll ~/.codex/sessions/ for a new rollout file with forked_from_id == original
# Extract new session ID from the rollout file's session_meta
# Kill the TUI process
# Use codex exec resume --json <new_id> <prompt> for the actual query
This works but adds ~6 seconds of overhead, requires PTY bindings (e.g., Python's pty module or node-pty), and is tightly coupled to the rollout file format.
References
codex exec resume— the existing headless resume that this mirrorsThreadManager.fork_thread()incodex-rs/core— the internal fork implementationthread/forkincodex-rs/app-server— the app-server JSON-RPC fork endpointcodex-rs/core/tests/suite/compact_resume_fork.rs— existing fork test coverage
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗