claude-code

Claude Code — Hermes 编排指南

通过 Hermes 终端，将编码任务委派给 Claude Code（Anthropic 的自主编码 Agent 命令行工具）。Claude Code v2.x 可以自主读取文件、编写代码、运行 shell 命令、启动子 Agent，并管理 git 工作流。

前置条件

• 安装： npm install -g @anthropic-ai/claude-code
• 身份验证： 运行一次 claude 登录（Pro/Max 使用浏览器 OAuth，或设置 ANTHROPIC_API_KEY）
• Console 身份验证： 运行 claude auth login --console，使用 API 密钥计费
• SSO 身份验证： 运行 claude auth login --sso，用于 Enterprise
• 检查状态： claude auth status（JSON）或 claude auth status --text（方便人类阅读）
• 运行状况检查： claude doctor — 检查自动更新程序和安装状态
• 检查版本： claude --version（需要 v2.x+）
• 更新： claude update 或 claude upgrade

两种编排模式

Hermes 与 Claude Code 交互的方式有两种，原理截然不同。请根据任务选择。

模式 1：打印模式（-p）— 非交互式（大多数任务的首选）

打印模式会执行一次性任务，返回结果后退出。无需 PTY，也不会出现交互式提示。这是最简洁的集成方式。

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)

适用场景：

• 一次性编码任务（修复错误、添加功能、重构）
• CI/CD 自动化和脚本编写
• 使用 --json-schema 提取结构化数据
• 处理管道输入（cat file | claude -p "analyze this"）
• 无需多轮对话的任务

打印模式会跳过所有交互式对话框 — 不会出现工作区信任提示或权限确认。因此，它非常适合自动化。

模式 2：通过 tmux 使用交互式 PTY — 多轮会话

交互模式会提供完整的对话式 REPL，你可以发送后续提示词、使用斜杠命令，并实时查看 Claude 的工作过程。需要通过 tmux 进行编排。

# 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")

适用场景：

• 多轮迭代工作（重构 → 审查 → 修复 → 测试循环）
• 需要人工参与决策的任务
• 探索性编码会话
• 需要使用 Claude 的斜杠命令（/compact、/review、/model）

PTY 对话框处理（交互模式的关键事项）

Claude Code 首次启动时最多会显示两个确认对话框。必须通过 tmux send-keys 处理：

对话框 1：工作区信任（首次访问某个目录）

❯ 1. Yes, I trust this folder    ← DEFAULT (just press Enter)
  2. No, exit

处理方式： tmux send-keys -t <session> Enter — 默认选项正确。

对话框 2：单项权限提示（常规流程）

每当某项工具使用需要批准（文件写入、shell 命令、网络访问）时，都会显示提示。请针对该提示单独作答 — 这与关闭整次运行中的所有提示不同：

# Read the prompt before answering it
terminal(command="tmux capture-pane -t <session> -p -S -30")
# Allow this one action (Enter = default "Yes"); Esc declines it
terminal(command="tmux send-keys -t <session> Enter")

切勿在计时器触发时盲目发送 Enter，以批准尚未读过的提示 — 这等于用更繁琐的方式设置绕过标志。

比完全绕过权限更受限的选择是选择加入 --permission-mode acceptEdits：工作目录中的文件编辑会自动获准，但 shell 和其他工具调用仍会提示。只有在检查任务后，于专用 worktree 中使用此选项。

稳健的对话框处理模式

# Default launch — keep permission prompts enabled
terminal(command="tmux send-keys -t claude-work 'claude \"your task\"' Enter")

# Handle trust dialog (Enter for default "Yes")
terminal(command="sleep 4 && 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")

注意： 接受某个目录的信任提示后，该目录将不再显示此提示。

选择加入：--dangerously-skip-permissions（仅限隔离环境）

这会在整次运行中关闭权限提示 — 授予文件系统、shell 和网络访问权限，且不再提示。仅在一次性 worktree 或隔离容器中使用才可接受。

❯ 1. No, exit                    ← DEFAULT (safe choice)
  2. Yes, I accept

接受方式：tmux send-keys -t <session> Down && sleep 0.3 && tmux send-keys -t <session> Enter

CLI 子命令

