Subagent

When to use

• Delegate large codebase reading, searching, or multi-step actions to a non-interactive exec run.

• Offload scripted or CI-style tasks that should finish without questions.

Inputs / outputs

• Inputs: a prompt string; optional flags such as --cd , --model , --json , or --full-auto .

• Outputs: CLI output from the exec run; possible file edits in the target repo.

Prompt template

Use a structured prompt to keep exec runs focused:

Goal: Scope/paths: Constraints: Deliverables: Context:

Steps

• Decide the task and repo root; include constraints and expected deliverables in the prompt.

• Choose a model using resources/references/codex-exec.md heuristics.

• Prefer resuming when the follow-up builds on the same context (e.g., providers after a repo overview, reviewing verbose test output, or continuing a multi-step investigation). Use codex exec resume <SESSION_ID> "<prompt>" .

• Start a new run when the task changes repos, needs a clean context, or should branch into a separate thread (e.g., exploring three unrelated areas in parallel).

• Run codex exec directly with flags; attach images with -i/--image when needed. Use --skip-git-repo-check when running outside a Git repo.

• Wait for completion; review output and any file changes.

• If the task references a plan directory, update learnings.md in that plan directory with key findings and decisions.

Result checklist

• Did it identify the right files and entry points?

• Are key decisions and rationale explicit?

• Are edits (if any) listed clearly?

• Are tests or verification steps noted?

Session tracking

• Always copy the exec session id into the main thread for resuming.

Safety

• Avoid --yolo unless inside an isolated runner.

• Prefer --full-auto or explicit sandbox settings when you need workspace changes.

• Keep prompts specific about allowed paths and operations.

Resources

• resources/references/codex-exec.md includes flags, model selection, and code-reading guidance.