---

name: review-agent description: Delegate code reviews to external agents (codex, claude, kimi) running in tmux background sessions. Use when user says "/review-agent", "review my code", "code review", "have an agent review", "delegate review", or needs external code review. Agents write findings to a uniquely-named file; invoking agent watches for the file to appear. Default agent is codex. NEVER self-review.

review-agent

Delegate code reviews to external agents running in tmux. The reviewer writes findings to a file, and you watch for the file to appear. Always delegate - never self-review.

Usage

/review-agent <description>                    # uses codex (default)
/review-agent codex <description>
/review-agent claude <description>
/review-agent kimi <description>

Argument Parsing

1. Check if first word is codex, claude, or kimi
2. If yes → use that agent, rest is description
3. If no → use codex, entire input is description

Agent Selection

Choose the right agent for the task:

| Agent | Best For | Characteristics | |-------|----------|-----------------| | Codex (default) | Focused code reviews, structured output | Fast, concise, code-centric | | Claude | Nuanced analysis, architectural concerns | Broader context, detailed reasoning | | Kimi | Rapid iteration, context-heavy tasks | Strong session persistence |

When in doubt, use codex — it's optimized for code review tasks.

Workflow

1. Setup tmux session

SESSION="review-${AGENT}"
if tmux has-session -t $SESSION 2>/dev/null; then
  WINDOW=$(tmux new-window -t $SESSION -P -F '#{window_index}' -c "$(pwd)")
else
  tmux new-session -d -s $SESSION -c "$(pwd)"
  WINDOW=0
fi

2. Setup findings directory

Create the findings directory. The reviewer agent will generate a unique filename:

FINDINGS_DIR="${PWD}/.review-findings"
mkdir -p "$FINDINGS_DIR"

The reviewer will create a unique 3-word filename based on the task (e.g., auth-flow-security.md, api-error-handling.md).

3. Build the file-writing instruction

Append clear instructions for the agent to create a uniquely-named findings file:

FILE_INSTRUCTION="

=== CRITICAL INSTRUCTION ===
You MUST write your complete findings to a file in this directory before finishing:
${FINDINGS_DIR}/

Create a UNIQUE filename using exactly 3 descriptive words based on this task, joined by hyphens, ending in .md.
Examples: auth-flow-security.md, api-error-handling.md, login-validation-fixes.md

The file must contain:
- ## Summary
- ## Issues Found (with ### High/Medium/Low Severity subsections)
- ## Recommendations
- ## Session Info (your session ID for follow-ups)

DO NOT consider your task complete until this file exists.
==========================="

4. Send review command with file instruction

Use non-interactive modes with the file-writing instruction appended:

# Codex (MUST use exec or review - plain codex never exits!)
tmux send-keys -t "$SESSION:$WINDOW" "codex exec '${DESCRIPTION}${FILE_INSTRUCTION}'" Enter

# or for uncommitted changes (can't easily append instruction, use exec instead):
tmux send-keys -t "$SESSION:$WINDOW" "codex exec 'Review uncommitted changes.${FILE_INSTRUCTION}'" Enter

# Claude (use -p for non-interactive)
tmux send-keys -t "$SESSION:$WINDOW" "claude -p '${DESCRIPTION}${FILE_INSTRUCTION}'" Enter

# Kimi (use --print for non-interactive)
tmux send-keys -t "$SESSION:$WINDOW" "kimi --print -p '${DESCRIPTION}${FILE_INSTRUCTION}'" Enter

Codex Command Selection (IMPORTANT)

Choose the right codex command based on what you're reviewing:

| What to Review | Command | Why | |----------------|---------|-----| | All uncommitted changes | codex exec "Review uncommitted changes.${FILE_INSTRUCTION}" | Flexible with file instruction | | Changes vs a branch | codex exec "Review changes vs main branch.${FILE_INSTRUCTION}" | For PR-style reviews | | Specific commit | codex exec "Review commit <sha>.${FILE_INSTRUCTION}" | Review a single commit | | Custom review task | codex exec "<specific instructions>${FILE_INSTRUCTION}" | Flexible, custom prompts |

NEVER use:

• codex (plain) — interactive mode, never exits
• codex -q — still interactive
• Any codex command without exec or review subcommand

5. Wait for findings file

Watch for any new .md file to appear in the findings directory:

TIMEOUT=300
ELAPSED=0

