Claude Code CLI

Claude Code Skill

Delegate coding tasks to the Claude Code CLI via background process with PTY or headless pipe mode.

PTY Mode Required (Interactive)

Claude Code is an interactive terminal application that needs a pseudo-terminal (PTY). Without PTY, output breaks or the agent hangs.

Always use pty:true for interactive mode:

# ✅ Correct - with PTY
exec pty:true command:"claude 'Your prompt'"

# ❌ Wrong - no PTY, agent may break
exec command:"claude 'Your prompt'"

Two Modes

1. Interactive PTY Mode

For tasks where Claude Code may ask confirmations, need input, or show permission prompts.

# Foreground (waits for completion)
exec pty:true workdir:~/project command:"claude 'Add dark mode toggle'"

# Background (returns sessionId)
exec pty:true workdir:~/project background:true command:"claude 'Build REST API for todos'"

2. Headless Pipe Mode

For automation, scripting, CI-like usage. Uses -p flag for non-interactive.

# Simple one-shot
exec command:"claude -p 'Explain what src/main.ts does' --output-format json"

# With structured output validation
exec command:"claude -p 'List all exported functions in src/' --output-format json --json-schema '{\"type\":\"object\",\"properties\":{\"functions\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}}}'"

# Budget-capped automation
exec command:"claude -p 'Refactor auth module' --max-budget-usd 5.00 --output-format json"

# Real-time streaming output (JSON chunks as they arrive)
exec command:"claude -p 'Build a helper function' --output-format stream-json"

Exec & Process Tool Reference

Exec Tool Parameters

Process Tool Actions (for background sessions)

Key CLI Flags

Permission Modes

System Prompt Modes

Use --append-system-prompt to add context or constraints. Use --system-prompt only when you need full control over the prompt (rare).

Granular Tool Restrictions

Restrict Claude Code's Bash tool to specific subcommands:

exec pty:true command:"claude --allowedTools 'Bash(git:*,npm:*),Read,Edit,Write,Glob,Grep' 'Your task'"

Session Continuity

Track and resume sessions across conversations.

# Start a task
exec pty:true workdir:~/project background:true command:"claude --permission-mode acceptEdits 'Build feature X'"

# Continue latest session
exec pty:true workdir:~/project command:"claude --continue"

# Resume specific session by ID
exec pty:true workdir:~/project command:"claude --resume abc123"

# Resume with interactive search (finds sessions matching the term)
exec pty:true workdir:~/project command:"claude --resume 'auth module'"

# Fork when resuming (creates new session ID, preserves original)
exec pty:true workdir:~/project command:"claude --continue --fork-session"

# Resume session linked to a PR
exec pty:true workdir:~/project command:"claude --from-pr 130"

# List recent sessions (find session IDs)
exec command:"claude sessions list"

HANDOFF.md Pattern (Long Sessions)

For tasks that exceed context limits, write progress to a handoff file:

# In the Claude Code session, ask it to write progress
# Then start a fresh session picking up from the handoff
exec pty:true workdir:~/project command:"claude 'Read HANDOFF.md and continue the work described there'"

Patterns

Quick Start: One-Shot Task

# Foreground with PTY
exec pty:true workdir:~/project command:"claude --permission-mode acceptEdits 'Add error handling to API calls'"

# Headless one-shot
exec command:"claude -p 'Summarize the codebase structure' --output-format json"

Background Task with Monitoring

# 1. Start
exec pty:true workdir:~/project background:true timeout:3600 command:"claude --permission-mode acceptEdits 'Build a complete auth module with JWT tokens'"

# 2. Monitor
process action:log sessionId:XXX
process action:poll sessionId:XXX

# 3. Send input if needed
process action:submit sessionId:XXX data:"yes"

# 4. Kill if stuck
process action:kill sessionId:XXX

PR Review (Safe — Never in Live Workspace)

⚠️ CRITICAL: Never review PRs in OpenClaw's own project folder!

# Clone to temp dir and checkout PR
exec command:"git clone https://github.com/user/repo.git /tmp/pr-review && cd /tmp/pr-review && gh pr checkout 130"

