Add `codex exec fork` subcommand for headless/non-interactive fork

Open 💬 1 comment Opened Feb 13, 2026 by pnegahdar

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 as codex fork)
  • Runs the optional [PROMPT] in the forked session
  • Outputs JSONL events to stdout (when --json is passed), including thread.started with the new session ID
  • Supports all existing exec flags: --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 mirrors
  • ThreadManager.fork_thread() in codex-rs/core — the internal fork implementation
  • thread/fork in codex-rs/app-server — the app-server JSON-RPC fork endpoint
  • codex-rs/core/tests/suite/compact_resume_fork.rs — existing fork test coverage

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