codex-subagents

# Codex Subagents ## Overview `codex-subagent` offloads work to background threads so your main context stays lean. Threads run detached by default; use `wait`/`peek` to check results. **Critical rules**: 1. You cannot send to a running thread. Always wait before sending follow-ups. 2. Use `--permissions read-only` or `--permissions workspace-write` (not `workspace-read`) For detailed workflow documentation, see [reference/workflow.md](reference/workflow.md). ## When to Use | Situation | Why subagents help | |-----------|-------------------| | Parallel research tasks | Multiple threads run simultaneously | | Context would bloat | Research stays in separate thread | | Long-running work | Detached execution, check later | **Don't use for**: Quick inline questions, tightly-coupled work needing your current state. ## Core Workflow ``` 1. start with --prompt (inline text or stdin) 2. wait/peek → check result 3. send → resume with follow-up (ONLY after thread stops) 4. archive/clean → lifecycle management ``` ## The Running Thread Rule **You CANNOT send to a running thread.** This is the #1 mistake. ```bash # WRONG - thread might still be running echo "followup" | codex-subagent send thread-abc --prompt - # RIGHT - wait first, then send codex-subagent wait --threads thread-abc echo "followup" | codex-subagent send thread-abc --prompt - ``` Resumable statuses: `completed`, `failed`, `stopped`, `waiting` ## Quick Reference | Command | Purpose | Key flags | |---------|---------|-----------| | `start` | Launch new thread | `--role`, `--permissions`, `--prompt`, `--label`, `-w` | | `send` | Resume stopped thread | `<thread-id>`, `--prompt`, `-w` | | `peek` | Read newest unseen message | `<thread-id>`, `--save-response` | | `log` | Full history | `<thread-id>`, `--tail`, `--json` | | `status` | Thread summary | `<thread-id>` | | `wait` | Block until threads stop | `--threads`, `--labels`, `--all`, `--follow-last` | | `list` | Show threads | `--status`, `--label`, `--role` | | `archive` | Move completed to archive | `--completed`, `--yes`, `--dry-run` | | `clean` | Delete old archives | `--older-than-days`, `--yes` | **Prompt input**: `--prompt "text"` for simple prompts, `--prompt -` reads from stdin (for multi-line), `-f`/`--prompt-file` for files **Positional thread IDs**: `peek abc123` works like `peek -t abc123` ## Common Patterns ### Simple inline prompt ```bash codex-subagent start --role researcher --permissions read-only \ --label "quick-task" --prompt "List all exported functions in src/lib/" ``` ### Multi-line prompt (heredoc) ```bash cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --label "auth-research" --prompt - Research authentication patterns in this codebase: 1. Find all auth-related files 2. Document the auth flow 3. Note any security concerns EOF ``` ### Parallel research ```bash # Launch multiple researchers cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --label "API: Stripe" --prompt - Research Stripe API authentication methods and best practices EOF cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --label "API: Twilio" --prompt - Research Twilio API authentication methods and best practices EOF # Wait for all, see results codex-subagent wait --labels "API:" --follow-last ``` ### Blocking task ```bash # -w blocks until complete (may take minutes) cat <<'EOF' | codex-subagent start --role researcher --permissions read-only --prompt - -w --save-response result.txt Analyze error handling patterns in src/ EOF cat result.txt ``` **Warning**: `-w` blocks for as long as the agent runs. For long tasks, prefer detached mode with `wait --follow-last`. ### Cleanup old work ```bash # Two-phase: archive completed, then clean old archives codex-subagent archive --completed --yes codex-subagent clean --older-than-days 30 --yes ``` ## Troubleshooting | Problem | Cause | Fix | |---------|-------|-----| | "profile does not exist" | Wrong permissions | Use `read-only` or `workspace-write` (not `workspace-read`) | | "not resumable" error | Thread still running | `wait` first, then `send` | | "different controller" | Wrong session | Use `--controller-id` or check `list` | | Thread disappeared | Was archived | Check archive dir or re-run task | ## Checklist - [ ] `start` has `--role`, `--permissions`, `--prompt`, and `--label` - [ ] Permissions are `read-only` or `workspace-write` - [ ] `wait` before `send` (never send to running thread) - [ ] Results captured with `--save-response` or `peek`