子命令	用途
claude	启动交互式 REPL
claude "query"	使用初始提示词启动 REPL
claude -p "query"	打印模式（非交互式，完成后退出）
cat file | claude -p "query"	将管道内容作为 stdin 上下文
claude -c	继续此目录中最近的对话
claude -r "id"	按 ID 或名称恢复指定会话
claude auth login	登录（添加 --console 以使用 API 计费，添加 --sso 以用于 Enterprise）
claude auth status	检查登录状态（返回 JSON；使用 --text 获取便于阅读的文本）
claude mcp add <name> -- <cmd>	添加 MCP 服务
claude mcp list	列出已配置的 MCP 服务
claude mcp remove <name>	移除 MCP 服务
claude agents	列出已配置的 Agent
claude doctor	对安装和自动更新程序运行健康检查
claude update / claude upgrade	将 Claude Code 更新到最新版本
claude remote-control	启动服务，以便通过 claude.ai 或移动应用控制 Claude
claude install [target]	安装原生构建版本（stable、latest 或指定版本）
claude setup-token	设置长期有效的身份验证令牌（需要订阅）
claude plugin / claude plugins	管理 Claude Code 插件
claude auto-mode	检查自动模式分类器配置

打印模式深入介绍

结构化 JSON 输出

terminal(command="claude -p 'Analyze auth.py for security issues' --output-format json --max-turns 5", workdir="/project", timeout=120)

返回包含以下内容的 JSON 对象：

{
  "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 } }
}

关键字段： session_id 用于恢复会话，num_turns 用于统计 Agent 循环次数，total_cost_usd 用于跟踪支出，subtype 用于检测成功或错误（success、error_max_turns、error_budget）。

流式 JSON 输出

如需实时令牌流式传输，请将 stream-json 与 --verbose 配合使用：

terminal(command="claude -p 'Write a summary' --output-format stream-json --verbose --include-partial-messages", timeout=60)

返回以换行符分隔的 JSON 事件。使用 jq 筛选实时文本：

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'

流事件包含 system/api_retry，其中带有 attempt、max_retries 和 error 字段（例如 rate_limit、billing_error）。

双向流式传输

如需实时流式传输输入和输出：

claude -p "task" --input-format stream-json --output-format stream-json --replay-user-messages

--replay-user-messages 会在 stdout 上重新输出用户消息以供确认。

管道输入

# 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

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)

从 JSON 结果中解析 structured_output。Claude 会在返回之前根据 schema 验证输出。

会话续接

# Start a task
terminal(command="claude -p 'Start refactoring the database layer' --output-format json --max-turns 10 > ~/.hermes/cache/scratch/session.json", workdir="/project", timeout=180)

# Resume with session ID
terminal(command="claude -p 'Continue and add connection pooling' --resume $(cat ~/.hermes/cache/scratch/session.json | python -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)

用于 CI/脚本的精简模式

terminal(command="claude --bare -p 'Run all tests and report failures' --allowedTools 'Read,Bash' --max-turns 10", workdir="/project", timeout=180)

--bare 会跳过钩子、插件、MCP 发现和 CLAUDE.md 加载。启动速度最快。需要 ANTHROPIC_API_KEY（跳过 OAuth）。

如需在精简模式下选择性加载上下文：

加载内容	标志
系统提示词补充内容	--append-system-prompt "text" 或 --append-system-prompt-file path
设置	--settings <file-or-json>
MCP 服务	--mcp-config <file-or-json>
自定义 Agent	--agents '<json>'

过载时的备用模型

terminal(command="claude -p 'task' --fallback-model haiku --max-turns 5", timeout=90)

默认模型过载时，会自动切换到指定模型（仅限打印模式）。

CLI 标志完整参考

会话与环境

标志	效果
-p, --print	非交互式单次运行模式（完成后退出）
-c, --continue	恢复当前目录中最近的对话
-r, --resume <id>	按 ID 或名称恢复指定会话（未提供 ID 时显示交互式选择器）
--fork-session	恢复会话时创建新的会话 ID，而非复用原 ID
--session-id <uuid>	为对话使用指定的 UUID
--no-session-persistence	不将会话保存到磁盘（仅限打印模式）
--add-dir <paths...>	授予 Claude 访问其他工作目录的权限
-w, --worktree [name]	在 .claude/worktrees/<name> 中的隔离 git worktree 内运行
--tmux	为 worktree 创建 tmux 会话（需要 --worktree）
--ide	启动时自动连接到有效的 IDE
--chrome / --no-chrome	启用/禁用用于 Web 测试的 Chrome 浏览器集成
--from-pr [number]	恢复与特定 GitHub PR 关联的会话
--file <specs...>	启动时下载文件资源（格式：file_id:relative_path）

模型与性能

标志	效果
--model <alias>	模型选择：sonnet、opus、haiku，或完整名称，例如 claude-sonnet-4-6
--effort <level>	推理深度：low、medium、high、xhigh、max
--max-turns <n>	限制 Agent 循环次数（仅限打印模式；防止无限运行）
--max-budget-usd <n>	将 API 开销上限设为指定美元金额（仅限打印模式）
--fallback-model <model>	默认模型过载时自动切换到备用模型（仅限打印模式）
--betas <betas...>	要包含在 API 请求中的 Beta 标头（仅限 API 密钥用户）

权限与安全

标志	效果
--dangerously-skip-permissions	仅限主动选择启用：禁用所有权限提示（文件写入、bash、网络）。仅用于一次性 worktree 或隔离容器——参见上文“主动选择启用”
--allow-dangerously-skip-permissions	将绕过权限检查设为可选项，但不默认启用
--permission-mode <mode>	default、acceptEdits、plan、auto、dontAsk、bypassPermissions
--allowedTools <tools...>	将指定工具加入白名单（以逗号或空格分隔）
--disallowedTools <tools...>	将指定工具加入黑名单
--tools <tools...>	覆盖内置工具集（"" = 无，"default" = 全部，或指定工具名称）

输出与输入格式

标志	效果
--output-format <fmt>	text（默认）、json（单个结果对象）、stream-json（以换行符分隔）
--input-format <fmt>	text（默认）或 stream-json（实时流式输入）
--json-schema <schema>	强制输出符合指定架构的结构化 JSON
--verbose	输出完整的逐轮信息
--include-partial-messages	收到消息分块时即纳入输出（stream-json + 打印模式）
--replay-user-messages	在 stdout 上重新输出用户消息（stream-json 双向模式）

系统提示词与上下文

标志	效果
--append-system-prompt <text>	追加到默认系统提示词（保留内置功能）
--append-system-prompt-file <path>	将文件内容追加到默认系统提示词
--system-prompt <text>	替换整个系统提示词（通常应改用 --append）
--system-prompt-file <path>	使用文件内容替换系统提示词
--bare	跳过钩子、插件、MCP 发现、CLAUDE.md、OAuth（启动最快）
--agents '<json>'	以 JSON 动态定义自定义子 Agent
--mcp-config <path>	从 JSON 文件加载 MCP 服务（可重复使用）
--strict-mcp-config	仅使用 --mcp-config 中的 MCP 服务，忽略所有其他 MCP 配置
--settings <file-or-json>	从 JSON 文件或内联 JSON 加载其他设置
--setting-sources <sources>	以逗号分隔的待加载来源：user、project、local
--plugin-dir <paths...>	仅为本次会话从目录加载插件
--disable-slash-commands	禁用所有技能和斜杠命令

调试

标志	效果
-d, --debug [filter]	启用调试日志记录，可选类别筛选器（例如 "api,hooks"、"!1p,!file"）
--debug-file <path>	将调试日志写入文件（会隐式启用调试模式）

Agent 团队

标志	效果
--teammate-mode <mode>	Agent 团队的显示方式：auto、in-process 或 tmux
--brief	启用 SendUserMessage 工具，用于 Agent 与用户之间的通信

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

设置与配置

设置层级（优先级从高到低）

1. CLI 标志 — 覆盖所有设置
2. 本地项目： .claude/settings.local.json（个人设置，由 Git 忽略）
3. 项目： .claude/settings.json（共享设置，由 Git 跟踪）
4. 用户： ~/.claude/settings.json（全局设置）

设置中的权限

{
  "permissions": {
    "allow": ["Bash(npm run lint:*)", "WebSearch", "Read"],
    "ask": ["Write(*.ts)", "Bash(git push*)"],
    "deny": ["Read(.env)", "Bash(rm -rf *)"]
  }
}

记忆文件（CLAUDE.md）层级

1. 全局： ~/.claude/CLAUDE.md — 适用于所有项目
2. 项目： ./CLAUDE.md — 项目专属上下文（由 Git 跟踪）
3. 本地： .claude/CLAUDE.local.md — 个人项目覆盖设置（由 Git 忽略）

在交互模式下使用 # 前缀可快速添加记忆：# Always use 2-space indentation。

交互会话：斜杠命令

会话与上下文

命令	用途
/help	显示所有命令（包括自定义命令和 MCP 命令）
/compact [focus]	压缩上下文以节省 token；压缩后 CLAUDE.md 仍会保留。例如：/compact focus on auth logic
/clear	清除对话历史，开始新会话
/context	以彩色网格直观呈现上下文用量，并提供优化建议
/cost	查看 token 用量，并按模型和缓存命中情况细分
/resume	切换到或恢复其他会话
/rewind	恢复对话或代码中的先前检查点
/btw <question>	提出旁支问题，不增加上下文成本
/status	显示版本、连接状态和会话信息
/todos	列出对话中跟踪的待办事项
/exit 或 Ctrl+D	结束会话

开发与审查

命令	用途
/review	请求审查当前更改的代码
/security-review	对当前更改进行安全分析
/plan [description]	进入计划模式，自动开始任务规划
/loop [interval]	在会话中安排重复任务
/batch	为大型并行更改自动创建工作树（5-30 个工作树）

配置与工具

命令	用途
/model [model]	在会话中途切换模型（使用方向键调整推理力度）
/effort [level]	设置推理力度：low、medium、high、xhigh 或 max
/init	创建 CLAUDE.md 文件以保存项目记忆
/memory	打开 CLAUDE.md 进行编辑
/config	打开交互式设置配置
/permissions	查看／更新工具权限
/agents	管理专用子 Agent
/mcp	使用交互式界面管理 MCP 服务
/add-dir	添加其他工作目录（适用于大型单体仓库）
/usage	显示套餐限额和速率限制状态
/voice	启用按键通话语音模式（支持 20 种语言；按住 Space 录音，松开即可发送）
/release-notes	通过交互式选择器查看版本发布说明

自定义斜杠命令

创建 .claude/commands/<name>.md（项目共享）或 ~/.claude/commands/<name>.md（个人）：

# .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)

用法：/deploy production — $ARGUMENTS 会替换为用户输入。

Skills（自然语言调用）

与斜杠命令（手动调用）不同，.claude/skills/ 中的 Skills 是 Markdown 指南，当任务匹配时，Claude 会通过自然语言自动调用：

# .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

交互式会话：键盘快捷键

常规控制

按键	操作
Ctrl+C	取消当前输入或生成
Ctrl+D	退出会话
Ctrl+R	反向搜索命令历史记录
Ctrl+B	将正在运行的任务转入后台
Ctrl+V	将图像粘贴到对话中
Ctrl+O	转录模式 — 查看 Claude 的思考过程
Ctrl+G 或 Ctrl+X Ctrl+E	在外部编辑器中打开提示词
Esc Esc	回退对话或代码状态／进行总结

模式切换

按键	操作
Shift+Tab	循环切换权限模式（Normal → Auto-Accept → Plan）
Alt+P	切换模型
Alt+T	切换思考模式
Alt+O	切换快速模式

多行输入

按键	操作
\ + Enter	快速换行
Shift+Enter	换行（替代方式）
Ctrl+J	换行（替代方式）

输入前缀

前缀	操作
!	直接执行 bash，绕过 AI（例如：!npm test）。单独使用 ! 可切换 Shell 模式。
@	通过自动补全引用文件／目录（例如：@./src/api/）
#	快速添加到 CLAUDE.md 记忆中（例如：# Use 2-space indentation）
/	斜杠命令

专业提示：“ultrathink”

在提示词中使用关键词 “ultrathink”，可在特定轮次启用最大推理力度。无论当前 /effort 设置如何，这都会触发最深入的思考模式。

PR 审查模式

快速审查（打印模式）

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)

