---

name: claude-code description: Run Claude Code CLI (Anthropic's official coding agent) for software development tasks. Use when the user explicitly requests Claude Code, or when working on coding tasks that benefit from Anthropic's Claude models. Supports project scaffolding, code generation, refactoring, debugging, and code review.

Claude Code

Run Claude Code — Anthropic's official CLI coding agent powered by Claude models.

⚠️ PTY Mode Required!

Claude Code is an interactive terminal application that needs a pseudo-terminal (PTY) to work correctly. Without PTY, you'll get broken output, missing colors, or the agent may hang.

Always use pty:true when running Claude Code:

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

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

Installation

# Install via npm (requires Node.js)
npm install -g @anthropic-ai/claude-code

# Or via Homebrew (macOS)
brew install claude-code

# Verify installation
claude --version

API Key Setup: Claude Code requires an Anthropic API key. Set it via:

export ANTHROPIC_API_KEY="your-api-key"
# Or configure via: claude config

Quick Start

One-Shot Tasks

# Simple task with PTY
exec pty:true command:"claude 'Add error handling to api.js'"

# In specific directory
exec pty:true workdir:/path/to/project command:"claude 'Refactor the auth module'"

# Background mode for longer tasks
exec pty:true workdir:/path/to/project background:true command:"claude 'Build a REST API for user management'"

Interactive Mode

# Start interactive session
exec pty:true command:"claude"

# Interactive in specific directory
exec pty:true workdir:/path/to/project command:"claude"

Common Use Cases

Code Generation

# Create new component
exec pty:true workdir:./src command:"claude 'Create a React component for user profile with avatar, name, and bio'"

# Generate utility function
exec pty:true command:"claude 'Write a TypeScript function to debounce async operations'"

# Scaffold project structure
exec pty:true workdir:./new-project command:"claude 'Set up a Node.js Express API with TypeScript, Jest, and ESLint'"

Code Review & Analysis

# Review specific file
exec pty:true command:"claude 'Review src/utils/auth.ts for security issues'"

# Analyze code quality
exec pty:true workdir:./src command:"claude 'Analyze the codebase for performance bottlenecks'"

# Review PR changes
exec pty:true command:"claude 'Review the changes in this PR and suggest improvements'"

Refactoring

# Refactor legacy code
exec pty:true command:"claude 'Refactor app.js to use modern ES6+ syntax and improve readability'"

# Extract components
exec pty:true command:"claude 'Extract reusable components from Dashboard.jsx'"

# Optimize performance
exec pty:true command:"claude 'Optimize the database queries in users.controller.js'"

Debugging

# Fix bugs
exec pty:true command:"claude 'Debug the infinite loop in calculateTotal() function'"

# Resolve errors
exec pty:true command:"claude 'Fix the TypeScript compilation errors in the types/ directory'"

# Add logging
exec pty:true command:"claude 'Add comprehensive logging to the payment processing module'"

Testing

# Write tests
exec pty:true command:"claude 'Write Jest unit tests for src/utils/validation.js with 90% coverage'"

# Add test cases
exec pty:true command:"claude 'Add edge case tests for the date parsing function'"

# Fix failing tests
exec pty:true command:"claude 'Fix the failing integration tests in __tests__/api.test.js'"

Command-Line Flags

# Specify model (defaults to claude-3-5-sonnet-latest)
claude --model claude-3-opus-20240229 "Your task"

# Set temperature
claude --temperature 0.7 "Your task"

# Max tokens
claude --max-tokens 4000 "Your task"

# Verbose output
claude --verbose "Your task"

# Help
claude --help

Background Mode Pattern

For long-running tasks, use background mode and monitor progress:

# Start in background
exec pty:true workdir:~/project background:true command:"claude 'Build a full authentication system with JWT'"

# Monitor progress (returns sessionId)
process action:log sessionId:XXX

# Check if still running
process action:poll sessionId:XXX

# Kill if needed
process action:kill sessionId:XXX

Progress Updates

When spawning Claude Code in background mode, keep the user informed:

1. On start: Brief message about what's running and where
2. During execution: Only update when:
   • Agent asks a question / needs input
   • Milestone completes (tests pass, build finishes)
   • Error occurs requiring user action
   • Task finishes (summary of what changed)
3. On completion or kill: Always notify user immediately

Example:

✅ Started Claude Code in ~/project: Building authentication system (background mode)
[wait for completion or milestones]
✅ Done: Built JWT auth with login, register, and token refresh endpoints

Auto-Notify on Completion

For long-running background tasks, add a notification command to your prompt:

exec pty:true workdir:~/project background:true command:"claude 'Build a todo app with React.

When completely finished, run:
openclaw system event --text \"Done: Built React todo app with CRUD operations\" --mode now'"

This triggers an immediate wake event instead of waiting for the next heartbeat.

Working with Git

Claude Code works best in git repositories:

# In existing repo
exec pty:true workdir:~/my-repo command:"claude 'Add user authentication'"

# Create temp repo for experiments
SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && claude 'Build a calculator CLI'

Parallel Execution

Run multiple Claude Code instances for parallel work:

# Use git worktrees for isolation
git worktree add -b feature/auth /tmp/auth-work main
git worktree add -b feature/api /tmp/api-work main

# Launch parallel instances
exec pty:true workdir:/tmp/auth-work background:true command:"claude 'Implement OAuth2 authentication'"
exec pty:true workdir:/tmp/api-work background:true command:"claude 'Build REST API endpoints'"

# Monitor all
process action:list

# Cleanup after
git worktree remove /tmp/auth-work
git worktree remove /tmp/api-work

Comparison to Other Coding Agents

| Feature | Claude Code | Codex (Clawd) | Cursor | |---------------------|-------------|---------------|------------| | Provider | Anthropic | OpenAI | OpenAI | | CLI | ✅ | ✅ | ❌ (GUI) | | PTY Required | ✅ | ✅ | N/A | | Background Mode | ✅ | ✅ | N/A | | Auto-approval | Context-dep | --full-auto | Manual | | Git Integration | ✅ | ✅ | ✅ |

When to use Claude Code:

• User explicitly requests Claude Code or Anthropic models
• Tasks requiring strong reasoning and code understanding
• Complex refactoring or architecture design
• Code review and security analysis

When to use Codex instead:

• User requests Codex/Clawd specifically
• Fast iteration cycles with --yolo mode
• Tasks benefiting from OpenAI's model strengths

Best Practices

1. Always use PTY mode - pty:true is non-negotiable for interactive CLIs
2. Set working directory - Use workdir: to focus the agent's context
3. Use background mode for long tasks - Don't block on multi-step operations
4. Monitor don't micromanage - Use process:log to check progress without interfering
5. Provide clear prompts - Specific tasks work better than vague requests
6. Review before committing - Always review generated code before pushing
7. Use git worktrees for parallel work - Isolate concurrent tasks properly

Troubleshooting

Claude Code hangs or produces garbled output

• Fix: Always use pty:true - coding agents need a terminal

"API key not found" error

• Fix: Set ANTHROPIC_API_KEY environment variable or run claude config

Claude Code modifies wrong files

• Fix: Use workdir: to constrain the agent's scope

Background task seems stuck

• Fix: Check logs with process action:log sessionId:XXX - agent may be waiting for confirmation

Agent refuses to run outside git repo

• Fix: Initialize a git repo: git init or use existing repo

Advanced: Custom Models & Settings

# Use specific Claude model
claude --model claude-3-opus-20240229 "Complex architecture design task"

# Adjust creativity (temperature)
claude --temperature 0.2 "Write precise unit tests"  # Lower = more deterministic
claude --temperature 0.9 "Brainstorm API design ideas"  # Higher = more creative

# Increase output length
claude --max-tokens 8000 "Generate comprehensive documentation"

Reference Files

For detailed information, see:

• EXAMPLES.md - Real-world usage examples
• TROUBLESHOOTING.md - Common issues and solutions

---

Rules

1. Always use pty:true - coding agents need a terminal!
2. Respect user's tool choice - if they ask for Claude Code, use Claude Code (not Codex)
3. Monitor, don't take over - if agent struggles, respawn it or ask user, don't silently hand-code
4. Update user on progress - especially for background tasks
5. Review generated code - never blindly commit without checking
6. Use workdir - keep agent focused on relevant files
7. Clean up - remove temp directories and git worktrees after use