name: claude-code
description: Run Claude Code CLI for AI-powered coding, debugging, refactoring, and codebase exploration. Use when needing to: (1) Build features from descriptions, (2) Debug and fix issues, (3) Navigate or understand codebases, (4) Automate tedious coding tasks, (5) Create commits and PRs, (6) Run code reviews, (7) Write tests. Triggers on mentions of "claude code", "claude cli", or coding agent tasks.
metadata: {"openclaw":{"emoji":"🔷","requires":{"bins":["claude"]}}}

Claude Code CLI

Claude Code is Anthropic's official AI coding assistant that runs in your terminal. It can edit files, run commands, and create commits directly.

⚠️ PTY Mode Required

Claude Code is an interactive terminal application. Always use pty:true:

# ✅ Correct
bash pty:true command:"claude 'Your task here'"

# ❌ Wrong - may break
bash command:"claude 'Your task here'"

Quick Reference

Headless Mode (-p flag)

For programmatic/scripted use, the -p flag runs Claude Code non-interactively:

# Simple query
bash pty:true command:"claude -p 'Explain this codebase'"

# With output format
bash pty:true command:"claude -p 'Summarize project' --output-format json"

# Auto-approve specific tools
bash pty:true command:"claude -p 'Fix auth.py' --allowedTools 'Read,Edit,Bash'"

# Continue previous conversation
bash pty:true command:"claude -p 'Now add tests' --continue"

Output Formats

Key CLI Flags

Common Workflows

Build Features

bash pty:true workdir:~/project command:"claude -p 'Add a dark mode toggle to the settings page' --allowedTools 'Read,Edit,Bash'"

Debug Issues

bash pty:true workdir:~/project command:"claude -p 'Fix this error: <paste error>' --allowedTools 'Read,Edit,Bash'"

Code Review

bash pty:true workdir:~/project command:"claude -p 'Review the changes in this PR and suggest improvements' --permission-mode plan"

Create Commits

bash pty:true workdir:~/project command:"claude -p 'Create a commit with descriptive message' --allowedTools 'Bash(git *)'"

Write Tests

bash pty:true workdir:~/project command:"claude -p 'Write unit tests for the auth module' --allowedTools 'Read,Edit,Bash'"

Explore Codebase (Read-Only)

bash pty:true workdir:~/project command:"claude --permission-mode plan -p 'Explain the architecture of this project'"

Background Mode for Long Tasks

For longer tasks, run in background:

# Start in background
bash pty:true workdir:~/project background:true command:"claude -p 'Refactor the entire auth system' --allowedTools 'Read,Edit,Bash'"
# Returns sessionId

# Monitor progress
process action:log sessionId:XXX

# Check if done
process action:poll sessionId:XXX

# Kill if needed
process action:kill sessionId:XXX

Parallel Work with Git Worktrees

For multiple tasks in parallel:

# Create worktrees
git worktree add -b feature/auth /tmp/auth main
git worktree add -b feature/api /tmp/api main

# Launch Claude in each (background)
bash pty:true workdir:/tmp/auth background:true command:"claude -p 'Implement OAuth2 login'"
bash pty:true workdir:/tmp/api background:true command:"claude -p 'Add REST endpoints for users'"

# Monitor
process action:list

# Create PRs after completion
cd /tmp/auth && git push -u origin feature/auth
gh pr create --title "feat: OAuth2 login"

Session Management

# Continue last conversation
claude -c

# Resume specific session
claude --resume <session-id>

# Resume by name
claude --resume "auth-refactor"

# Fork a session (create new from existing)
claude --resume abc123 --fork-session

Plan Mode (Safe Exploration)

For read-only analysis without changes:

# Start in plan mode
bash pty:true command:"claude --permission-mode plan"

# Headless plan mode
bash pty:true command:"claude --permission-mode plan -p 'Analyze security vulnerabilities'"

Plan mode:
- Only uses read-only operations
- Perfect for code review and exploration
- No file edits or dangerous commands

Piping and Unix Integration

Claude Code works as a Unix utility:

# Pipe input
cat error.log | claude -p "Explain this error"

# Pipe output
claude -p "List all TODO comments" > todos.txt

# In scripts
echo "$(claude -p 'Generate a random UUID')"

Custom Subagents (--agents flag)

Define specialized agents on the fly:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer",
    "prompt": "You are a senior code reviewer. Focus on quality, security, best practices.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

Auto-Notify on Completion

For background tasks, add wake trigger:

bash pty:true workdir:~/project background:true command:"claude -p 'Build the API.

When finished, run: openclaw gateway wake --text \"Done: API built\" --mode now'"

Rules

1. Always use pty:true - Claude Code needs a terminal
2. Use workdir - Keep Claude focused on the right directory
3. Use -p for scripts - Headless mode for automation
4. Use --permission-mode plan - For safe read-only exploration
5. Monitor background tasks - Check progress with process:log
6. Notify on completion - Add wake trigger for long tasks