| name | claude-code |
| description | 将编码任务委派给 Claude Code（Anthropic 的 CLI 代理）。用于构建功能、重构、PR 审查和迭代编码。需要安装 claude CLI。
Use when: claude code, 编码任务, coding task, 代码审查, code review, 重构, refactoring, PR审查, Claude CLI.
Do NOT use for:
- Hermes 配置问题（用 hermes-agent skill）
- Codex/OpenCode 任务（用 codex/opencode skills）
- 非编码任务（用相应 skills）
- 批量文件操作（用 file/terminal 工具）
|
| version | 2.3.0 |
| author | Hermes Agent + Teknium |
| license | MIT |
| keywords | ["claude code","编码任务","coding task","代码审查","code review","重构","refactoring","Claude CLI"] |
| triggers | ["claude code","编码任务","coding task","代码审查","code review","重构","refactoring","PR审查"] |
| metadata | {"hermes":{"tags":["Coding-Agent","Claude","Anthropic","Code-Review","Refactoring","PTY","Automation"],"related_skills":["codex","hermes-agent","opencode"]}} |
Claude Code — Hermes Orchestration Guide
Delegate coding tasks to Claude Code (Anthropic's autonomous coding agent CLI) via the Hermes terminal. Claude Code v2.x can read files, write code, run shell commands, spawn subagents, and manage git workflows autonomously.
Prerequisites
- Install:
npm install -g @anthropic-ai/claude-code
- Auth: run
claude once to log in (browser OAuth for Pro/Max, or set ANTHROPIC_API_KEY)
- Console auth:
claude auth login --console for API key billing
- SSO auth:
claude auth login --sso for Enterprise
- Check status:
claude auth status (JSON) or claude auth status --text (human-readable)
- Health check:
claude doctor — checks auto-updater and installation health
- Version check:
claude --version (requires v2.x+)
- Update:
claude update or claude upgrade
Two Orchestration Modes
Hermes interacts with Claude Code in two fundamentally different ways. Choose based on the task.
Mode 1: Print Mode (-p) — Non-Interactive (PREFERRED for most tasks)
Print mode runs a one-shot task, returns the result, and exits. No PTY needed. No interactive prompts. This is the cleanest integration path.
terminal(command="claude -p 'Add error handling to all API calls in src/' --allowedTools 'Read,Edit' --max-turns 10", workdir="/path/to/project", timeout=120)
When to use print mode:
- One-shot coding tasks (fix a bug, add a feature, refactor)
- CI/CD automation and scripting
- Structured data extraction with
--json-schema
- Piped input processing (
cat file | claude -p "analyze this")
- Any task where you don't need multi-turn conversation
Print mode skips ALL interactive dialogs — no workspace trust prompt, no permission confirmations. This makes it ideal for automation.
Mode 2: Interactive PTY via tmux — Multi-Turn Sessions
Interactive mode gives you a full conversational REPL where you can send follow-up prompts, use slash commands, and watch Claude work in real time. Requires tmux orchestration.
# Start a tmux session
terminal(command="tmux new-session -d -s claude-work -x 140 -y 40")
# Launch Claude Code inside it
terminal(command="tmux send-keys -t claude-work 'cd /path/to/project && claude' Enter")
# Wait for startup, then send your task
# (after ~3-5 seconds for the welcome screen)
terminal(command="sleep 5 && tmux send-keys -t claude-work 'Refactor the auth module to use JWT tokens' Enter")
# Monitor progress by capturing the pane
terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -50")
# Send follow-up tasks
terminal(command="tmux send-keys -t claude-work 'Now add unit tests for the new JWT code' Enter")
# Exit when done
terminal(command="tmux send-keys -t claude-work '/exit' Enter")
When to use interactive mode:
- Multi-turn iterative work (refactor → review → fix → test cycle)
- Tasks requiring human-in-the-loop decisions
- Exploratory coding sessions
- When you need to use Claude's slash commands (
/compact, /review, /model)
PTY Dialog Handling (CRITICAL for Interactive Mode)
Claude Code presents up to two confirmation dialogs on first launch. You MUST handle these via tmux send-keys:
Dialog 1: Workspace Trust (first visit to a directory)
❯ 1. Yes, I trust this folder ← DEFAULT (just press Enter)
2. No, exit
Handling: tmux send-keys -t <session> Enter — default selection is correct.
Dialog 2: Bypass Permissions Warning (only with --dangerously-skip-permissions)
❯ 1. No, exit ← DEFAULT (WRONG choice!)
2. Yes, I accept
Handling: Must navigate DOWN first, then Enter:
tmux send-keys -t <session> Down && sleep 0.3 && tmux send-keys -t <session> Enter
Robust Dialog Handling Pattern
# Launch with permissions bypass
terminal(command="tmux send-keys -t claude-work 'claude --dangerously-skip-permissions \"your task\"' Enter")
# Handle trust dialog (Enter for default "Yes")
terminal(command="sleep 4 && tmux send-keys -t claude-work Enter")
# Handle permissions dialog (Down then Enter for "Yes, I accept")
terminal(command="sleep 3 && tmux send-keys -t claude-work Down && sleep 0.3 && tmux send-keys -t claude-work Enter")
# Now wait for Claude to work
terminal(command="sleep 15 && tmux capture-pane -t claude-work -p -S -60")
Note: After the first trust acceptance for a directory, the trust dialog won't appear again. Only the permissions dialog recurs each time you use --dangerously-skip-permissions.
CLI Subcommands
| Subcommand | Purpose |
|---|
claude | Start interactive REPL |
claude "query" | Start REPL with initial prompt |
claude -p "query" | Print mode (non-interactive, exits when done) |
cat file | claude -p "query" | Pipe content as stdin context |
claude -c | Continue the most recent conversation in this directory |
claude -r "id" | Resume a specific session by ID or name |
claude auth login | Sign in (add --console for API billing, --sso for Enterprise) |
claude auth status | Check login status (returns JSON; --text for human-readable) |
claude mcp add <name> -- <cmd> | Add an MCP server |
claude mcp list | List configured MCP servers |
claude mcp remove <name> | Remove an MCP server |
claude agents | List configured agents |
claude doctor | Run health checks on installation and auto-updater |
claude update / claude upgrade | Update Claude Code to latest version |
claude remote-control | Start server to control Claude from claude.ai or mobile app |
claude install [target] | Install native build (stable, latest, or specific version) |
claude setup-token | Set up long-lived auth token (requires subscription) |
claude plugin / claude plugins | Manage Claude Code plugins |
claude auto-mode | Inspect auto mode classifier configuration |
Print Mode Deep Dive
Structured JSON Output
terminal(command="claude -p 'Analyze auth.py for security issues' --output-format json --max-turns 5", workdir="/project", timeout=120)
Returns a JSON object with:
{
"type": "result",
"subtype": "success",
"result": "The analysis text...",
"session_id": "75e2167f-...",
"num_turns": 3,
"total_cost_usd": 0.0787,
"duration_ms": 10276,
"stop_reason": "end_turn",
"terminal_reason": "completed",
"usage": { "input_tokens": 5, "output_tokens": 603, ... },
"modelUsage": { "claude-sonnet-4-6": { "costUSD": 0.078, "contextWindow": 200000 } }
}
Key fields: session_id for resumption, num_turns for agentic loop count, total_cost_usd for spend tracking, subtype for success/error detection (success, error_max_turns, error_budget).
Streaming JSON Output
For real-time token streaming, use stream-json with --verbose:
terminal(command="claude -p 'Write a summary' --output-format stream-json --verbose --include-partial-messages", timeout=60)
Returns newline-delimited JSON events. Filter with jq for live text:
claude -p "Explain X" --output-format stream-json --verbose --include-partial-messages | \
jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
Stream events include system/api_retry with attempt, max_retries, and error fields (e.g., rate_limit, billing_error).
Bidirectional Streaming
For real-time input AND output streaming:
claude -p "task" --input-format stream-json --output-format stream-json --replay-user-messages
--replay-user-messages re-emits user messages on stdout for acknowledgment.
Piped Input
# Pipe a file for analysis
terminal(command="cat src/auth.py | claude -p 'Review this code for bugs' --max-turns 1", timeout=60)
# Pipe multiple files
terminal(command="cat src/*.py | claude -p 'Find all TODO comments' --max-turns 1", timeout=60)
# Pipe command output
terminal(command="git diff HEAD~3 | claude -p 'Summarize these changes' --max-turns 1", timeout=60)
JSON Schema for Structured Extraction
terminal(command="claude -p 'List all functions in src/' --output-format json --json-schema '{\"type\":\"object\",\"properties\":{\"functions\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"functions\"]}' --max-turns 5", workdir="/project", timeout=90)
Parse structured_output from the JSON result. Claude validates output against the schema before returning.
Session Continuation
# Start a task
terminal(command="claude -p 'Start refactoring the database layer' --output-format json --max-turns 10 > /tmp/session.json", workdir="/project", timeout=180)
# Resume with session ID
terminal(command="claude -p 'Continue and add connection pooling' --resume $(cat /tmp/session.json | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"session_id\"])') --max-turns 5", workdir="/project", timeout=120)
# Or resume the most recent session in the same directory
terminal(command="claude -p 'What did you do last time?' --continue --max-turns 1", workdir="/project", timeout=30)
# Fork a session (new ID, keeps history)
terminal(command="claude -p 'Try a different approach' --resume <id> --fork-session --max-turns 10", workdir="/project", timeout=120)
Bare Mode for CI/Scripting
terminal(command="claude --bare -p 'Run all tests and report failures' --allowedTools 'Read,Bash' --max-turns 10", workdir="/project", timeout=180)
--bare skips hooks, plugins, MCP discovery, and CLAUDE.md loading. Fastest startup. Requires ANTHROPIC_API_KEY (skips OAuth).
To selectively load context in bare mode:
| To load | Flag |
|---|
| System prompt additions | --append-system-prompt "text" or --append-system-prompt-file path |
| Settings | --settings <file-or-json> |
| MCP servers | --mcp-config <file-or-json> |
| Custom agents | --agents '<json>' |
Fallback Model for Overload
terminal(command="claude -p 'task' --fallback-model haiku --max-turns 5", timeout=90)
Automatically falls back to the specified model when the default is overloaded (print mode only).
Complete CLI Flags Reference
Session & Environment
| Flag | Effect |
|---|
-p, --print | Non-interactive one-shot mode (exits when done) |
-c, --continue | Resume most recent conversation in current directory |
-r, --resume <id> | Resume specific session by ID or name (interactive picker if no ID) |
--fork-session | When resuming, create new session ID instead of reusing original |
--session-id <uuid> | Use a specific UUID for the conversation |
--no-session-persistence | Don't save session to disk (print mode only) |
--add-dir <paths...> | Grant Claude access to additional working directories |
-w, --worktree [name] | Run in an isolated git worktree at .claude/worktrees/<name> |
--tmux | Create a tmux session for the worktree (requires --worktree) |
--ide | Auto-connect to a valid IDE on startup |
--chrome / --no-chrome | Enable/disable Chrome browser integration for web testing |
--from-pr [number] | Resume session linked to a specific GitHub PR |
--file <specs...> | File resources to download at startup (format: file_id:relative_path) |
Model & Performance
| Flag | Effect |
|---|
--model <alias> | Model selection: sonnet, opus, haiku, or full name like claude-sonnet-4-6 |
--effort <level> | Reasoning depth: low, medium, high, max, auto |
--max-turns <n> | Limit agentic loops (print mode only; prevents runaway) |
--max-budget-usd <n> | Cap API spend in dollars (print mode only) |
--fallback-model <model> | Auto-fallback when default model is overloaded (print mode only) |
--betas <betas...> | Beta headers to include in API requests (API key users only) |
Permission & Safety
| Flag | Effect |
|---|
--dangerously-skip-permissions | Auto-approve ALL tool use (file writes, bash, network, etc.) |
--allow-dangerously-skip-permissions | Enable bypass as an option without enabling it by default |
--permission-mode <mode> | default, acceptEdits, plan, auto, dontAsk, bypassPermissions |
--allowedTools <tools...> | Whitelist specific tools (comma or space-separated) |
--disallowedTools <tools...> | Blacklist specific tools |
--tools <tools...> | Override built-in tool set ("" = none, "default" = all, or tool names) |
Output & Input Format
| Flag | Effect |
|---|
--output-format <fmt> | text (default), json (single result object), stream-json (newline-delimited) |
--input-format <fmt> | text (default) or stream-json (real-time streaming input) |
--json-schema <schema> | Force structured JSON output matching a schema |
--verbose | Full turn-by-turn output |
--include-partial-messages | Include partial message chunks as they arrive (stream-json + print) |
--replay-user-messages | Re-emit user messages on stdout (stream-json bidirectional) |
System Prompt & Context
| Flag | Effect |
|---|
--append-system-prompt <text> | Add to the default system prompt (preserves built-in capabilities) |
--append-system-prompt-file <path> | Add file contents to the default system prompt |
--system-prompt <text> | Replace the entire system prompt (use --append instead usually) |
--system-prompt-file <path> | Replace the system prompt with file contents |
--bare | Skip hooks, plugins, MCP discovery, CLAUDE.md, OAuth (fastest startup) |
--agents '<json>' | Define custom subagents dynamically as JSON |
--mcp-config <path> | Load MCP servers from JSON file (repeatable) |
--strict-mcp-config | Only use MCP servers from --mcp-config, ignoring all other MCP configs |
--settings <file-or-json> | Load additional settings from a JSON file or inline JSON |
--setting-sources <sources> | Comma-separated sources to load: user, project, local |
--plugin-dir <paths...> | Load plugins from directories for this session only |
--disable-slash-commands | Disable all skills/slash commands |
Debugging
| Flag | Effect |
|---|
-d, --debug [filter] | Enable debug logging with optional category filter (e.g., "api,hooks", "!1p,!file") |
--debug-file <path> | Write debug logs to file (implicitly enables debug mode) |
Agent Teams
| Flag | Effect |
|---|
--teammate-mode <mode> | How agent teams display: auto, in-process, or tmux |
--brief | Enable SendUserMessage tool for agent-to-user communication |
Tool Name Syntax for --allowedTools / --disallowedTools
Read # All file reading
Edit # File editing (existing files)
Write # File creation (new files)
Bash # All shell commands
Bash(git *) # Only git commands
Bash(git commit *) # Only git commit commands
Bash(npm run lint:*) # Pattern matching with wildcards
WebSearch # Web search capability
WebFetch # Web page fetching
mcp__<server>__<tool> # Specific MCP tool
Settings & Configuration
Settings Hierarchy (highest to lowest priority)
- CLI flags — override everything
- Local project:
.claude/settings.local.json (personal, gitignored)
- Project:
.claude/settings.json (shared, git-tracked)
- User:
~/.claude/settings.json (global)
Permissions in Settings
{
"permissions": {
"allow": ["Bash(npm run lint:*)", "WebSearch", "Read"],
"ask": ["Write(*.ts)", "Bash(git push*)"],
"deny": ["Read(.env)", "Bash(rm -rf *)"]
}
}
Memory Files (CLAUDE.md) Hierarchy
- Global:
~/.claude/CLAUDE.md — applies to all projects
- Project:
./CLAUDE.md — project-specific context (git-tracked)
- Local:
.claude/CLAUDE.local.md — personal project overrides (gitignored)
Use the # prefix in interactive mode to quickly add to memory: # Always use 2-space indentation.
Interactive Session: Slash Commands
Session & Context
| Command | Purpose |
|---|
/help | Show all commands (including custom and MCP commands) |
/compact [focus] | Compress context to save tokens; CLAUDE.md survives compaction. E.g., /compact focus on auth logic |
/clear | Wipe conversation history for a fresh start |
/context | Visualize context usage as a colored grid with optimization tips |
/cost | View token usage with per-model and cache-hit breakdowns |
/resume | Switch to or resume a different session |
/rewind | Revert to a previous checkpoint in conversation or code |
/btw <question> | Ask a side question without adding to context cost |
/status | Show version, connectivity, and session info |
/todos | List tracked action items from the conversation |
/exit or Ctrl+D | End session |
Development & Review
| Command | Purpose |
|---|
/review | Request code review of current changes |
/security-review | Perform security analysis of current changes |
/plan [description] | Enter Plan mode with auto-start for task planning |
/loop [interval] | Schedule recurring tasks within the session |
/batch | Auto-create worktrees for large parallel changes (5-30 worktrees) |
Configuration & Tools
| Command | Purpose |
|---|
/model [model] | Switch models mid-session (use arrow keys to adjust effort) |
/effort [level] | Set reasoning effort: low, medium, high, max, or auto |
/init | Create a CLAUDE.md file for project memory |
/memory | Open CLAUDE.md for editing |
/config | Open interactive settings configuration |
/permissions | View/update tool permissions |
/agents | Manage specialized subagents |
/mcp | Interactive UI to manage MCP servers |
/add-dir | Add additional working directories (useful for monorepos) |
/usage | Show plan limits and rate limit status |
/voice | Enable push-to-talk voice mode (20 languages; hold Space to record, release to send) |
/release-notes | Interactive picker for version release notes |
Custom Slash Commands
Create .claude/commands/<name>.md (project-shared) or ~/.claude/commands/<name>.md (personal):
# .claude/commands/deploy.md
Run the deploy pipeline:
1. Run all tests
2. Build the Docker image
3. Push to registry
4. Update the $ARGUMENTS environment (default: staging)
Usage: /deploy production — $ARGUMENTS is replaced with the user's input.
Skills (Natural Language Invocation)
Unlike slash commands (manually invoked), skills in .claude/skills/ are markdown guides that Claude invokes automatically via natural language when the task matches:
# .claude/skills/database-migration.md
When asked to create or modify database migrations:
1. Use Alembic for migration generation
2. Always create a rollback function
3. Test migrations against a local database copy
Interactive Session: Keyboard Shortcuts
General Controls
| Key | Action |
|---|
Ctrl+C | Cancel current input or generation |
Ctrl+D | Exit session |
Ctrl+R | Reverse search command history |
Ctrl+B | Background a running task |
Ctrl+V | Paste image into conversation |
Ctrl+O | Transcript mode — see Claude's thinking process |
Ctrl+G or Ctrl+X Ctrl+E | Open prompt in external editor |
Esc Esc | Rewind conversation or code state / summarize |
Mode Toggles
| Key | Action |
|---|
Shift+Tab | Cycle permission modes (Normal → Auto-Accept → Plan) |
Alt+P | Switch model |
Alt+T | Toggle thinking mode |
Alt+O | Toggle Fast Mode |
Multiline Input
| Key | Action |
|---|
\ + Enter | Quick newline |
Shift+Enter | Newline (alternative) |
Ctrl+J | Newline (alternative) |
Input Prefixes
| Prefix | Action |
|---|
! | Execute bash directly, bypassing AI (e.g., !npm test). Use ! alone to toggle shell mode. |
@ | Reference files/directories with autocomplete (e.g., @./src/api/) |
# | Quick add to CLAUDE.md memory (e.g., # Use 2-space indentation) |
/ | Slash commands |
Pro Tip: "ultrathink"
Use the keyword "ultrathink" in your prompt for maximum reasoning effort on a specific turn. This triggers the deepest thinking mode regardless of the current /effort setting.
PR Review Pattern
Quick Review (Print Mode)
terminal(command="cd /path/to/repo && git diff main...feature-branch | claude -p 'Review this diff for bugs, security issues, and style problems. Be thorough.' --max-turns 1", timeout=60)
Deep Review (Interactive + Worktree)
terminal(command="tmux new-session -d -s review -x 140 -y 40")
terminal(command="tmux send-keys -t review 'cd /path/to/repo && claude -w pr-review' Enter")
terminal(command="sleep 5 && tmux send-keys -t review Enter") # Trust dialog
terminal(command="sleep 2 && tmux send-keys -t review 'Review all changes vs main. Check for bugs, security issues, race conditions, and missing tests.' Enter")
terminal(command="sleep 30 && tmux capture-pane -t review -p -S -60")
PR Review from Number
terminal(command="claude -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10", workdir="/path/to/repo", timeout=120)
Claude Worktree with tmux
terminal(command="claude -w feature-x --tmux", workdir="/path/to/repo")
Creates an isolated git worktree at .claude/worktrees/feature-x AND a tmux session for it. Uses iTerm2 native panes when available; add --tmux=classic for traditional tmux.
Parallel Claude Instances
Run multiple independent Claude tasks simultaneously:
# Task 1: Fix backend
terminal(command="tmux new-session -d -s task1 -x 140 -y 40 && tmux send-keys -t task1 'cd ~/project && claude -p \"Fix the auth bug in src/auth.py\" --allowedTools \"Read,Edit\" --max-turns 10' Enter")
# Task 2: Write tests
terminal(command="tmux new-session -d -s task2 -x 140 -y 40 && tmux send-keys -t task2 'cd ~/project && claude -p \"Write integration tests for the API endpoints\" --allowedTools \"Read,Write,Bash\" --max-turns 15' Enter")
# Task 3: Update docs
terminal(command="tmux new-session -d -s task3 -x 140 -y 40 && tmux send-keys -t task3 'cd ~/project && claude -p \"Update README.md with the new API endpoints\" --allowedTools \"Read,Edit\" --max-turns 5' Enter")
# Monitor all
terminal(command="sleep 30 && for s in task1 task2 task3; do echo '=== '$s' ==='; tmux capture-pane -t $s -p -S -5 2>/dev/null; done")
CLAUDE.md — Project Context File
Claude Code auto-loads CLAUDE.md from the project root. Use it to persist project context:
# Project: My API
## Architecture
- FastAPI backend with SQLAlchemy ORM
- PostgreSQL database, Redis cache
- pytest for testing with 90% coverage target
## Key Commands
- `make test` — run full test suite
- `make lint` — ruff + mypy
- `make dev` — start dev server on :8000
## Code Standards
- Type hints on all public functions
- Docstrings in Google style
- 2-space indentation for YAML, 4-space for Python
- No wildcard imports
Be specific. Instead of "Write good code", use "Use 2-space indentation for JS" or "Name test files with .test.ts suffix." Specific instructions save correction cycles.
Rules Directory (Modular CLAUDE.md)
For projects with many rules, use the rules directory instead of one massive CLAUDE.md:
- Project rules:
.claude/rules/*.md — team-shared, git-tracked
- User rules:
~/.claude/rules/*.md — personal, global
Each .md file in the rules directory is loaded as additional context. This is cleaner than cramming everything into a single CLAUDE.md.
Auto-Memory
Claude automatically stores learned project context in ~/.claude/projects/<project>/memory/.
- Limit: 25KB or 200 lines per project
- This is separate from CLAUDE.md — it's Claude's own notes about the project, accumulated across sessions
Custom Subagents
Define specialized agents in .claude/agents/ (project), ~/.claude/agents/ (personal), or via --agents CLI flag (session):
Agent Location Priority
.claude/agents/ — project-level, team-shared--agents CLI flag — session-specific, dynamic~/.claude/agents/ — user-level, personal
Creating an Agent
# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Security-focused code review
model: opus
tools: [Read, Bash]
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication/authorization flaws
- Secrets in code
- Unsafe deserialization
Invoke via: @security-reviewer review the auth module
Dynamic Agents via CLI
terminal(command="claude --agents '{\"reviewer\": {\"description\": \"Reviews code\", \"prompt\": \"You are a code reviewer focused on performance\"}}' -p 'Use @reviewer to check auth.py'", timeout=120)
Claude can orchestrate multiple agents: "Use @db-expert to optimize queries, then @security to audit the changes."
Hooks — Automation on Events
Configure in .claude/settings.json (project) or ~/.claude/settings.json (global):
{
"hooks": {
"PostToolUse": [{
"matcher": "Write(*.py)",
"hooks": [{"type": "command", "command": "ruff check --fix $CLAUDE_FILE_PATHS"}]
}],
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{"type": "command", "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'rm -rf'; then echo 'Blocked!' && exit 2; fi"}]
}],
"Stop": [{
"hooks": [{"type": "command", "command": "echo 'Claude finished a response' >> /tmp/claude-activity.log"}]
}]
}
}
All 8 Hook Types
| Hook | When it fires | Common use |
|---|
UserPromptSubmit | Before Claude processes a user prompt | Input validation, logging |
PreToolUse | Before tool execution | Security gates, block dangerous commands (exit 2 = block) |
PostToolUse | After a tool finishes | Auto-format code, run linters |
Notification | On permission requests or input waits | Desktop notifications, alerts |
Stop | When Claude finishes a response | Completion logging, status updates |
SubagentStop | When a subagent completes | Agent orchestration |
PreCompact | Before context memory is cleared | Backup session transcripts |
SessionStart | When a session begins | Load dev context (e.g., git status) |
Hook Environment Variables
| Variable | Content |
|---|
CLAUDE_PROJECT_DIR | Current project path |
CLAUDE_FILE_PATHS | Files being modified |
CLAUDE_TOOL_INPUT | Tool parameters as JSON |
Security Hook Examples
{
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{"type": "command", "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|git push.*--force|:(){ :|:& };:'; then echo 'Dangerous command blocked!' && exit 2; fi"}]
}]
}
MCP Integration
Add external tool servers for databases, APIs, and services:
# GitHub integration
terminal(command="claude mcp add -s user github -- npx @modelcontextprotocol/server-github", timeout=30)
# PostgreSQL queries
terminal(command="claude mcp add -s local postgres -- npx @anthropic-ai/server-postgres --connection-string postgresql://localhost/mydb", timeout=30)
# Puppeteer for web testing
terminal(command="claude mcp add puppeteer -- npx @anthropic-ai/server-puppeteer", timeout=30)
MCP Scopes
| Flag | Scope | Storage |
|---|
-s user | Global (all projects) | ~/.claude.json |
-s local | This project (personal) | .claude/settings.local.json (gitignored) |
-s project | This project (team-shared) | .claude/settings.json (git-tracked) |
MCP in Print/CI Mode
terminal(command="claude --bare -p 'Query database' --mcp-config mcp-servers.json --strict-mcp-config", timeout=60)
--strict-mcp-config ignores all MCP servers except those from --mcp-config.
Reference MCP resources in chat: @github:issue://123
MCP Limits & Tuning
- Tool descriptions: 2KB cap per server for tool descriptions and server instructions
- Result size: Default capped; use
maxResultSizeChars annotation to allow up to 500K characters for large outputs
- Output tokens:
export MAX_MCP_OUTPUT_TOKENS=50000 — cap output from MCP servers to prevent context flooding
- Transports:
stdio (local process), http (remote), sse (server-sent events)
Monitoring Interactive Sessions
Reading the TUI Status
# Periodic capture to check if Claude is still working or waiting for input
terminal(command="tmux capture-pane -t dev -p -S -10")
Look for these indicators:
❯ at bottom = waiting for your input (Claude is done or asking a question)● lines = Claude is actively using tools (reading, writing, running commands)⏵⏵ bypass permissions on = status bar showing permissions mode◐ medium · /effort = current effort level in status barctrl+o to expand = tool output was truncated (can be expanded interactively)
Context Window Health
Use /context in interactive mode to see a colored grid of context usage. Key thresholds:
- < 70% — Normal operation, full precision
- 70-85% — Precision starts dropping, consider
/compact
- > 85% — Hallucination risk spikes significantly, use
/compact or /clear
Environment Variables
| Variable | Effect |
|---|
ANTHROPIC_API_KEY | API key for authentication (alternative to OAuth) |
CLAUDE_CODE_EFFORT_LEVEL | Default effort: low, medium, high, max, or auto |
MAX_THINKING_TOKENS | Cap thinking tokens (set to 0 to disable thinking entirely) |
MAX_MCP_OUTPUT_TOKENS | Cap output from MCP servers (default varies; set e.g., 50000) |
CLAUDE_CODE_NO_FLICKER=1 | Enable alt-screen rendering to eliminate terminal flicker |
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB | Strip credentials from sub-processes for security |
Cost & Performance Tips
- Use
--max-turns in print mode to prevent runaway loops. Start with 5-10 for most tasks.
- Use
--max-budget-usd for cost caps. Note: minimum ~$0.05 for system prompt cache creation.
- Use
--effort low for simple tasks (faster, cheaper). high or max for complex reasoning.
- Use
--bare for CI/scripting to skip plugin/hook discovery overhead.
- Use
--allowedTools to restrict to only what's needed (e.g., Read only for reviews).
- Use
/compact in interactive sessions when context gets large.
- Pipe input instead of having Claude read files when you just need analysis of known content.
- Use
--model haiku for simple tasks (cheaper) and --model opus for complex multi-step work.
- Use
--fallback-model haiku in print mode to gracefully handle model overload.
- Start new sessions for distinct tasks — sessions last 5 hours; fresh context is more efficient.
- Use
--no-session-persistence in CI to avoid accumulating saved sessions on disk.
设计哲学：98.4%是工程，不是AI
核心理念：模型能力再强，如果没有好的"Harness"（鞍具），也无法在具体项目中发挥价值。详见 references/architecture-design-philosophy.md。
Harness隐喻
「一匹马可以跑得很快很有力，但它自己不知道往哪儿走：整套挽具决定了它的方向。」
- 方向盘：指引方向（CLAUDE.md、Skills）
- 刹车：安全保障（Hooks、权限系统）
- 导航：上下文理解（上下文管理、文档）
能力占比真相
| 维度 | 传统认知 | 实际真相 |
|---|
| AI能力占比 | 认为是核心 | 仅占1.6% |
| 工程架构占比 | 被忽视 | 占98.4% |
今天就能做的3件事
- 建立CLAUDE.md：10分钟写完架构规则、命名约定、踩过的坑。AI犯错时先问：CLAUDE.md里缺了什么？
- 把重复做事变成Skill：Code review、commit message、发布说明——不该每天手敲提示词
- 在踩坑地方加Hook：最有杠杆的部分，用确定性代码做强制检查，不依赖AI变聪明
关键洞察
- Hook的核心不在写代码，而在写规则
- 不换模型，优化Harness也能显著提升效果（LangChain案例：52.8→66.5）
- 工程师价值从"我能写多少行代码"转向"我能为AI设计多严格的工作环境"
Pitfalls & Gotchas
- Interactive mode REQUIRES tmux — Claude Code is a full TUI app. Using
pty=true alone in Hermes terminal works but tmux gives you capture-pane for monitoring and send-keys for input, which is essential for orchestration.
--dangerously-skip-permissions dialog defaults to "No, exit" — you must send Down then Enter to accept. Print mode (-p) skips this entirely.--max-budget-usd minimum is ~$0.05 — system prompt cache creation alone costs this much. Setting lower will error immediately.--max-turns is print-mode only — ignored in interactive sessions.- Claude may use
python instead of python3 — on systems without a python symlink, Claude's bash commands will fail on first try but it self-corrects.
- Session resumption requires same directory —
--continue finds the most recent session for the current working directory.
--json-schema needs enough --max-turns — Claude must read files before producing structured output, which takes multiple turns.- Trust dialog only appears once per directory — first-time only, then cached.
- Background tmux sessions persist — always clean up with
tmux kill-session -t <name> when done.
- Slash commands (like
/commit) only work in interactive mode — in -p mode, describe the task in natural language instead.
--bare skips OAuth — requires ANTHROPIC_API_KEY env var or an apiKeyHelper in settings.- Context degradation is real — AI output quality measurably degrades above 70% context window usage. Monitor with
/context and proactively /compact.
Rules for Hermes Agents
- Prefer print mode (
-p) for single tasks — cleaner, no dialog handling, structured output
- Use tmux for multi-turn interactive work — the only reliable way to orchestrate the TUI
- Always set
workdir — keep Claude focused on the right project directory
- Set
--max-turns in print mode — prevents infinite loops and runaway costs
- Monitor tmux sessions — use
tmux capture-pane -t <session> -p -S -50 to check progress
- Look for the
❯ prompt — indicates Claude is waiting for input (done or asking a question)
- Clean up tmux sessions — kill them when done to avoid resource leaks
- Report results to user — after completion, summarize what Claude did and what changed
- Don't kill slow sessions — Claude may be doing multi-step work; check progress instead
- Use
--allowedTools — restrict capabilities to what the task actually needs
📋 检查点设计
检查点 1：环境准备验证
【前置检查】执行任务前必须验证：
which claude && claude --version
claude auth status --text
test -d "/path/to/project" && echo "✓ 目录存在" || echo "✗ 目录不存在"
验证清单：
检查点 2：Print Mode执行验证
【执行中监控】Print Mode关键指标：
claude -p "任务描述" --max-turns 10 --allowedTools "Read,Edit"
exit_code=$?
if [ $exit_code -eq 0 ]; then
echo "✓ 任务成功完成"
else
echo "✗ 任务失败，退出码: $exit_code"
fi
验证清单：
检查点 3：Interactive Mode会话验证
【会话管理】Interactive Mode关键节点：
tmux new-session -d -s claude-work -x 140 -y 40
echo "✓ tmux会话已创建"
tmux send-keys -t claude-work 'cd /project && claude' Enter
sleep 5
tmux send-keys -t claude-work Enter
sleep 3
tmux capture-pane -t claude-work -p -S -5 | grep "❯" && echo "✓ Claude已就绪"
验证清单：
检查点 4：任务完成验证
【结果验证】任务完成后必须检查：
claude -p "任务描述" --output-format json 2>&1 | jq -r '.status'
tmux capture-pane -t claude-work -p -S -50 | grep -E "(完成|finished|done|❯)"
git status --short
git diff --stat
验证清单：
⚠️ 异常处理
异常类型1：认证失败
症状：
Error: Not authenticated. Run 'claude auth login' first.
恢复流程：
claude auth status
claude auth login
claude auth login --console
claude auth status --text | grep "Logged in"
异常类型2：工作目录不存在
症状：
Error: Directory '/path/to/project' does not exist
恢复流程：
pwd
ls -la /path/to/project
mkdir -p /path/to/project
cd /path/to/project && claude -p "任务描述"
异常类型3：超时或卡死
症状：
- Print Mode长时间无输出（>5分钟）
- Interactive Mode无响应（>10分钟）
恢复流程：
claude -p "任务描述" --max-turns 5
tmux capture-pane -t claude-work -p -S -50
tmux kill-session -t claude-work
tmux new-session -d -s claude-work
异常类型4：权限被拒绝
症状：
Error: Permission denied: /path/to/file
恢复流程：
ls -la /path/to/file
chmod 644 /path/to/file
chmod 755 /path/to/dir
claude -p "任务描述"
异常类型5：模型过载
症状：
Error: Model overloaded. Please retry.
恢复流程：
claude -p "任务描述" --fallback-model haiku
claude -p "任务描述" --model haiku
sleep 60 && claude -p "任务描述"
异常类型6：上下文窗口溢出
症状：
Error: Context window exceeded. Use /compact or reduce input size.
恢复流程：
tmux send-keys -t claude-work '/compact' Enter
sleep 5
claude -p "分析单个文件" --allowedTools "Read"
claude -p "简要分析 auth.py"
异常类型7：tmux会话冲突
症状：
duplicate session
恢复流程：
tmux list-sessions
tmux kill-session -t claude-work
tmux new-session -d -s claude-work
异常类型8：预算超限
症状：
Error: Budget exceeded ($X.XX used, limit was $Y.YY)
恢复流程：
claude -p "任务描述" --max-budget-usd 1.00
claude -p "任务描述" --model haiku
claude -p "任务描述" --max-turns 3
🎯 边界条件
资源边界
| 资源 | 最小值 | 最大值 | 推荐值 | 说明 |
|---|
| max-turns | 1 | 100 | 5-20 | Print Mode专用 |
| max-budget-usd | $0.05 | 无限制 | $0.10-1.00 | 最低$0.05用于缓存 |
| 上下文窗口 | - | 200K tokens | <70% | 超过70%质量下降 |
| 会话时长 | - | 5小时 | 1-2小时 | 之后需新会话 |
并发边界
| 场景 | 限制 | 说明 |
|---|
| Print Mode并发 | 建议≤3个 | 避免API限流 |
| Interactive Mode会话 | 建议≤2个 | tmux资源消耗 |
| 文件操作 | 单次≤100文件 | 避免上下文溢出 |
性能边界
| 指标 | 目标值 | 告警阈值 | 说明 |
|---|
| Print Mode响应时间 | <30秒 | >60秒 | 简单任务 |
| Interactive Mode首次响应 | <10秒 | >20秒 | 复杂任务可能更长 |
| 文件读取速度 | <1秒/文件 | >3秒/文件 | 大文件例外 |
使用场景边界
适用场景 ✅：
- 代码重构和优化
- Bug修复和调试
- 代码审查和改进
- 文档生成
- 测试编写
- API集成
不适用场景 ❌：
- 实时性要求高的任务（<5秒响应）
- 大规模文件批量处理（>100文件）
- 需要图形界面的操作
- 系统级配置修改
- 敏感数据处理（无审计）
📊 成功指标
| 指标 | 目标 | 测量方法 |
|---|
| 任务成功率 | >95% | exit_code=0的比例 |
| 代码质量 | 无阻塞性问题 | 人工审查或CI检查 |
| 响应速度 | <60秒 | 简单任务完成时间 |
| 成本控制 | <$1.00/任务 | max-budget-usd监控 |
🔄 恢复策略总结
| 异常类型 | 自动恢复 | 人工介入 | 预防措施 |
|---|
| 认证失败 | ❌ | ✅ 重登录 | 定期检查认证状态 |
| 目录不存在 | ✅ 自动创建 | ❌ | 前置检查 |
| 超时卡死 | ✅ 重启任务 | ❌ | 设置合理max-turns |
| 权限拒绝 | ✅ 修改权限 | ❌ | 预先检查权限 |
| 模型过载 | ✅ fallback模型 | ❌ | 使用Haiku备用 |
| 上下文溢出 | ✅ /compact | ❌ | 监控上下文使用率 |
| tmux冲突 | ✅ 杀旧会话 | ❌ | 用后清理 |
| 预算超限 | ✅ 提高预算 | ❌ | 设置合理上限 |
⚠️ Known Gotchas
认证和权限问题
-
认证过期: Claude Code 会话失效
claude auth status
claude auth login
export ANTHROPIC_API_KEY="sk-ant-..."
claude auth login --console
-
权限不足: 无法访问项目目录
ls -la /path/to/project
chmod -R u+rw /path/to/project
sudo -u owner claude -p "task"
-
工作区信任失败: Print 模式跳过信任提示
claude -p "analyze code"
claude trust /path/to/project
claude -p "task"
Print 模式陷阱
-
超时未设置: 默认 60 秒不够
terminal("claude -p 'complex task'")
terminal(
"claude -p 'complex task' --max-turns 20",
timeout=300
)
-
JSON Schema 解析失败: 输出格式不符合预期
claude -p "extract APIs" \
--json-schema '{"type": "array", "items": {"type": "string"}}'
-
allowedTools 过宽: 给予过多权限
claude -p "task" --allowedTools "*"
claude -p "task" --allowedTools "Read,Edit,Write"
PTY/tmux 模式问题
-
tmux 会话残留: 未正确清理
tmux list-sessions
tmux kill-session -t claude-* 2>/dev/null
tmux kill-server
-
PTY 响应超时: 交互式提示卡住
process = terminal(
"claude",
background=True,
pty=True,
timeout=300
)
time.sleep(2)
output = process.poll()
-
多轮对话丢失上下文: 会话重启后失忆
session_id = save_session()
claude resume <session_id>
工具调用问题
-
Edit 工具失败: 文件内容不匹配
-
Bash 工具被禁: 安全策略限制
claude -p "list tools" --allowedTools "Read"
claude -p "task" --allowedTools "Read,Edit,Bash"
-
文件路径错误: 相对路径解析失败
claude -p "edit src/main.py"
terminal(
"claude -p 'edit src/main.py'",
workdir="/absolute/path/to/project"
)
成本控制问题
-
预算超支: 未设置 max-budget
claude -p "task" --max-budget-usd 1.00
-
Token 浪费: 重复读取大文件
for file in files:
claude -p f"read {file}"
claude -p f"read {' '.join(files)}"
-
模型选择错误: Sonnet/Opus 不匹配任务
claude -p "fix typo" --model claude-3-haiku
claude -p "refactor module" --model claude-3-sonnet
claude -p "architectural redesign" --model claude-3-opus
并发和冲突
-
多个 Claude 实例冲突: 同时修改同一文件
import fcntl
with open("/tmp/claude.lock", "w") as lock:
fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
terminal("claude -p 'task'")
fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
-
Git 冲突: Claude 提交与本地冲突
claude -p "git pull && make changes && git commit"
claude -p "git checkout -b feature/ai-gen && make changes"
-
IDE 文件监控: 文件变化触发重载
性能问题
-
启动慢: 首次运行需要初始化
claude --version
claude doctor
-
大文件处理慢: 文件超过 1MB
chunks = split_large_file(file, max_size=500000)
for chunk in chunks:
result = claude -p f"process: {chunk}"
-
网络延迟: API 调用慢
export ANTHROPIC_API_BASE="https://api.anthropic.com"
输出质量
-
代码风格不一致: 与项目规范冲突
claude -p "follow PEP 8, max line length 88"
-
生成代码有 Bug: 未经过测试
claude -p "implement feature X and write tests"
claude -p "write tests first, then implement"
-
理解偏差: 任务描述不清晰
claude -p "optimize code"
claude -p "optimize performance: reduce time complexity from O(n²) to O(n log n)"
兼容性问题
-
Node.js 版本不兼容: 需要 Node 18+
node --version
nvm install 18
nvm use 18
-
操作系统限制: Windows/WSL 路径问题
wsl claude -p "task"
-
环境变量缺失: ANTHROPIC_API_KEY 未设置
echo $ANTHROPIC_API_KEY
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc
