Skip to main content

​
Usage

codaph exec "<prompt>" [options]
Direct capture wrapper for Codex using JSON output parsing. Spawns codex exec --json as a subprocess and parses JSONL output line-by-line.
codaph exec uses the CodexExecAdapter from src/lib/adapter-codex-exec.ts for event capture.

​
Arguments

​
prompt
string
required
The prompt to send to Codex.

​
Options

​
--cwd
string
Working directory for the Codex session. Defaults to current directory.
​
--model
string
Codex model to use. Defaults to Codex’s default model.
​
--resume-thread-id
string
Resume an existing Codex thread instead of starting a new one.
​
--mubit
boolean
Enable Mubit cloud sync (default: auto-enabled if MUBIT_API_KEY is set).
​
--no-mubit
boolean
Disable Mubit cloud sync even if API key is configured.

​
Examples

​
Basic usage

codaph exec "Add authentication to the API"

​
Specify working directory

codaph exec "Refactor the auth module" --cwd /path/to/project

​
Use specific model

codaph exec "Add tests for auth" --model gpt-4

​
Resume existing thread

codaph exec "Continue with the auth work" --resume-thread-id thread_abc123

​
Local-only capture (no Mubit)

codaph exec "Quick experiment" --no-mubit

​
How It Works

1

Build Codex command

Constructs codex exec --json command with prompt and options.
2

Spawn subprocess

Spawns Codex as a child process:
spawn('codex', ['exec', '--json', prompt, ...flags])
3

Parse JSONL output

Reads stdout line-by-line and parses each JSON event:
const event = JSON.parse(line);
// Transform to CapturedEventEnvelope
4

Capture events

For each parsed event:
  • Transforms to canonical format
  • Redacts sensitive data
  • Appends to local mirror
  • Writes to Mubit (if enabled)

​
Event Sources

Events captured via codaph exec have source type: 
source: "codex_exec"
This distinguishes them from:
  • codex_sdk (captured via codaph run)
  • codex_history (imported via codaph push)

​
Differences from codaph run

Featurecodaph execcodaph run
AdapterCodexExecAdapterCodexSdkAdapter
MethodJSON output parsingSDK streaming
EventsParse JSONL outputLive event stream
Sourcecodex_execcodex_sdk
Use caseBatch, scriptedInteractive, live
OutputCodex stdout/stderrSDK events
codaph exec is better for scripted workflows where you want to parse Codex’s JSON output directly.

​
JSON Output Format

Codex exec outputs JSONL (JSON Lines): 
{"type":"thread.created","thread":{"id":"thread_abc123"}}
{"type":"thread.message.created","message":{"role":"user","content":"Add auth"}}
{"type":"thread.item.created","item":{"type":"reasoning","text":"I'll add JWT..."}}
{"type":"thread.message.created","message":{"role":"assistant","content":"Done"}}
Codeph parses each line and transforms it to CapturedEventEnvelope format.

​
Troubleshooting

Cause: Codex SDK not installed or not in PATHSolution:
# Install Codex SDK
npm install -g @openai/codex-sdk

# Verify installation
codex --version
Cause: Codex not outputting JSON or mixing JSON with textSolution: Ensure --json flag is working:
# Test Codex JSON output
codex exec --json "test prompt" | head -5
If not outputting JSON, update Codex SDK.
Cause: Parse errors or incomplete JSONL outputSolution:
# Check mirror segments
ls -la .codaph/segments/

# Check for parse errors in Codaph output
codaph exec "test" 2>&1 | grep -i error
Cause: Codex subprocess waiting for input or crashedSolution:
# Check for zombie Codex processes
ps aux | grep codex

# Kill stuck processes
pkill -9 codex

# Try with timeout
timeout 300 codaph exec "prompt"

​
When to Use

  • Running Codex in automated scripts
  • Need to parse Codex JSON output
  • Batch processing multiple prompts
  • CI/CD pipelines
  • Want deterministic JSON parsing

​
See Also

codaph run

Alternative capture using SDK streaming

Direct Capture Guide

Detailed guide on direct capture methods

Codex Exec Adapter

Exec adapter implementation details

Architecture

How adapters fit into the data flow

Build docs developers (and LLMs) love

Get started for freeTalk to us