深度审查（交互式 + 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

terminal(command="claude -p 'Review this PR thoroughly' --from-pr 42 --max-turns 10", workdir="/path/to/repo", timeout=120)

使用 tmux 的 Claude Worktree

terminal(command="claude -w feature-x --tmux", workdir="/path/to/repo")

在 .claude/worktrees/feature-x 创建隔离的 git worktree，并为其创建 tmux 会话。如果可用，则使用 iTerm2 原生窗格；添加 --tmux=classic 可使用传统 tmux。

并行运行多个 Claude 实例

同时运行多个相互独立的 Claude 任务：

# 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 — 项目上下文文件

Claude Code 会自动加载项目根目录中的 CLAUDE.md。使用它来持久保存项目上下文：

# 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

请提供具体说明。 不要只写“编写优质代码”，而应写“JS 使用 2 空格缩进”或“测试文件以 .test.ts 为后缀”。具体指示可以减少反复修正。

Rules 目录（模块化 CLAUDE.md）

对于规则较多的项目，可使用 rules 目录代替一个庞大的 CLAUDE.md：

• 项目规则： .claude/rules/*.md — 团队共享，纳入 Git 跟踪
• 用户规则： ~/.claude/rules/*.md — 个人使用，全局生效

rules 目录中的每个 .md 文件都会作为额外上下文加载。这样比把所有内容都塞进单个 CLAUDE.md 更清晰。

自动记忆

Claude 会自动将学到的项目上下文存储在 ~/.claude/projects/<project>/memory/ 中。

• 限制： 每个项目 25KB 或 200 行
• 这与 CLAUDE.md 分开，是 Claude 对项目自行记录的笔记，会在多个会话中不断积累

自定义子 Agent

在 .claude/agents/（项目级）、~/.claude/agents/（个人级）中定义专用 Agent，或通过 --agents CLI 标志（会话级）定义：

Agent 位置优先级

1. .claude/agents/ — 项目级，团队共享
2. --agents CLI 标志 — 会话专用，动态配置
3. ~/.claude/agents/ — 用户级，个人专用

创建 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

通过以下方式调用：@security-reviewer review the auth module

通过 CLI 创建动态 Agent

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 可以协调多个 Agent：“使用 @db-expert 优化查询，然后使用 @security 审查更改。”

Hooks — 事件自动化

在 .claude/settings.json（项目级）或 ~/.claude/settings.json（全局）中配置：

{
  "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' >> ~/.hermes/cache/scratch/claude-activity.log"}]
    }]
  }
}

全部 8 种 Hook 类型

Hook	触发时机	常见用途
UserPromptSubmit	Claude 处理用户提示词之前	输入验证、日志记录
PreToolUse	工具执行之前	安全检查、拦截危险命令（退出码 2 = 拦截）
PostToolUse	工具执行完成之后	自动格式化代码、运行代码检查工具
Notification	请求权限或等待输入时	桌面通知、提醒
Stop	Claude 完成响应时	完成情况日志记录、状态更新
SubagentStop	子 Agent 完成时	Agent 协调
PreCompact	清除上下文记忆之前	备份会话记录
SessionStart	会话开始时	加载开发上下文（例如，git status）

Hook 环境变量

变量	内容
CLAUDE_PROJECT_DIR	当前项目路径
CLAUDE_FILE_PATHS	正在修改的文件
CLAUDE_TOOL_INPUT	JSON 格式的工具参数

安全 Hook 示例

{
  "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 集成

添加用于数据库、API 和服务的外部工具服务：

# 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 作用域

标志	作用域	存储位置
-s user	全局（所有项目）	~/.claude.json
-s local	当前项目（个人）	.claude/settings.local.json（已加入 git 忽略）
-s project	当前项目（团队共享）	.claude/settings.json（由 git 跟踪）

打印/CI 模式下的 MCP

terminal(command="claude --bare -p 'Query database' --mcp-config mcp-servers.json --strict-mcp-config", timeout=60)

--strict-mcp-config 会忽略所有 MCP 服务，但 --mcp-config 中的服务除外。

在聊天中引用 MCP 资源：@github:issue://123

MCP 限制与调优

• 工具描述： 每个服务的工具描述和服务说明上限为 2KB
• 结果大小： 默认有上限；使用 maxResultSizeChars 注解，可允许大型输出最多包含 500K 个字符
• 输出令牌： export MAX_MCP_OUTPUT_TOKENS=50000 — 限制 MCP 服务的输出，防止上下文过载
• 传输方式： stdio（本地进程）、http（远程）、sse（服务器发送事件）

监控交互式会话

查看 TUI 状态

# Periodic capture to check if Claude is still working or waiting for input
terminal(command="tmux capture-pane -t dev -p -S -10")

留意以下指示标记：

• 底部的 ❯ = 等待你输入（Claude 已完成或正在提问）
• ● 行 = Claude 正在使用工具（读取、写入、运行命令）
• ⏵⏵ bypass permissions on = 状态栏显示权限模式
• ◐ medium · /effort = 状态栏中当前的工作强度等级
• ctrl+o to expand = 工具输出已截断（可通过交互方式展开）

上下文窗口健康状况

在交互模式下使用 /context，查看上下文用量的彩色网格。关键阈值：

• < 70% — 正常运行，精度完整
• 70-85% — 精度开始下降，请考虑使用 /compact
• > 85% — 幻觉风险显著上升，请使用 /compact 或 /clear

环境变量

变量	作用
ANTHROPIC_API_KEY	用于身份验证的 API 密钥（OAuth 的替代方案）
CLAUDE_CODE_EFFORT_LEVEL	默认推理力度：low、medium、high、max 或 auto
MAX_THINKING_TOKENS	限制思考令牌数（设为 0 可完全禁用思考）
MAX_MCP_OUTPUT_TOKENS	限制 MCP 服务的输出（默认值因情况而异；例如可设为 50000）
CLAUDE_CODE_NO_FLICKER=1	启用备用屏幕渲染，消除终端闪烁
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB	从子进程中移除凭据以增强安全性

成本与性能提示

1. 在打印模式下使用 --max-turns，防止陷入无限循环。大多数任务可从 5-10 开始。
2. 使用 --max-budget-usd 设置成本上限。注意：创建系统提示词缓存的最低费用约为 $0.05。
3. 简单任务使用 --effort low（更快、更省钱）。复杂推理任务使用 high 或 max。
4. 在 CI/脚本中使用 --bare，跳过插件/钩子发现带来的开销。
5. 使用 --allowedTools 限制为仅使用所需工具（例如，评审时仅使用 Read）。
6. 在交互会话中，若上下文变得过大，使用 /compact。
7. 如果只需分析已知内容，请通过管道传入输入，而不是让 Claude 读取文件。
8. 简单任务使用 --model haiku（更省钱），复杂的多步骤任务使用 --model opus。
9. 在打印模式下使用 --fallback-model haiku，以便在模型过载时平稳处理。
10. 不同任务使用新的会话 — 会话持续 5 小时；使用新上下文效率更高。
11. 在 CI 中使用 --no-session-persistence，避免在磁盘上累积保存的会话。

易踩的坑与注意事项

1. 交互模式需要 tmux — Claude Code 是完整的 TUI 应用。在 Hermes 终端中单独使用 pty=true 也能运行，但 tmux 提供了用于监控的 capture-pane 和用于输入的 send-keys，这对编排至关重要。
2. --dangerously-skip-permissions 警告对话框默认选择“No, exit” — 这是安全的选项；只有在隔离环境中主动选择绕过权限时，才按 Down 然后 Enter。打印模式（-p）会完全跳过该对话框。
3. --max-budget-usd 的最低值约为 $0.05 — 仅创建系统提示词缓存就需要这么多费用。设置更低会立即报错。
4. --max-turns 仅适用于打印模式 — 在交互会话中会被忽略。
5. Claude 可能会使用 python 而不是 python — 在没有 python 符号链接的系统上，Claude 的 bash 命令首次运行会失败，但它会自行纠正。
6. 恢复会话需要在同一目录下进行 — --continue 会查找当前工作目录中最近的会话。
7. --json-schema 需要足够多的 --max-turns — Claude 必须先读取文件，再生成结构化输出，这需要多个轮次。
8. 信任对话框每个目录只会出现一次 — 仅首次出现，之后会缓存。
9. 后台 tmux 会话会持续存在 — 完成后务必使用 tmux kill-session -t <name> 清理。
10. 斜杠命令（如 /commit）仅在交互模式下有效 — 在 -p 模式下，请改用自然语言描述任务。
11. --bare 会跳过 OAuth — 需要设置 ANTHROPIC_API_KEY 环境变量，或在设置中配置 apiKeyHelper。
12. 上下文退化确实存在 — 当上下文窗口使用量超过 70% 时，AI 输出质量会明显下降。使用 /context 监控，并主动使用 /compact。

Hermes Agent 使用规则

1. 单次任务优先使用打印模式（-p）——更简洁，无需处理对话框，并可获得结构化输出
2. 多轮交互任务使用 tmux——这是编排 TUI 唯一可靠的方式
3. 始终设置 workdir——让 Claude 专注于正确的项目目录
4. 在打印模式下设置 --max-turns——防止无限循环和成本失控
5. 监控 tmux 会话——使用 tmux capture-pane -t <session> -p -S -50 检查进度
6. 留意 ❯ 提示符——这表示 Claude 正在等待输入（已完成或正在提问）
7. 清理 tmux 会话——完成后将其关闭，以避免资源泄漏
8. 向用户报告结果——完成后，概述 Claude 执行的操作和所做的更改
9. 不要结束运行缓慢的会话——Claude 可能正在执行多步骤任务；请改为检查进度
10. 使用 --allowedTools——将功能限制在任务实际需要的范围内