名称: trace-claude-code 描述: | 自动将Claude Code对话跟踪到Braintrust进行可观察性。捕获会话、对话轮次和工具调用作为层次化跟踪。版本: 1.1.0

跟踪Claude代码到Braintrust

自动将Claude Code对话发送到Braintrust进行跟踪和可观察性。通过层次化跟踪展示会话、轮次和每个工具调用，获得完整的AI编码会话可见性。

您将获得

Claude Code会话（根跟踪）
├── 轮次1: "添加错误处理"
│   ├── 读取: src/app.ts
│   ├── 编辑: src/app.ts
│   └── 响应: "我已添加try-catch..."
├── 轮次2: "现在运行测试"
│   ├── 终端: npm test
│   └── 响应: "所有测试通过..."
└── 轮次3: "很好，提交这个"
    ├── 终端: git add .
    ├── 终端: git commit -m "..."
    └── 响应: "更改已提交..."

工作原理

四个钩子捕获完整工作流：

钩子	捕获内容
SessionStart	在您启动Claude Code时创建根跟踪
PostToolUse	捕获每个工具调用（文件读取、编辑、终端命令）
Stop	捕获对话轮次（您的消息 + Claude的响应）
SessionEnd	在您退出时记录会话摘要

快速设置

在您想要跟踪的任何项目目录中运行设置脚本：

bash /path/to/skills/trace-claude-code/setup.sh

脚本会提示您输入API密钥和项目名称，然后自动配置所有钩子。

手动设置

先决条件

已安装Claude Code CLI
Braintrust API密钥
jq命令行工具（在macOS上使用brew install jq安装）

配置

在您的项目目录中创建.claude/settings.local.json：

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/hooks/session_start.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/hooks/post_tool_use.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/hooks/stop_hook.sh"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/hooks/session_end.sh"
          }
        ]
      }
    ]
  },
  "env": {
    "TRACE_TO_BRAINTRUST": "true",
    "BRAINTRUST_API_KEY": "sk-...",
    "BRAINTRUST_CC_PROJECT": "my-project"
  }
}

将/path/to/hooks/替换为此技能钩子目录的实际路径。

环境变量

变量	必需	描述
`TRACE_TO_BRAINTRUST`	是	设置为`"true"`以启用跟踪
`BRAINTRUST_API_KEY`	是	您的Braintrust API密钥
`BRAINTRUST_CC_PROJECT`	否	项目名称（默认：`claude-code`）
`BRAINTRUST_CC_DEBUG`	否	设置为`"true"`以获取详细日志

查看跟踪

启用跟踪后运行Claude Code：

访问braintrust.dev
导航到您的项目（例如claude-code）
点击日志以查看所有跟踪会话

每个跟踪显示：

会话根：整个Claude Code会话
轮次：每个对话交换（用户输入 → 助手响应）
工具调用：单个操作（文件读取、编辑、终端命令）

跟踪结构

跟踪是层次化的：

会话（根跨度）
- span_attributes.type: "task"
- metadata.session_id: 唯一会话标识符
- metadata.workspace: 项目目录
轮次（会话的子级）
- span_attributes.type: "llm"
- input: 用户消息
- output: 助手响应
- metadata.turn_number: 顺序轮次编号
工具调用（轮次或会话的子级）
- span_attributes.type: "tool"
- input: 工具输入（文件路径、命令等）
- output: 工具结果
- metadata.tool_name: 使用的工具名称

故障排除

无跟踪出现

检查钩子是否运行：

tail -f ~/.claude/state/braintrust_hook.log

验证环境变量在.claude/settings.local.json中：
- TRACE_TO_BRAINTRUST必须为"true"
- BRAINTRUST_API_KEY必须有效

启用调试模式：

{
  "env": {
    "BRAINTRUST_CC_DEBUG": "true"
  }
}

权限错误

使钩子脚本可执行：

chmod +x /path/to/hooks/*.sh

缺少jq命令

安装jq：

macOS: brew install jq
Ubuntu/Debian: sudo apt-get install jq

状态问题

重置跟踪状态：

rm ~/.claude/state/braintrust_state.json

钩子日志

查看详细的钩子执行日志：

# 实时跟踪日志
tail -f ~/.claude/state/braintrust_hook.log

# 查看最后50行
tail -50 ~/.claude/state/braintrust_hook.log

# 清除日志
> ~/.claude/state/braintrust_hook.log

文件结构

hooks/
├── common.sh          # 共享工具（日志记录、API、状态）
├── session_start.sh   # 创建根跟踪跨度
├── post_tool_use.sh   # 捕获工具调用
├── stop_hook.sh       # 捕获对话轮次
└── session_end.sh     # 完成跟踪

替代方案：SDK集成

对于使用Claude Agent SDK的程序化使用，使用原生的Braintrust集成：

import { initLogger, wrapClaudeAgentSDK } from "braintrust";
import * as claudeSDK from "@anthropic-ai/claude-agent-sdk";

initLogger({
  projectName: "my-project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const { query, tool } = wrapClaudeAgentSDK(claudeSDK);

详见Braintrust Claude Agent SDK文档。

名称: trace-claude-code 描述: | 自动将Claude Code对话跟踪到Braintrust进行可观察性。 捕获会话、对话轮次和工具调用作为层次化跟踪。 版本: 1.1.0