Automatically trace Claude Code conversations to Braintrust for observability. Captures sessions, conversation turns, and tool calls as hierarchical traces.
74%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./.claude/plugins/braintrust-tracing/skills/trace-claude-code/SKILL.mdAutomatically send Claude Code conversations to Braintrust for tracing and observability. Get full visibility into your AI coding sessions with hierarchical traces showing sessions, turns, and every tool call.
Claude Code Session (root trace)
├── Turn 1: "Add error handling"
│ ├── Read: src/app.ts
│ ├── Edit: src/app.ts
│ └── Response: "I've added try-catch..."
├── Turn 2: "Now run the tests"
│ ├── Terminal: npm test
│ └── Response: "All tests pass..."
└── Turn 3: "Great, commit this"
├── Terminal: git add .
├── Terminal: git commit -m "..."
└── Response: "Changes committed..."Four hooks capture the complete workflow:
| Hook | What it captures |
|---|---|
| SessionStart | Creates root trace when you start Claude Code |
| PostToolUse | Captures every tool call (file reads, edits, terminal commands) |
| Stop | Captures conversation turns (your message + Claude's response) |
| SessionEnd | Logs session summary when you exit |
Run the setup script in any project directory where you want tracing:
bash /path/to/skills/trace-claude-code/setup.shThe script prompts for your API key and project name, then configures all hooks automatically.
jq command-line tool (brew install jq on macOS)Create .claude/settings.local.json in your project directory:
{
"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"
}
}Replace /path/to/hooks/ with the actual path to this skill's hooks directory.
| Variable | Required | Description |
|---|---|---|
TRACE_TO_BRAINTRUST | Yes | Set to "true" to enable tracing |
BRAINTRUST_API_KEY | Yes | Your Braintrust API key |
BRAINTRUST_CC_PROJECT | No | Project name (default: claude-code) |
BRAINTRUST_CC_DEBUG | No | Set to "true" for verbose logging |
After running Claude Code with tracing enabled:
claude-code)Each trace shows:
Traces are hierarchical:
Session (root span)
span_attributes.type: "task"metadata.session_id: Unique session identifiermetadata.workspace: Project directoryTurn (child of session)
span_attributes.type: "llm"input: User messageoutput: Assistant responsemetadata.turn_number: Sequential turn numberTool call (child of turn or session)
span_attributes.type: "tool"input: Tool input (file path, command, etc.)output: Tool resultmetadata.tool_name: Name of the tool usedCheck hooks are running:
tail -f ~/.claude/state/braintrust_hook.logVerify environment variables in .claude/settings.local.json:
TRACE_TO_BRAINTRUST must be "true"BRAINTRUST_API_KEY must be validEnable debug mode:
{
"env": {
"BRAINTRUST_CC_DEBUG": "true"
}
}Make hook scripts executable:
chmod +x /path/to/hooks/*.shInstall jq:
brew install jqsudo apt-get install jqReset the tracing state:
rm ~/.claude/state/braintrust_state.jsonView detailed hook execution logs:
# Follow logs in real-time
tail -f ~/.claude/state/braintrust_hook.log
# View last 50 lines
tail -50 ~/.claude/state/braintrust_hook.log
# Clear logs
> ~/.claude/state/braintrust_hook.loghooks/
├── common.sh # Shared utilities (logging, API, state)
├── session_start.sh # Creates root trace span
├── post_tool_use.sh # Captures tool calls
├── stop_hook.sh # Captures conversation turns
└── session_end.sh # Finalizes traceFor programmatic use with the Claude Agent SDK, use the native Braintrust integration:
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);See Braintrust Claude Agent SDK docs for details.
parcadei/Continuous-Claude-v3
d07ff4b
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.