Claude Code 编码代理

委派编码任务给 Claude Code CLI（功能开发、PR 提交）

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.

前置条件

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:

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:

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 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  Down && sleep 0.3 && tmux send-keys -t  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

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  --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:

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

Model & Performance

Permission & Safety

Output & Input Format

System Prompt & Context

Debugging

Agent Teams

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____   # Specific MCP tool

Settings & Configuration

Settings Hierarchy (highest to lowest priority)

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

Use the # prefix in interactive mode to quickly add to memory: # Always use 2-space indentation.

Interactive Session: Slash Commands

Session & Context

Development & Review

配置 & Tools

Custom Slash Commands

Create .claude/commands/.md (project-shared) or ~/.claude/commands/.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

Mode Toggles

Multiline Input

Input Prefixes

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:

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//memory/.

Custom Subagents

Define specialized agents in .claude/agents/ (project), ~/.claude/agents/ (personal), or via --agents CLI flag (session):

Agent Location Priority

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 Environment Variables

安全说明 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

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

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:

Context Window Health

Use /context in interactive mode to see a colored grid of context usage. Key thresholds:

环境要求 Variables

Cost & Performance Tips

Pitfalls & Gotchas

Rules for Hermes Agents

Claude Code 终端编程完全指南

npm install -g @anthropic-ai/claude-code
npx claude-code

claude-code
# 解释代码
"请解释 src/utils/auth.js 的工作原理"
# 重构代码
"将这个函数重构为 TypeScript，并添加类型注解"
# 写测试
"为这个模块生成 Jest 单元测试"