Introduction
# 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 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).
```bash # 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:
```bash # 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: ```bash # 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.