Skip to main content

​
Usage

codaph run "<prompt>" [options]
Direct capture wrapper for Codex. Runs a Codex SDK session with live event streaming and captures all events to the local mirror and Mubit.
codaph run uses the CodexSdkAdapter from src/lib/adapter-codex-sdk.ts for live 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 run "Add authentication to the API"

​
Specify working directory

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

​
Use specific model

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

​
Resume existing thread

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

​
Local-only capture (no Mubit)

codaph run "Quick experiment" --no-mubit

​
How It Works

1

Initialize adapter

Creates a CodexSdkAdapter instance with the ingest pipeline.
2

Run Codex session

Calls adapter.runAndCapture() which:
  • Spawns Codex SDK process
  • Subscribes to Codex event stream
  • Sends the prompt
3

Capture events

For each Codex event:
  • Transforms to CapturedEventEnvelope
  • Redacts sensitive data
  • Appends to local mirror (.codaph/)
  • Writes to Mubit (if enabled)
4

Complete session

Returns session ID, thread ID, and final response.

​
Event Sources

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

​
Differences from codaph exec

Featurecodaph runcodaph exec
AdapterCodexSdkAdapterCodexExecAdapter
MethodSDK streamingJSON output parsing
EventsLive streamParse after completion
Sourcecodex_sdkcodex_exec
Use caseInteractive, liveBatch, scripted
codaph run requires Codex SDK to be installed and accessible in PATH.

​
Troubleshooting

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

# Or add Codex to PATH
export PATH="$PATH:/path/to/codex/bin"
Cause: Mubit API key not configured or circuit breaker openSolution:
# Check Mubit configuration
codaph doctor --mubit

# Set API key if missing
codaph setup --mubit-api-key <your-key>

# Check for circuit breaker errors in output
Cause: Mirror not flushed or index not updatedSolution:
# Sync and refresh TUI
codaph sync
codaph tui

# Or check mirror directly
ls -la .codaph/segments/

​
See Also

codaph exec

Alternative capture using JSON output parsing

Direct Capture Guide

Detailed guide on direct capture methods

Codex SDK Adapter

SDK adapter implementation details

Architecture

How adapters fit into the data flow

Build docs developers (and LLMs) love

Get started for freeTalk to us