qcasares/saas-app/codex-orchestrator

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:<target_dir> background:true command:"codex exec --full-auto '<PROMPT>'"

• 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:<id> 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:<id> data:"y"
 
# Send just Enter (default choice)
process action:submit sessionId:<id> data:""

If Codex is looping or hallucinating:

# Kill the session
process action:kill sessionId:<id>

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:<id> 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 <session_id> 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.