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

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 timeout or buffering issues.

If the Agent tool is NOT available (other environments): fall back to claude -p via the Bash tool. See the 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 --allowedTools to restrict tools instead.
2. Always use --max-turns to prevent the sub-claude from exhausting all turns on tool calls without producing a text response. Use --max-turns 3 for reviews, --max-turns 5 for deep digs, or --tools "" --max-turns 1 for prompt-only (no file access).
3. 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 ....
4. When NOT using --allowedTools, pass the prompt as a positional argument — claude -p --max-turns 3 'prompt' works fine.
5. Always add 2>&1 at the end of the command to capture stderr alongside stdout.
6. Always use --no-session-persistence to avoid littering the user's session history with sub-agent sessions.
7. 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.

Commands

# Review current branch against main (with --allowedTools, prompt via stdin)
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 3 --no-session-persistence \
    --allowedTools "Bash(git:*)" "Read" "Glob" "Grep" 2>&1

# Simpler review without tool restrictions (prompt as positional arg)
claude -p --max-turns 3 --no-session-persistence \
  'Review the changes on this branch vs main. Focus on error handling and security. Run `git diff main...HEAD`.' \
  2>&1

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

CLI Anti-Patterns

# 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: No --max-turns — sub-claude may exhaust turns on tool calls
claude -p 'Review...'

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

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>	Limit tool-use turns. Use 1 for prompt-only, 3 for reviews, 5 for deep digs
--tools ""	Disable all tools — forces a single-turn text response
--allowedTools "..."	Restrict to specific tools. Variadic — must pipe prompt via stdin when used
--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.