exec pty:true workdir:/tmp/pr-review command:"claude --permission-mode plan 'Review this PR. Focus on bugs, security issues, and performance. Show diff summary.'"

# Clean up
exec command:"rm -rf /tmp/pr-review"

Parallel Issue Fixing with Git Worktrees

# 1. Create worktrees
exec command:"git worktree add -b fix/issue-78 /tmp/issue-78 main"
exec command:"git worktree add -b fix/issue-99 /tmp/issue-99 main"

# 2. Launch Claude Code in each (background + PTY)
exec pty:true workdir:/tmp/issue-78 background:true command:"claude --permission-mode acceptEdits 'Fix issue #78: <description>. Commit when done.

When finished, run: openclaw system event --text \"Done: Fixed issue #78\" --mode now'"

exec pty:true workdir:/tmp/issue-99 background:true command:"claude --permission-mode acceptEdits 'Fix issue #99: <description>. Commit when done.

When finished, run: openclaw system event --text \"Done: Fixed issue #99\" --mode now'"

# 3. Monitor
process action:list

# 4. Create PRs
exec command:"cd /tmp/issue-78 && git push -u origin fix/issue-78"
exec command:"gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'"

# 5. Cleanup
exec command:"git worktree remove /tmp/issue-78"
exec command:"git worktree remove /tmp/issue-99"

Fan-Out Pattern (Bulk Operations)

Distribute work across parallel headless invocations:

# Migrate multiple files in parallel (shell script via exec)
exec command:"for file in \$(cat files-to-migrate.txt); do claude -p \"Migrate \$file to new API\" --output-format json --max-budget-usd 1.00 & done; wait"

Writer/Reviewer Pattern (Dual Sessions)

Two parallel sessions — one implements, one reviews:

# Session A: implement
exec pty:true workdir:~/project background:true command:"claude --permission-mode acceptEdits 'Implement the feature described in SPEC.md'"

# Session B: review (read-only)
exec pty:true workdir:~/project background:true command:"claude --permission-mode plan 'Watch for new changes and review them. Focus on correctness and test coverage.'"

Inline Dynamic Subagents

Define agents without any files on disk:

exec pty:true command:"claude --agents '{
  \"code-reviewer\": {
    \"description\": \"Expert code reviewer\",
    \"prompt\": \"You are a senior code reviewer. Focus on correctness, security, and performance.\",
    \"tools\": [\"Read\", \"Grep\", \"Glob\", \"Bash\"],
    \"model\": \"sonnet\"
  },
  \"implementer\": {
    \"description\": \"Feature implementer\",
    \"prompt\": \"You implement features following existing patterns.\",
    \"tools\": [\"Read\", \"Edit\", \"Write\", \"Bash\", \"Glob\", \"Grep\"],
    \"model\": \"sonnet\"
  }
}'"

Auto-Notify on Completion

For long-running background tasks, append a wake trigger so OpenClaw gets notified immediately:

exec pty:true workdir:~/project background:true command:"claude --permission-mode acceptEdits 'Build a REST API for todos.

When completely finished, run this command to notify me:
openclaw system event --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'"

Progress Updates

When spawning background agents, keep the user informed:

• Send 1 short message on start (what's running + where)
• Update only on changes: milestone complete, agent needs input, error, or finish
• If killing a session, say why immediately
• Never let the user see "Agent failed" with zero context

Safety Rules

1. Always use pty:true for interactive mode
2. Use --permission-mode acceptEdits for background tasks to prevent prompt stalls
3. Never run in ~/.openclaw/ workspace
4. Never checkout branches in live OpenClaw project dir
5. --dangerously-skip-permissions gets explicit danger warning — prefer acceptEdits
6. Respect user's tool choice — don't silently take over if agent fails
7. Be patient — don't kill sessions because they're "slow"
8. Budget cap automation — use --max-budget-usd for unattended headless runs
9. Max 3-4 active sessions — more causes resource contention
10. Timeout guidance — use 1800s+ for real tasks, don't let timeouts kill mid-work