tomevault-io Claude Code Agent
通过 Claude Code CLI 将任务委派给独立的 Claude Code 会话执行。
可把 claude -p 理解为 Claude Code Agent SDK 的 CLI 入口。旧文档有时把它叫做 headless mode，但行为和当前 -p 入口是同一条能力线。
前置条件
- 安装 Claude Code CLI：
npm install -g @anthropic-ai/claude-code - 确保已完成认证：
claude auth login - 可用
claude auth status --text快速确认当前登录状态 - 建议先切到目标项目目录再运行；自动化调用默认用
claude -p
调用方式
新建会话（默认）
claude -p "你的任务描述" --output-format json --permission-mode bypassPermissions --model opus --effort high
返回单个 JSON 对象，常用字段：
{
"type": "result",
"subtype": "success",
"is_error": false,
"result": "回复内容",
"session_id": "81a5f75b-...",
"total_cost_usd": 0.0944715,
"usage": { "input_tokens": 3, "output_tokens": 4 }
}
- 从
session_id提取会话 ID，用于后续多轮对话 - 从
result提取 Claude 的最终回复 - 用
is_error、subtype、usage、total_cost_usd判断是否出错并记录成本 - 如果同时传了
--json-schema，真正受 schema 约束的结果在structured_output字段里；result可能为空，不要把它当结构化结果读取
事件流输出（stream-json）
claude -p "你的任务描述" --output-format stream-json --verbose --model sonnet --effort medium
stream-json 必须配 --verbose，否则 CLI 会直接报错。当前常见事件：
{"type":"system","subtype":"init","session_id":"bb6067a9-..."}
{"type":"assistant","message":{"content":[{"type":"text","text":"OK"}]}}
{"type":"result","subtype":"success","result":"OK","session_id":"bb6067a9-..."}
- 自动化脚本通常以最后一条
type == "result"作为最终结果 type == "assistant"更适合拿完成后的整条回复，不是稳定的中途增量入口system/ hook / rate-limit 事件是正常噪音；不要把它们当最终答案system/init会带上 model、tools、plugins、plugin_errors 等启动元数据；脚本想校验插件是否真的加载成功时，这个事件最有用
如果你需要 token 级增量文本，追加 --include-partial-messages，并解析 type == "stream_event" 且 event.delta.type == "text_delta" 的事件。
继续指定会话
claude -p "后续提问" --output-format json --model sonnet --effort medium --resume "session_id"
继续最近会话（快捷方式）
claude -p "后续提问" --output-format json --model sonnet --effort medium --continue
--continue自动续接当前目录最近一次会话- 已经保存了明确
session_id，或需要更稳的脚本行为时，优先用--resume
管道输入 / stdin
cat logs.txt | claude -p "Explain the failure in these logs" --output-format json --model sonnet --effort low
- 适合把日志、长文本、生成中的中间产物直接喂给子 Claude Code
- 如果上层工具本身输出
stream-json，再考虑配--input-format stream-json
⚠️ --no-session-persistence：会话不可恢复
加 --no-session-persistence 后，本次会话不会写入磁盘，因此事后无法被 --resume 或 --continue 恢复。仅在以下场景使用：
- 一次性快速问答，确定不会追问
- CI / 脚本中的临时调用，避免污染会话列表
- 敏感任务，不希望在本地留下记录
只要后续可能需要追问，就不要加 --no-session-persistence。
claude CLI 参数
输出与结果
| Flag | 说明 |
|---|---|
-p, --print |
非交互模式；json / stream-json 输出都依赖它 |
--output-format FORMAT |
text（默认）/ json / stream-json |
--verbose |
打开详细模式；stream-json 必需 |
--include-partial-messages |
在 stream-json 中输出部分消息块 |
--include-hook-events |
在 stream-json 中包含完整 hook 生命周期事件 |
--json-schema SCHEMA |
用 JSON Schema 约束结构化输出 |
会话管理
| Flag | 说明 |
|---|---|
-r, --resume SESSION_OR_NAME |
恢复指定会话 ID 或会话名 |
-c, --continue |
恢复当前目录最近会话 |
--fork-session |
在 resume / continue 时分叉出新会话 |
--from-pr NUMBER |
恢复关联到指定 PR 的会话 |
--session-id UUID |
显式指定会话 ID |
-n, --name NAME |
为会话设置显示名称；后续可 --resume <name> |
--no-session-persistence |
不持久化会话 |
输入与流式集成
| Flag | 说明 |
|---|---|
--input-format FORMAT |
text（默认）/ stream-json；给上游程序化输入用 |
--replay-user-messages |
在 stream-json 输入模式下，把用户消息重新回放到 stdout |
--permission-prompt-tool TOOL |
在非交互模式下，把权限确认委托给指定 MCP 工具 |
权限与工具边界
| Flag | 说明 |
|---|---|
--permission-mode MODE |
default / acceptEdits / plan / auto / dontAsk / bypassPermissions |
--allowedTools TOOLS |
白名单特定工具，如 "Read,Grep,Glob,Bash(git *)" |
--disallowedTools TOOLS |
禁用特定工具 |
--tools TOOLS |
指定可用工具集；"" 禁用全部，"default" 使用全部 |
--dangerously-skip-permissions |
直接跳过所有权限检查，风险极高 |
--allow-dangerously-skip-permissions |
允许会话里把“跳过权限检查”作为可选模式打开 |
acceptEdits 适合“允许写文件，但不想把所有 Bash / 网络能力都一把放开”的脚本化修复。dontAsk 更适合锁得很死的 CI：任何不在 allowlist 或只读命令集里的动作都会直接失败，而不是进入交互确认。
模型与上下文
| Flag | 说明 |
|---|---|
--model MODEL |
指定模型，建议显式传递 |
--effort LEVEL |
思考力度：low / medium / high / xhigh / max |
--max-turns N |
限制 agentic turn 数；给自动化子会话兜边界 |
--max-budget-usd AMOUNT |
最大花费限制 |
--fallback-model MODEL |
--print 模式下过载时的自动降级模型 |
--system-prompt PROMPT |
替换默认系统提示词 |
--append-system-prompt PROMPT |
追加系统提示词 |
--system-prompt-file FILE |
从文件加载系统提示词 |
--append-system-prompt-file FILE |
从文件追加系统提示词 |
--exclude-dynamic-system-prompt-sections |
把 cwd / 环境 / git 状态等动态信息移出系统提示词，提升跨机器缓存复用 |
--add-dir DIR |
添加额外可访问目录 |
--mcp-config CONFIG |
加载 MCP 配置（文件或 JSON 字符串） |
--settings FILE_OR_JSON |
加载额外 settings |
运行环境
| Flag | 说明 |
|---|---|
-w, --worktree [NAME] |
为该任务创建隔离 worktree |
--tmux |
配合 --worktree 创建 tmux / iTerm pane 会话 |
--bare |
scripted / SDK 推荐的 clean-room 模式：跳过 hooks、skills、plugins、MCP、auto memory 和 CLAUDE.md 自动发现 |
--disable-slash-commands |
禁用所有 skills / slash commands |
--agent AGENT |
指定当前会话使用的 agent |
--agents JSON |
注入自定义 agents 定义 |
--plugin-dir PATH |
为当前会话额外加载 plugin 目录 |
--chrome / --no-chrome |
打开或关闭 Claude in Chrome 集成 |
--bare 下只会应用你显式传入的 flags；它不会读取本地 OAuth / keychain。需要 Anthropic 鉴权时，通常改用 ANTHROPIC_API_KEY 或在 --settings 里提供 apiKeyHelper。
多轮对话
- 首次
claude -p ... --output-format json获取session_id - 后续追问用
claude -p ... --resume "session_id"，或在同目录用--continue - 自动跟踪
session_id，用户无需手动理解完整协议 - 不同任务各自新建会话；多个
session_id互不干扰
模型与 effort 选择
根据任务复杂度显式指定 --model 和 --effort：
| 任务复杂度 | model | effort | 适用场景 |
|---|---|---|---|
| 高 | opus |
high |
架构设计、复杂重构、多文件编码 |
| 中 | sonnet |
medium |
单文件功能实现、bug 修复、一般分析 |
| 低 | sonnet |
low |
简单问答、代码解释、快速续问 |
推荐参数组合
| 场景 | model | effort | permission-mode | 其他 flags |
|---|---|---|---|---|
| 复杂编码 | opus |
high |
bypassPermissions |
--output-format json |
| 一般编码 | sonnet |
medium |
bypassPermissions |
--output-format json |
| 脚本化小修复 | sonnet |
medium |
acceptEdits |
--bare --allowedTools "Bash,Read,Edit" |
| 代码审查 | sonnet |
medium |
plan |
--allowedTools "Read,Grep,Glob,Bash(git *)" |
| 锁死的 CI 检查 | sonnet |
medium |
dontAsk |
--bare --allowedTools "Read,Grep,Glob" |
| 快速问答 | sonnet |
low |
default |
--no-session-persistence（⚠️ 不可恢复） |
| 工具链消费事件流 | sonnet |
medium |
视任务而定 | --output-format stream-json --verbose |
| 有边界的自动化子会话 | sonnet |
medium |
视任务而定 | --max-turns 3 --max-budget-usd 1 |
| 干净子进程 / prompt 实验 | sonnet |
medium |
default 或 plan |
--bare |
| 结构化输出 | sonnet |
medium |
default |
--json-schema schema.json |
| 隔离执行 | opus |
high |
bypassPermissions |
--worktree feature-x |
使用规则
- 自动化调用默认用
-p+--output-format json：拿稳定的单对象结果；只有确实需要事件流时再切stream-json stream-json一律配--verbose：这是 CLI 的硬约束，不是建议- 始终显式传
--model和--effort：避免默认值漂移 - 始终在目标项目目录运行：先
cd /path/to/project，不要让 Claude 在错误仓库执行 - 编码任务用
bypassPermissions，审查任务用plan+ 工具白名单：plan不是硬沙箱，仍要配--allowedTools - 保持对话连续：只要后续可能追问，就不要加
--no-session-persistence --continue适合“继续刚才那个任务”；需要可追踪脚本行为、跨目录稳定性或明确会话绑定时，用--resume- 需要隔离修改时优先
--worktree：比手工切目录更稳，也更适合子 agent 独立执行 - 向用户报告结果时优先取
result字段：必要时再补session_id、成本和 token 使用 - 如果只允许读，不要只依赖提示词：同时加
plan、工具白名单或--tools限制，避免子进程意外写文件 - 需要更可控的自动化边界时，加
--max-turns：避免子会话在模糊任务里跑得过深 - scripted / SDK 调用默认优先
--bare：这样不会继承本地CLAUDE.md、skills、plugins、MCP 和 auto memory，结果也更可复现 -p模式里不要依赖/commit之类交互式 slash commands：直接用自然语言描述任务；必要时显式给--append-system-prompt、--allowedTools或--json-schema
Prompt References
按任务类型按需加载对应 reference，不要把所有默认 prompt 一次性塞进主上下文：
- 编码 / 诊断 / 规划 / 窄修复：读 references/task-prompt-recipes.md
- 代码审查 / 挑战式审查 / 测试缺口检查：读 references/review-prompt-recipes.md
- 委派 handoff / 独立 worker / 续接同一 session：读 references/delegation-prompt-recipes.md
这些 reference 提供的是可直接复用或轻改的默认 prompt 模板；优先复制最接近的模板，再删掉不需要的块。
示例
编码任务
cd /path/to/project && claude -p \
"Implement a REST API for TODO items with CRUD endpoints. Use Express.js." \
--output-format json \
--permission-mode bypassPermissions \
--model opus \
--effort high
返回的 result 是自然语言总结，session_id 用于后续追问。
继续最近会话
cd /path/to/project && claude -p \
"Continue from the current state. Add unit tests for the new endpoints and report only the final outcome." \
--output-format json \
--model sonnet \
--effort medium \
--continue
适合“刚才那个任务继续做”，不想手动保存 session_id 的场景。
事件流输出给上层工具
cd /path/to/project && claude -p \
"Review the current diff and stream back progress plus a final verdict." \
--output-format stream-json \
--verbose \
--permission-mode plan \
--allowedTools "Read,Grep,Glob,Bash(git *)" \
--model sonnet \
--effort medium
适合上层 agent 或脚本：中间读 assistant / system 事件，最后读 result。
流式抽取纯文本增量
claude -p "Write a short changelog entry" \
--output-format stream-json \
--verbose \
--include-partial-messages | \
jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
适合你自己的上层 UI 或脚本只想吃连续文本 token，不想自己处理整条事件流。
管道输入日志或长文本
cat logs.txt | claude -p \
"Explain the failure in these logs. Return root cause, evidence, and the smallest safe next step." \
--output-format json \
--model sonnet \
--effort low
适合把父进程已经拿到的大段上下文直接流给子 Claude Code，而不是再落成临时 prompt。
结构化输出给另一个工具
claude -p \
"Extract the main exported function names from src/auth.ts." \
--output-format json \
--json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' | \
jq '.structured_output'
适合上层 agent、CI 或脚本只消费结构化字段；注意真正受 schema 约束的结果在 structured_output，不是 result。
代码审查
cd /path/to/project && claude -p \
"Review git diff HEAD~1. Focus on correctness, regression risk, and missing tests. Findings first." \
--output-format json \
--permission-mode plan \
--allowedTools "Read,Grep,Glob,Bash(git *)" \
--model sonnet \
--effort medium
隔离 worktree 执行
cd /path/to/project && claude -p \
"Implement the fix in an isolated worktree, run the most relevant tests, and summarize the final result." \
--output-format json \
--permission-mode bypassPermissions \
--model opus \
--effort high \
--worktree fix-login-timeout
适合让子 Claude Code 独立完成一段实现，而不直接污染当前工作树。
干净子进程 / prompt 实验
先决条件：这个示例假设你已经通过 ANTHROPIC_API_KEY 或 --settings 里的 apiKeyHelper 提供鉴权。--bare 不会读取本地 OAuth / keychain，所以直接依赖 claude auth login 的环境会报 Not logged in。
cd /path/to/project && ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" claude -p \
"Review src/auth.ts for contract drift only." \
--output-format json \
--permission-mode plan \
--allowedTools "Read,Grep,Glob" \
--model sonnet \
--effort medium \
--bare \
--max-turns 3
适合做更可复现的 scripted 调用，不希望本地 CLAUDE.md、插件、skills 或 auto memory 影响输出。
Source: Ben2pc/g-claude-code-plugins — distributed by TomeVault.