name: claude-code description: Run Claude Code for development tasks — headless (claude -p), interactive (tmux), or agent teams. Use when the user asks to build, develop, fix, refactor, or implement anything with Claude Code. Covers spec-driven development (spec-kit), agent teams orchestration, hooks, subagents, CLAUDE.md configuration, and session management.

Claude Code Skill

Operate Claude Code from OpenClaw to execute development tasks. All prompts/instructions to Claude Code must be in English. Generated products (apps, pages, docs) default to Traditional Chinese unless specified otherwise.

Execution Modes

1. Headless (Background — Default for OpenClaw automation)

Run via the wrapper script. Claude Code runs independently; OpenClaw is notified on completion.

nohup ~/.openclaw/workspace/.claude/hooks/run-task.sh "<task in English>" /path/to/workdir &

• Auto-enables agent teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)
• Uses claude -p --dangerously-skip-permissions
• Results written to .claude/hooks/task_YYYYMMDD_HHMMSS.md
• Completion triggers wake API → OpenClaw reads result → notifies user

2. Interactive (tmux — for complex/iterative work)

Launch Claude Code in a tmux session for slash commands, plan mode, and manual steering.

# Create tmux session
tmux new-session -d -s claude-dev -c /path/to/workdir
tmux send-keys -t claude-dev 'claude' Enter

Key interactive controls:

• Shift+Tab — cycle permission modes (Normal → Auto-Accept → Plan → Delegate)
• /model opus or /model sonnet — switch models
• /compact — compress context when running long
• Ctrl+C — cancel current generation
• @filepath — reference files directly

3. Agent Teams (parallel complex work)

Enable via environment or settings:

{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

Best for: parallel research, multi-module features, competing debug hypotheses, cross-layer changes.

Tell Claude to create teams naturally:

"Create an agent team: one on frontend, one on backend, one on tests."

Controls: Shift+Up/Down to select teammates, lead coordinates via shared task list.

Spec-Driven Development (spec-kit)

Use specify CLI for structured development. See references/spec-kit.md for full workflow.

Quick flow:

1. specify init <project> --ai claude — scaffold project
2. /speckit.constitution — set project principles
3. /speckit.specify <description> — write the spec (what + why)
4. /speckit.plan <tech choices> — create implementation plan
5. /speckit.tasks — break into actionable tasks
6. /speckit.implement — execute all tasks

For headless spec-driven development, compose the full task in the prompt:

nohup run-task.sh "Read spec.md, implement according to the spec. Iterate until all acceptance criteria pass. On each bug fix, document the lesson in CLAUDE.md." /path/to/project &

Error Sedimentation Principle

Every bug fix must produce a lasting lesson. When fixing errors:

1. Fix the immediate issue
2. Write the lesson as a rule/tip into CLAUDE.md or memory/
3. Ensure future runs benefit from the lesson

Project Configuration (CLAUDE.md)

Create CLAUDE.md in project root to guide Claude Code:

• Coding conventions, test patterns, architecture decisions
• Accumulated lessons from error sedimentation
• Tech stack specifics, deployment notes
• Run /init in interactive mode to generate a starter CLAUDE.md

Key CLI Flags

| Flag | Purpose | |------|---------| | -p | Print mode (headless, non-interactive) | | --dangerously-skip-permissions | Skip all permission prompts (sandboxed only) | | --model opus/sonnet/haiku | Select model | | --effort low/medium/high | Opus 4.6 reasoning depth | | --permission-mode plan | Read-only plan mode | | --allowedTools "Read,Edit,Bash" | Whitelist specific tools | | --output-format json | Structured JSON output | | --continue | Resume last conversation | | -r <session-id> | Resume specific session | | --max-budget-usd <n> | Cap API spend | | --append-system-prompt "<text>" | Add custom system instructions |

Hooks (Auto-callbacks)

Configured in .claude/settings.json. Current setup fires on Stop and SessionEnd:

• Writes result JSON to .claude/hooks/last-result.json
• Wakes OpenClaw via POST http://localhost:18789/api/wake

Available hook events: SessionStart, Stop, SessionEnd, PreToolUse, PostToolUse, TaskCompleted, SubagentStart/Stop, TeammateIdle.

Subagents

Built-in: Explore (fast read-only), Plan (research), General-purpose (full tools).

Custom subagents: create .claude/agents/<name>.md with YAML frontmatter:

---
name: reviewer
description: Reviews code for quality and security
model: sonnet
allowedTools: ["Read", "Grep", "Glob", "Bash(grep *)"]
---
You are a code reviewer. Focus on security, performance, and maintainability.

Model Selection Guide

| Task | Recommended | |------|-------------| | Complex architecture, planning | opus (high effort) | | Daily coding, implementation | sonnet | | Quick lookups, simple tasks | haiku | | Plan then execute | opusplan | | Long sessions (>200k tokens) | sonnet[1m] |