# Get initial file count
INITIAL_COUNT=$(ls -1 "$FINDINGS_DIR"/*.md 2>/dev/null | wc -l)

while true; do
    sleep 2
    ELAPSED=$((ELAPSED + 2))

    # Check for new .md files
    CURRENT_COUNT=$(ls -1 "$FINDINGS_DIR"/*.md 2>/dev/null | wc -l)

    if [ "$CURRENT_COUNT" -gt "$INITIAL_COUNT" ]; then
        # New file appeared - get the newest one
        FINDINGS_PATH=$(ls -t "$FINDINGS_DIR"/*.md | head -1)
        break
    fi

    [ $ELAPSED -ge $TIMEOUT ] && {
        echo "ERROR: Timeout waiting for findings file in: ${FINDINGS_DIR}"
        exit 1
    }
done

# File exists - read findings
FINDINGS=$(cat "$FINDINGS_PATH")
echo "Findings written to: $FINDINGS_PATH"

6. Verify findings completeness

Check that the file has the required sections:

if ! grep -q "## Session Info" "$FINDINGS_PATH"; then
    # File incomplete - prompt agent to finish
    tmux send-keys -t "$SESSION:$WINDOW" "The findings file exists but is incomplete. Please add ## Session Info with your session ID to: ${FINDINGS_PATH}" Enter
    sleep 10
fi

# Extract session ID for resume
SESSION_ID=$(grep -A1 "Session ID:" "$FINDINGS_PATH" | tail -1 | tr -d ' ')

7. Act on results

DO NOT just summarize and ask permission. Take action based on your mode:

Edit Mode

1. Parse findings by severity (High → Medium → Low)
2. High severity: Fix immediately, no questions
3. Medium severity: Fix unless it changes behavior significantly
4. Low severity: Fix if trivial, otherwise note for later
5. Report: "Fixed X, Y. Deferred Z (reason)."

Plan Mode

1. Parse findings by severity
2. Add high/medium issues to plan as tasks
3. Note low severity as optional improvements
4. Update plan file with findings summary

Handling Disagreement

If you disagree with a finding:

• Still report it to the user
• Explain why you disagree
• Let user decide

Bad (passive):

Review found issues A, B, C. Should I fix?

Good (proactive):

Review complete. Fixed A and B. Deferred C (needs clarification on X).

8. Cleanup

tmux kill-window -t "$SESSION:$WINDOW"

---

Session Resume

When you need to continue a review with follow-up questions, use the stored session ID. The reviewer will generate a new unique filename for the follow-up findings.

Resume commands (all agents use file-based delivery)

Same file instruction format - agent picks a new unique 3-word filename:

# Claude
tmux send-keys -t "$SESSION:$WINDOW" "claude -p '${FOLLOW_UP}${FILE_INSTRUCTION}' -r ${SESSION_ID}" Enter

# Kimi
tmux send-keys -t "$SESSION:$WINDOW" "kimi -S ${SESSION_ID} --print -p '${FOLLOW_UP}${FILE_INSTRUCTION}'" Enter

# Codex
tmux send-keys -t "$SESSION:$WINDOW" "codex resume ${SESSION_ID} '${FOLLOW_UP}${FILE_INSTRUCTION}'" Enter

Then watch for a new file in the findings directory the same way as the initial review.

---

Findings Directory

Review findings are stored in .review-findings/ in the project directory. Each reviewer generates a unique 3-word filename based on the task:

.review-findings/
├── auth-flow-security.md       # Security review of auth
├── api-error-handling.md       # API error handling review
├── login-validation-fixes.md   # Login form review
└── database-query-optimization.md  # Performance review

Cleanup Policy

• Findings files persist until manually deleted
• Add .review-findings/ to .gitignore to avoid committing
• Use rm -rf .review-findings/ to clean all findings

---

Quick Reference

| Agent | Initial Review | Resume | |-------|---------------|--------| | Codex | codex exec "...${FILE_INSTRUCTION}" | codex resume <id> "...${FILE_INSTRUCTION}" | | Claude | claude -p "...${FILE_INSTRUCTION}" | claude -p "...${FILE_INSTRUCTION}" -r <id> | | Kimi | kimi --print -p "...${FILE_INSTRUCTION}" | kimi -S <id> --print -p "...${FILE_INSTRUCTION}" |

All agents use the same file-based completion detection.

| Codex Command | When to Use | |---------------|-------------| | codex exec "Review uncommitted changes..." | Review all pending changes (staged + unstaged) | | codex exec "Review changes vs main..." | Review changes vs a branch (for PRs) | | codex exec "review: <specific>..." | Custom review with specific instructions |

---

Session Reuse (CRITICAL)

ALWAYS remember the session ID from the findings file. Reuse it for:

• Follow-up questions about the review findings
• Requests for clarification on specific issues
• Additional review passes on the same code
• Any task that could benefit from the review context

The sub-agent (codex/claude/kimi) retains context about:

• The code it reviewed
• Issues it identified
• Suggestions it made
• The reasoning behind its recommendations

Reusing the session avoids re-analyzing the same code and provides continuity. Starting a fresh session loses all this context.

---

Error Handling

| Scenario | Detection | Recovery | |----------|-----------|----------| | File creation timeout | File not present after 300s | Report timeout error, suggest retry with longer timeout | | Incomplete findings | File exists but missing ## Session Info | Send reminder to agent, wait additional 10s | | Directory creation fails | mkdir returns non-zero | Report permissions error, suggest different directory | | Agent ignores instruction | Timeout with no file created | Report agent did not write findings, suggest re-running with clearer instruction | | Wrong file detected | File exists but content unrelated | Check file modification time; if older than review start, keep waiting | | Partial file write | File exists but truncated/malformed | Wait 5s extra, re-read; if still broken, report and retry | | Quote escaping failure | tmux command errors | Escape special chars in DESCRIPTION: ' → '\'', avoid $ and backticks |

---

NEVER

• NEVER use plain codex (interactive mode) — it never exits. Always use codex exec or codex review which exit cleanly
• NEVER use tmux attach — blocks the orchestrating agent, makes you completely unresponsive until manually detached
• NEVER skip the file-writing instruction — agents won't know to write the findings file
• NEVER use --last/-c/-C for resume — if other agent sessions run between your review and resume, these flags pick the WRONG session, causing context confusion and potential data leakage
• NEVER forget to reuse session for follow-ups — the review agent has valuable context about the code it analyzed; starting fresh wastes that knowledge and costs more tokens
• NEVER just summarize and ask permission — act on findings based on your mode (edit or plan)
• NEVER use special characters (', ", $, `) in DESCRIPTION without escaping — breaks the tmux send-keys command
• NEVER run concurrent reviews in the same findings directory without tracking initial file count per review — race conditions cause missed or wrong file detection
• NEVER assume the agent followed the file instruction — always use timeout as ultimate fallback
• NEVER self-review — always delegate to an external agent; that's the entire point of this skill