Codex Agent Skill

Operate Codex CLI as a managed coding agent — from worktree setup through PR merge.

Prerequisites

CODEBLOCK0

CLI Quick Reference

Flag	Effect
INLINECODE0	Non-interactive one-shot, exits when done
INLINECODE1

Alias for -s workspace-write (auto-approve file edits) | | -s workspace-write | Read + write files in workspace | | -s read-only | Analysis only, no modifications (default for exec) | | -s danger-full-access | Full access including network and system | | --dangerously-bypass-approvals-and-sandbox | Skip all prompts + no sandbox (safe in containers/VMs) | | -m <model> | Model selection — only use when user explicitly requests a model (e.g. gpt-5.1-codex-max). Omit to use Codex default. | | -c "model_reasoning_effort=high" | Reasoning effort: low, medium, high | | --json | Structured JSON Lines output | | -o <file> | Write final output to file | | -C <dir> / --cd <dir> | Set working directory | | --add-dir <dir> | Allow writing to additional directories | | --skip-git-repo-check | Run in non-git directories | | resume --last | Resume last session with new prompt |

---

Execution Modes

Quick Mode — Small Tasks

For trivial fixes, one-file changes, or analysis. Use exec (non-interactive):

CODEBLOCK1

Adaptive Timeout (Poll-and-Extend)

Do NOT use timeout= for codex tasks. Instead, use background execution
with periodic polling. This prevents premature kills on long-running tasks:

1. 1. Launch with background=true (no timeout)
2. Poll every ~5 min with INLINECODE25
3. If process is still running → it's making progress, keep waiting
4. If process exited → check logs, done
5. Safety net: if no new output for 12 hours, ask user before killing

CODEBLOCK2

This way tasks that need 5 min or several hours both work without premature kills.

Quick Mode caveats:

• - Session output is held in memory only — lost on OpenClaw restart (no disk persistence).

For truly critical tasks, prefer Full Mode (tmux + log file).

• - In-memory output is capped by PI_BASH_MAX_OUTPUT_CHARS. Very verbose codex tasks may

lose early output from process log. Use process log offset:0 limit:50 to check if
the beginning is still available; if not, the cap was hit.

• - process is scoped per agent — you can only see sessions you started.

Full Mode — Features, Bugfixes, Refactors

For non-trivial tasks, use the full workflow below. This gives you:

• - Isolated worktree — no conflicts with other work
• tmux session — mid-task steering without killing the agent
• Task tracking — know what's running at all times
• Quality gates — Definition of Done checklist
• Smart retries — don't waste tokens on repeated failures

---

Full Workflow: Task → Merged PR

Step 1: Create Worktree

Isolate each task in its own worktree and branch:

CODEBLOCK3

Step 2: Launch Agent in tmux

Start Codex in interactive mode (no exec) so you can steer mid-task.
Important: Use tmux pipe-pane to log output — do NOT use | tee because it
turns stdout into a pipe, which breaks interactive mode (codex detects !isatty(stdout)
and may disable interactive features, breaking send-keys steering).

CODEBLOCK4

Why this order (session → pipe-pane → send-keys)?

• - No race condition — if you pass the command directly to tmux new-session, output

produced before pipe-pane attaches is lost from the log file

• - Exit code captured — echo "CODEX_EXIT=$?" appends the exit code to the log,

so you can distinguish success from crash (otherwise tmux discards it on session close)

• - Line-buffered logging — stdbuf -oL ensures tail -f $LOG_FILE works in real time

Why interactive mode (no exec)?

• - Allows mid-task steering via INLINECODE41
• Agent can be redirected without killing and restarting
• INLINECODE42 is safe in container/sandbox environments

Step 3: Register Task

Track all active tasks in a JSON registry:

CODEBLOCK5

Step 4: Monitor & Steer

CODEBLOCK6

Monitoring cadence: Check every 5–10 minutes, not every 30 seconds. Agents need time to work.

Step 5: Definition of Done

A PR is NOT ready for review until all checks pass:

CODEBLOCK7

Quick inline check:
CODEBLOCK8

Step 6: Multi-Model Code Review

Review with a different model than the one that wrote the code. Different models catch different issues:

CODEBLOCK9

Post review results to PR:
CODEBLOCK10

Update task registry:
CODEBLOCK11

Step 7: Notify

If you included the notify command in the agent prompt (Step 2), the agent self-notifies on completion.

Otherwise, notify after DoD passes:
CODEBLOCK12

Update task status:
CODEBLOCK13

Step 8: Cleanup

After PR is merged:

git worktree remove "$WORKTREE" 2>/dev/null
git branch -d "$BRANCH" 2>/dev/null

# Remove from registry
jq --arg id "$TASK_ID" '.tasks = [.tasks[] | select(.id != $id)]' \
  "$TASKS_FILE" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json "$TASKS_FILE"

---

Smart Retry Strategy

When an agent fails, analyze the failure and adapt the prompt — don't just re-run blindly.

Failure Type	Symptom	Retry Strategy
Context overflow	Agent loops, produces garbage, or stops mid-task	Narrow scope: "Focus only on files X, Y, Z"
Wrong direction

Agent implements something unrelated to intent | Correct intent: "Stop. Customer wanted X, not Y. Spec: ..." |
| Missing info | Agent makes wrong assumptions about architecture | Add context: "Auth uses JWT, see src/auth/jwt.ts" |
| CI failure | Tests, lint, or typecheck fail after PR | Attach CI log: "Fix these test failures: ..." |
| Build failure | Dependencies missing or incompatible | Pre-install deps before retry |

Max 3 retries. After that, escalate to human.

CODEBLOCK15

---

Parallel Execution

Run multiple agents simultaneously on different tasks:

CODEBLOCK16

---

Codex-Specific Features

Reasoning Effort

Control how much the model "thinks" before acting:

CODEBLOCK17

Sandbox Modes

Mode	Use Case
INLINECODE43	Code review, analysis, documentation
INLINECODE44 / INLINECODE45

Feature implementation, bug fixes, refactors | | danger-full-access | Installing dependencies, network access needed | | --dangerously-bypass-approvals-and-sandbox | Full auto in containers (recommended for tmux workflow) |

JSON Output

CODEBLOCK18

Resume Session

CODEBLOCK19

---

Best Practices

Prompt Quality

• - Include file paths: "The entry point is src/index.ts, config in src/config/"
• Include schemas/types: Paste relevant type definitions into the prompt
• Include test commands: "Verify with: npm test -- --grep auth"
• Include commit convention: "Use conventional commits: feat:, fix:, chore:"
• Include error logs: When retrying, always attach the failure output

Scope Management

• - One task per agent — don't ask for "refactor everything"
• Pre-install dependencies before launching the agent
• Be specific — "Add rate limiting to POST /api/users" not "improve the API"
• Use high reasoning effort for complex tasks, low for mechanical ones

When to Interrupt (Ask Human)

• - Destructive operations (drop tables, force push main)
• Security decisions (expose credentials, change auth)
• Ambiguous requirements with significant trade-offs
• All other decisions: proceed autonomously