codex-skill

What this skill does

# Codex Agent Skill

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

## Prerequisites

```bash
codex --version  # Verify installed
# Install: npm i -g @openai/codex  or  brew install codex
tmux -V          # tmux required for full workflow
```

## CLI Quick Reference

| Flag | Effect |
|------|--------|
| `exec "prompt"` | Non-interactive one-shot, exits when done |
| `--full-auto` | 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):

```bash
# Via OpenClaw exec — use background=true + pty=true, NO hard timeout
# pty=true ensures codex CLI flushes output properly (no buffering issues)
# (hard timeout kills the process; instead we poll and extend)
exec(command="codex exec --full-auto 'fix the typo in README.md'",
     workdir="/path/to/project", background=true, pty=true)

# With high reasoning
exec(command="codex exec -c 'model_reasoning_effort=high' --full-auto 'fix the auth bug'",
     workdir="/path/to/project", background=true, pty=true)
```

#### 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. Launch with `background=true` (no `timeout`)
2. Poll every ~5 min with `process(action="poll", sessionId=<id>, timeout=300000)`
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

```
Poll loop (agent behavior, not a script):

  poll_interval = 5 min (300000 ms)
  max_silent_rounds = 144  (= 12 hours with no new output → ask user)

  repeat:
    result = process(action="poll", sessionId=<id>, timeout=300000)
    if result.completed:
      → check exit code, read logs, report result
      → break
    else:
      new_output = process(action="log", sessionId=<id>, limit=20)
      if new_output changed since last check:
        silent_rounds = 0          # still producing output, keep going
      else:
        silent_rounds += 1
      if silent_rounds >= max_silent_rounds:
        → notify user: "Codex has been silent for 12 hours, kill or keep waiting?"
        → wait for user decision
```

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:

```bash
TASK_ID="feat-custom-templates"
BRANCH="feat/$TASK_ID"
REPO_ROOT=$(git rev-parse --show-toplevel)
WORKTREE="/tmp/worktrees/$TASK_ID"

git worktree add -b "$BRANCH" "$WORKTREE" origin/main
cd "$WORKTREE"

# Install dependencies (adapt to your stack)
pnpm install   # or: npm install / go mod tidy / pip install -r requirements.txt
```

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

```bash
LOG_FILE="/tmp/worktrees/$TASK_ID/codex-output.log"

# 1. Create session (starts a shell — codex not launched yet)
tmux new-session -d -s "$TASK_ID" -c "$WORKTREE"

# 2. Attach logging BEFORE launching codex — prevents losing early output
#    stdbuf -oL = line-buffered writes, so tail -f shows progress in real time
#    (plain cat buffers when writing to a file, causing monitoring lag)
tmux pipe-pane -t "$TASK_ID" -o "stdbuf -oL cat >> $LOG_FILE"

# 3. Launch codex via send-keys — all output captured from the start
#    Exit code is appended to log on completion for reliable status detection
tmux send-keys -t "$TASK_ID" \
  'codex -c "model_reasoning_effort=high" \
   --dangerously-bypass-approvals-and-sandbox \
   '"'"'Your detailed prompt here.

When completely finished:
1. Commit all changes with descriptive messages
2. Push the branch: git push -u origin '"$BRANCH"'
3. Create PR: gh pr create --fill
4. Notify: openclaw system event --text "Done: '"$TASK_ID"'" --mode now'"'"' \
   ; echo "CODEX_EXIT=$?" >> '"$LOG_FILE" Enter
```

**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 `tmux send-keys`
- Agent can be redirected without killing and restarting
- `--dangerously-bypass-approvals-and-sandbox` is safe in container/sandbox environments

### Step 3: Register Task

Track all active tasks in a JSON registry:

```bash
mkdir -p "$REPO_ROOT/.clawd"
TASKS_FILE="$REPO_ROOT/.clawd/active-tasks.json"

# Initialize if not exists
[ -f "$TASKS_FILE" ] || echo '{"tasks":[]}' > "$TASKS_FILE"

# Register
jq --arg id "$TASK_ID" --arg branch "$BRANCH" --arg wt "$WORKTREE" \
  '.tasks += [{
    "id": $id,
    "agent": "codex",
    "branch": $branch,
    "worktree": $wt,
    "tmuxSession": $id,
    "status": "running",
    "startedAt": (now|floor),
    "pr": null,
    "retries": 0,
    "checks": {}
  }]' "$TASKS_FILE" > /tmp/tasks.$$.json && mv /tmp/tasks.$$.json "$TASKS_FILE"
```

### Step 4: Monitor & Steer

```bash
# --- Status check ---

# Is the agent still running?
tmux has-session -t "$TASK_ID" 2>/dev/null && echo "running" || echo "done"

# Check exit code (if agent finished — written by the exit-code capture in Step 2)
grep "CODEX_EXIT=" "/tmp/worktrees/$TASK_ID/codex-output.log"

# --- Reading output ---

# Use the LOG FILE, not capture-pane, for long-running tasks.
# tmux capture-pane only holds ~2000 lines of scrollback — earlier output is silently
# dropped. The log file (via pipe-pane) retains everything.

# View recent output