codex-agent

Codex Agent Spawner

Spawn non-interactive Codex CLI agents using codex exec. Requires the OpenAI Codex CLI installed and authenticated (codex login; auth stored in ~/.codex/auth.json). Always pin model and reasoning effort explicitly — don't rely on ~/.codex/config.toml defaults (they drift).

Model: gpt-5.6-sol by default for a single agent (flagship — a lone second opinion should be the strong one). Use gpt-5.6-terra for routine well-scoped subtasks, gpt-5.6-luna for mechanical extraction/classification. Legacy gpt-5.5 only if the user names it. For fleets, the [[ultracodex]] skill has its own per-role table.

Reasoning effort: medium by default. Raise to high/xhigh only when the user asks (e.g. "xhigh", "a fondo", "máximo esfuerzo") or the subtask is genuinely hard (subtle debugging, architecture, security analysis); max (new in 5.6) for a single hardest problem. Valid values on 5.6: low | medium | high | xhigh | max (minimal is gone).

Base command

codex exec \
  -m gpt-5.6-sol \
  -c model_reasoning_effort=medium \
  -C "<workdir>" \
  -s workspace-write \
  -o "<rundir>/last-message.md" \
  "<PROMPT>"

Run it with the Bash tool and run_in_background: true. The harness notifies you when it exits — do NOT poll or sleep. For long prompts, pipe via stdin (codex exec ... - with a heredoc) instead of an argv string.

Per-run output directory

Before spawning, create a run dir and capture everything there:

RUNDIR="/tmp/codex-agents/<slug>"   # slug: short task name, add -2, -3 if it exists
mkdir -p "$RUNDIR"

• -o "$RUNDIR/last-message.md" — final answer (this is what you report back to the user).
• Append --json > "$RUNDIR/events.jsonl" only if the user wants a full trace; otherwise plain stdout (captured by the background task) is enough to monitor progress.
• The session id appears in the output header (session id: <uuid>) — note it so the agent can be resumed.

Flag decisions