# Claude Exec

> Delegate code review, plan review, and exploration to Claude Code CLI. Use when you need an independent second opinion on code changes, plans, or architecture — or when asked to run claude review/exec.

- Skill: `mrshu/claude-exec` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mrshu/claude-exec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mrshu/claude-exec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mrshu (https://skillmd.com/u/mrshu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mrshu/claude-exec

---


# Claude Exec — Cross-Agent Delegation

Delegate review and exploration tasks to an **independent Claude sub-agent** for a second opinion. The sub-agent acts as a strict counter-reviewer that catches blind spots you might miss.

## When to Use

Use this skill when:
- You have finished implementing a feature or fix and want an independent review before committing/pushing
- The user explicitly asks to run `claude` for review, or to "get claude's opinion"
- You have written or revised a plan and want a counter-review
- You want to explore the codebase for blind spots, simplification opportunities, or quality issues
- You need a second opinion on architecture or design decisions

**Do NOT use this skill** for tasks where you are confident in the output and the user hasn't asked for a second opinion. Reserve it for quality gates and deliberate review steps.

## How It Works

> **In Claude Code, ALWAYS use the Agent tool. Do not shell out to `claude -p`.** The Bash-`claude -p` path is the cross-agent fallback for environments without the Agent tool (Codex CLI, Cursor, OpenCode, …) — it is NOT a shortcut from inside Claude Code itself.

**If the Agent tool is available** (Claude Code): use it. The Agent tool streams output natively (the user sees progress as the sub-agent works, with no buffering), has **no artificial `--max-turns` ceiling**, and inherits the running session's environment without spawning a new claude process. The CLI fallback has none of those properties.

**If the Agent tool is NOT available** (Codex CLI, other non-Claude environments): fall back to `claude -p` via the Bash tool. See the [CLI Fallback](#cli-fallback) section for the correct invocation pattern.

---

## Agent Tool (Preferred)

### Invocation Rules

1. **Set `subagent_type` to `"general-purpose"`** — this gives the sub-agent access to Read, Glob, Grep, and Bash for exploring the codebase.
2. **Include "research only" in the prompt** when you want a review without modifications. Tell the sub-agent explicitly not to edit files.
3. **Be specific in prompts.** Tell the sub-agent exactly what to review, what to focus on, and what format you want the output in. Vague prompts get vague reviews.
4. **Use `run_in_background: true`** on the Agent tool call if you have other work to do while the review runs.

### Commands

#### Code Review

```
Agent tool call:
  subagent_type: "general-purpose"
  description: "Review branch changes"
  prompt: "You are a strict code reviewer. Review the changes on this branch compared to main. Run `git diff main...HEAD` to see the full diff. Check for correctness, edge cases, security issues, and code clarity. Reference specific files and lines. IMPORTANT: Research only — do not edit any files."
```

#### Uncommitted Changes Review

```
Agent tool call:
  subagent_type: "general-purpose"
  description: "Review uncommitted changes"
  prompt: "You are a strict code reviewer. Review all uncommitted changes (run `git diff` and `git diff --cached`). Check for correctness, edge cases, and code clarity. Be specific with file:line references. IMPORTANT: Research only — do not edit any files."
```

#### Plan Review

```
Agent tool call:
  subagent_type: "general-purpose"
  description: "Review implementation plan"
  prompt: "You are a strict plan reviewer. Read the plan in PLAN.md. Be a strict critic: identify gaps, missing edge cases, wrong assumptions, and over-engineering. Suggest concrete improvements. IMPORTANT: Research only — do not edit any files."
```

#### Deep Dig / Exploration

```
Agent tool call:
  subagent_type: "general-purpose"
  description: "Deep codebase exploration"
  prompt: "Explore the codebase for inconsistencies, dead code, and simplification opportunities. Focus on the src/ directory. Be specific with file:line references. IMPORTANT: Research only — do not edit any files."
```

#### Parallel Reviews

Use multiple Agent calls in a single message for independent reviews:

```
Agent call 1:
  description: "Review API changes"
  prompt: "Review changes in src/api/ on this branch vs main..."

Agent call 2:
  description: "Review test coverage"
  prompt: "Check test coverage for changes on this branch vs main..."
```

### Options

| Parameter | Purpose |
|---|---|
| `subagent_type: "general-purpose"` | Gives sub-agent access to Read, Glob, Grep, Bash |
| `description` | Short label shown to the user (3-5 words) |
| `prompt` | The review instructions — be specific |
| `run_in_background: true` | Run review while you continue other work |
| `model: "sonnet"` or `model: "opus"` | Override model for speed vs depth |

---

## CLI Fallback

Use this when the Agent tool is not available (e.g., Codex, other non-Claude environments).

### Invocation Rules

1. **Never use `--permission-mode plan`.** It redirects output to an internal plan file instead of stdout, producing empty or 1-line output. Use `--permission-mode dontAsk` for non-interactive locked-down runs: allowed/read-only actions proceed, and anything else is denied instead of prompting.
2. **Use `--tools` to restrict built-in tools; use `--allowedTools` to auto-approve the permitted commands.** `--allowedTools` does not define the available built-in tool set by itself. Pair both flags when a fallback reviewer may read files or run safe commands.
3. **Set `--max-turns` as a backstop, never as an effort estimate.** A sub-claude that hits the turn cap mid-investigation returns "Reached max turns" with no findings — its entire run is wasted, which is strictly worse than letting it take longer. Task-sized caps keep biting in practice, and even 20 was hit in production by review-anvil reviewers reading callers and tests around a diff. So:
   - **Prompt-only review (no file access)**: `--tools "" --max-turns 1` — the one case where a tight cap is correct.
   - **Anything that explores files** (diff review, codebase exploration): `--max-turns 100`. This is a runaway-loop backstop that should never bind on legitimate work. Bound the run's *duration* with a wall-clock watchdog (Rule 10), not with turns.
   - There's no cost to a generous ceiling that's never hit; there's total cost to a tight one that is.
4. **Pin `--output-format text` while the caller expects a Markdown report.** JSON and stream-json are useful for future telemetry, but wrappers that read the final answer from stdout must opt into the text contract explicitly.
5. **When using `--allowedTools`, pipe the prompt via stdin** — `--allowedTools` is a variadic flag that consumes all subsequent positional arguments, including the prompt. Use `echo 'prompt' | claude -p ...`.
6. **When NOT using `--allowedTools`, pass the prompt as a positional argument** — `--allowedTools` is the flag that makes stdin necessary. Keep the generous turn backstop for file-exploring reviews.
7. **Always add `2>&1`** at the end of the command to capture stderr alongside stdout.
8. **Always use `--no-session-persistence`** to avoid littering the user's session history with sub-agent sessions.
9. **Write long prompts to a temp file** and pass via stdin redirect (`< /tmp/claude-prompt.txt`). Do not use inline HEREDOCs like `$(cat <<'EOF'...)` — they break in some shell environments.
10. **Never background a bare `claude -p ... > out.md 2>&1` and wait on the file.** In `-p` text mode nothing is printed until the final answer, so the output file sits at 0 bytes whether the run is working, hung, or dead — a production review-anvil run waited many minutes on exactly that. Run it under a watchdog with a hard timeout, check the exit status afterwards, and **treat an empty output file as an explicit failure**, not something to keep waiting on. The review-anvil engine ships the canonical wrapper (`review-anvil/scripts/run-reviewer.sh`: hard timeout → TERM/KILL, `STATUS=ok|timeout|empty|failed` classification, stderr kept in `<out>.err`); reuse it, or replicate its contract with `timeout <secs> claude -p ...` plus an exit-status and non-empty-output check.

### Commands

```bash
# Branch / PR diff review — generous turn backstop, duration bounded by
# the watchdog (Rule 10), not by turns
echo 'Review the changes on this branch compared to main. Run `git diff main...HEAD` to see the full diff. Be a strict reviewer: check for correctness, edge cases, security issues, and code clarity. Reference specific files and lines.' \
  | claude -p --max-turns 100 --no-session-persistence \
    --permission-mode dontAsk --output-format text \
    --tools "Bash,Read,Glob,Grep" \
    --allowedTools "Bash(git:*)" "Read" "Glob" "Grep" 2>&1

# Quick focused review — same backstop; a tight cap saves nothing and
# can throw the whole run away
echo 'Review the changes on this branch vs main. Focus on error handling and security. Run `git diff main...HEAD`.' \
  | claude -p --max-turns 100 --no-session-persistence \
    --permission-mode dontAsk --output-format text \
    --tools "Bash,Read,Glob,Grep" \
    --allowedTools "Bash(git:*)" "Read" "Glob" "Grep" 2>&1

# Prompt-only review — no file access, single-turn response
claude -p --tools "" --max-turns 1 --no-session-persistence \
  --permission-mode dontAsk --output-format text \
  'Review this diff for correctness...' 2>&1
```

### CLI Anti-Patterns

```bash
# BAD: --permission-mode plan causes empty stdout
claude -p --permission-mode plan 'Review...'

# BAD: --allowedTools eats the positional prompt — prompt is lost
claude -p --allowedTools "Read Glob Grep" 'Review...'

# BAD: --allowedTools alone auto-approves matches but does not define
# the built-in tool set. Pair it with --tools for fallback reviewers.
echo 'Review...' | claude -p --allowedTools "Bash(git:*)" "Read"

# BAD: No --max-turns — a runaway review has no explicit turn backstop
claude -p 'Review...'

# BAD: --max-turns sized to the task — any cap the run actually hits
# throws away the entire investigation ("Reached max turns", no findings).
# Caps are runaway backstops (100), not effort estimates (3, 20)
claude -p --max-turns 3 'Review this PR's full diff and synthesize findings'

# BAD: running claude -p from inside Claude Code itself — spawns a new
# claude process when the Agent tool would have streamed natively and
# had no max-turns limit
# (in Claude Code, use the Agent tool with subagent_type "general-purpose")

# BAD: HEREDOC expansion — breaks in Bash tool shell
claude -p "$(cat <<'EOF'
long prompt here
EOF
)"

# BAD: Missing 2>&1 — stderr errors are invisible
claude -p --max-turns 3 'Review...'

# BAD: backgrounded with output redirected to a file and no timeout —
# text mode prints nothing until the final answer, so a hung run and a
# working run both look like a 0-byte file; there is no signal to act on
claude -p --max-turns 20 ... < prompt.txt > out.md 2>&1 &
# (wrap in a watchdog instead — see Invocation Rule 10)
```

### CLI Options

| Flag | Purpose |
|---|---|
| `-p, --print` | Non-interactive mode — print response and exit (required for delegation) |
| `--model <model>` | Override model (e.g., `--model sonnet`, `--model opus`) |
| `--max-turns <n>` | Turn-cap backstop. Use 1 for prompt-only, 100 for anything that explores files (see Invocation Rule 3) |
| `--tools "..."` | Restrict the available built-in tools; use `""` to disable all tools |
| `--allowedTools "..."` | Auto-approve matching tool uses. **Variadic — must pipe prompt via stdin when used** |
| `--permission-mode dontAsk` | Non-interactive locked-down mode: deny anything outside the allowed/read-only path instead of prompting |
| `--output-format text` | Explicitly emit the Markdown/text report expected by the wrapper |
| `--no-session-persistence` | Don't save the sub-agent session to disk |

---

## Workflow Patterns

### Pre-push Quality Gate

1. Run the review (Agent tool or CLI)
2. Read the review output carefully
3. Fix any issues raised
4. Re-run the review until clean
5. Push

### Plan Counter-Review

1. Write the plan
2. Run the review
3. Revise the plan based on feedback
4. Re-run until the reviewer agrees with the plan
5. Proceed with implementation

### Iterative Review

1. Run review
2. Fix issues found
3. Run another review to check remaining problems
4. Repeat until clean

## Tips

- **Be pointed in prompts.** Tell the reviewer exactly what to focus on and what format you want the response in.
- **Use "research only"** in the prompt to prevent the sub-agent from editing files during review.
- **Run in parallel.** Multiple independent reviews can run simultaneously (Agent tool: multiple calls in one message; CLI: multiple background processes).
- **Iterate.** Don't treat the first review as final — run it again after fixes to catch regressions.
- **Model override.** Use `sonnet` for faster reviews, `opus` for deeper analysis.