name: claude-code description: > Orchestrate Claude Code as an autonomous coding agent. OpenClaw acts as supervisor — spawning tasks, monitoring progress, approving routine decisions, and only escalating critical items to the user. Two modes: headless (claude -p) for fully autonomous tasks, and supervised interactive for complex work requiring mid-task decisions. metadata: { "openclaw": { "emoji": "🤖", "os": ["darwin", "linux"], "requires": { "bins": ["claude"] }, }, }

Claude Code

You are the orchestrator. Claude Code is your coding agent. You supervise it, make routine decisions on its behalf, and only escalate critical items to the user.

Decision Framework

When Claude Code asks a question or needs a decision, apply this framework:

Tier 1: Auto-approve (never ask the user)

• File reads, writes, edits (any file in the project)
• Running tests, linting, type-checking, building
• Installing dev dependencies
• Creating branches, committing code
• Reading docs, searching code, using grep/glob
• Retrying after transient errors (API 500, rate limits, timeouts)
• Choosing between reasonable implementation approaches
• Running formatters or code fixers

Tier 2: You decide (use your judgment, don't ask the user)

• "Should I refactor X or Y?" — pick the better approach and tell Claude Code
• "Tests are failing, what should I do?" — analyze the failure, instruct retry or different approach
• "This file is large, should I split it?" — yes, generally
• "I found multiple bugs, which should I fix first?" — prioritize and instruct
• "Should I add tests?" — yes, always
• "The existing code does X, should I change it?" — if it's related to the task, yes
• Nudging when stuck — if Claude Code loops or stalls, give it a different angle
• Compacting when context is long — send /compact

Tier 3: Escalate to user (always ask first)

• Destructive actions: deleting repos, force-pushing, dropping databases
• Deployments: pushing to production, publishing packages
• External services: making API calls to third-party services, sending emails
• Cost decisions: actions that cost real money beyond the current task
• Security: changing auth, modifying secrets, adjusting permissions
• Scope changes: "this is a bigger change than expected, should I proceed?"
• Genuine uncertainty: you truly don't know the right call

When escalating, message the user with a concise summary and options:

"Claude Code is working on [task] and needs a decision: [situation]. Options:

1. [option A]
2. [option B] What should I tell it?"

Mode 1: Headless (fully autonomous)

Use claude -p for tasks where Claude Code can run start-to-finish without needing mid-task decisions. This is the cleanest path — no permission prompts, structured output, no monitoring needed.

# Standard autonomous task
bash command:"claude -p 'Fix the typo in README.md' --output-format json --allowedTools 'Bash,Read,Edit,Write,Glob,Grep' --permission-mode acceptEdits --max-turns 10" workdir:~/project

# Bigger task with cost cap
bash command:"claude -p 'Refactor auth module into separate files and add tests' --output-format json --allowedTools 'Bash,Read,Edit,Write,Glob,Grep' --permission-mode acceptEdits --max-turns 30 --max-budget-usd 10.00" workdir:~/project

# Background (for long tasks — you get auto-notified on completion)
bash background:true command:"claude -p 'Write comprehensive tests for src/api/' --output-format json --allowedTools 'Bash,Read,Edit,Write,Glob,Grep' --permission-mode acceptEdits --max-turns 30 --max-budget-usd 10.00" workdir:~/project

Required flags (always include these)

| Flag | Value | Why | |------|-------|-----| | -p | (flag) | Non-interactive mode | | --output-format | json | Structured, parseable output | | --allowedTools | 'Bash,Read,Edit,Write,Glob,Grep' | Pre-approve tools — no stalls | | --permission-mode | acceptEdits | Auto-approve file changes | | --max-turns | 10-30 depending on task | Prevent runaway |

Optional flags

| Flag | When to use | |------|------------| | --max-budget-usd N | Cost cap for expensive tasks | | --model sonnet\|opus\|haiku | Model selection (default is usually fine) | | --resume SESSION_ID | Continue a previous session | | --append-system-prompt "..." | Add task-specific instructions | | --json-schema '{...}' | Get validated structured output |

Parsing results

# Extract the result text
echo "$output" | jq -r '.result'

# Check for errors
echo "$output" | jq -r '.is_error'

# Get cost
echo "$output" | jq -r '.total_cost_usd'

Mode 2: Interactive (only when user explicitly asks)

Interactive mode runs Claude Code with a PTY. Use it only when the user specifically wants to interact with Claude Code mid-task.

Limitation: You cannot actively poll at second-level intervals. Once Claude Code is running in background, you only find out what happened when:

• The process exits (OpenClaw's exec system auto-notifies)
• The user asks you to check on it
• A heartbeat fires (minute-level, not seconds)

This means Claude Code can stall on permission prompts with nobody to approve them. Prefer headless mode to avoid this entirely.

Launch

bash pty:true workdir:~/project background:true command:"claude 'Fix the flaky integration tests in src/api/.'"

Check on it (when user asks or on heartbeat)

# See what's happening
process action:log sessionId:XXX

# If it's waiting for permission — approve it (Tier 1)
process action:submit sessionId:XXX data:"y"

# If it's asking a question — decide (Tier 2) or escalate (Tier 3)
process action:submit sessionId:XXX data:"Your answer here"

# If it's done
process action:kill sessionId:XXX

⚠️ CLAUDECODE env var

When launched from within Claude Code (common in OpenClaw), the subprocess inherits a CLAUDECODE env var that prevents nesting. Pass CLAUDECODE= (empty) as an env override in the exec tool to clear it.

⚠️ Why headless is better

In interactive mode, Claude Code can sit waiting for approval for minutes with no one checking. Headless mode with --allowedTools and --permission-mode acceptEdits pre-approves everything, so it never stalls.

Choosing a Mode

| Scenario | Mode | Why | |----------|------|-----| | Fix a bug | Headless | Well-scoped, auto-approve everything | | Add a feature | Headless | Clear requirements, no mid-task decisions | | Code review | Headless | Pipe in diff, get structured result | | Refactor a module | Headless (background) | Auto-approve edits, cost-cap | | Write tests | Headless (background) | Autonomous, just needs time | | Debug complex issue | Headless (background) | Give it freedom, check result | | Multi-file feature | Headless (background) | Auto-approve, high max-turns | | Parallel tasks | Headless (multiple background) | Each one independent | | User wants interactive | Interactive | Only when explicitly requested |

Always use headless unless the user specifically asks for interactive mode.

Rules

1. You are the supervisor, not a relay — make Tier 1 and 2 decisions yourself
2. Default to headless — covers 80% of tasks with zero supervision needed
3. Always set --allowedTools + --permission-mode acceptEdits — no stalls
4. Always set --max-turns — prevents runaway
5. Monitor supervised sessions proactively — don't wait to be asked
6. Report results — always tell the user what Claude Code did
7. Don't hand-code — if asked to use Claude Code, delegate to it
8. Parse JSON — use jq -r '.result' to extract useful output
9. Escalate only Tier 3 — everything else, you handle

Parallel Tasks

bash background:true command:"claude -p 'Fix auth bug' --output-format json --allowedTools 'Bash,Read,Edit,Write,Glob,Grep' --permission-mode acceptEdits --max-turns 10" workdir:~/project
bash background:true command:"claude -p 'Add tests for utils/' --output-format json --allowedTools 'Bash,Read,Edit,Write,Glob,Grep' --permission-mode acceptEdits --max-turns 15" workdir:~/project
bash background:true command:"claude -p 'Update API docs' --output-format json --allowedTools 'Bash,Read,Edit,Write,Glob,Grep' --permission-mode acceptEdits --max-turns 10" workdir:~/project

# Each auto-notifies on completion via OpenClaw's exec system events
process action:list