obra/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.

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.

# 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

codex-subagent start --role researcher --permissions read-only \
  --label "quick-task" --prompt "List all exported functions in src/lib/"

Multi-line prompt (heredoc)

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

# 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

# -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

# 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