Codex Orchestrator

---

name: codex-orchestrator description: Monitor, control, and orchestrate background Codex sessions. Use this skill to track progress, handle interruptions, and ensure task completion for long-running coding tasks.

---

Codex Orchestrator

This skill provides a workflow for supervising the Codex coding agent running in background processes.

Workflow

1. Start (Launch)

Always launch Codex in a background PTY session to maintain interactivity without blocking the main agent.

bash pty:true workdir: background:true command:"codex exec --full-auto ''"

* Store the returned sessionId. * If sessionId is lost, find it via process action:list.

2. Monitor (Watch)

Check progress regularly (e.g., via cron or manual check).

# Get last 2KB of logs to see current status
process action:log sessionId: limit:2000

Signs of life: * Spinner animations or progress bars updating. * "Working...", "Thinking...", "Running...". * File edits (Edit ...).

Signs of blockage: * Interactive prompts (e.g., "Select directory", "Approve change [y/n]"). * No log output for >5 minutes (process might be hung or waiting for hidden input).

3. Intervene (Control)

If Codex is stuck at a prompt:

# Send 'y' and Enter
process action:submit sessionId: data:"y"
Send just Enter (default choice)
process action:submit sessionId: data:""

If Codex is looping or hallucinating:

# Kill the session
process action:kill sessionId:

4. Report (Notify)

When a significant milestone is reached or the task is done: 1. Summarize the work done (files changed, tests passed). 2. Notify the user.

Standard Operating Procedures (SOPs)

"The Stuck Agent" Protocol

1. Diagnose: Run process action:log sessionId: limit:500. 2. Analyze: Is it asking a question? Is it downloading? 3. Action: * If asking: Provide answer via submit. * If downloading (slow): Wait. * If silent >10m: Send a "poke" (e.g. submit data:"\n" to refresh prompt) or kill/resume.

"The Resume" Protocol

If a session died or was killed: 1. Run codex resume --last or codex resume in a new background process. 2. Verify it picked up the context.

Logs & Artifacts

* Codex logs are ephemeral in the PTY buffer. * For persistent logs, instruct Codex to write to a file: codex exec "task..." > codex.log 2>&1 (Note: buffering may delay output). * Better: Use process action:log to snapshot the buffer periodically.