braintrust-tracing 技能 | PlugMCP
跳到正文 Install The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add parcadei/Continuous-Claude-v3 --skill braintrust-tracing -a cursor -y Copy Download skill .claude/skills/braintrust-tracing/SKILL.md on GitHub Questions
How do I install braintrust-tracing? Download .claude/skills/braintrust-tracing/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does braintrust-tracing live? The publisher keeps it at https://github.com/parcadei/Continuous-Claude-v3.
Which agents can use braintrust-tracing? Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository. SKILL.md 简介 常见问题
Braintrust tracing for Claude Code - hook architecture, sub-agent correlation, debugging
name: braintrust-tracing
description: Braintrust tracing for Claude Code - hook architecture, sub-agent correlation, debugging
user-invocable: false
Braintrust Tracing for Claude Code
Comprehensive guide to tracing Claude Code sessions in Braintrust, including sub-agent correlation.
Architecture Overview
PARENT SESSION
+---------------------+
| SessionStart |
| (creates root) |
+----------+----------+
|
+----------v----------+
| UserPromptSubmit |
| (creates Turn) |
+----------+----------+
|
+--------------------+--------------------+
| | |
+---------v--------+ +--------v--------+ +--------v--------+
| PostToolUse | | PostToolUse | | PreToolUse |
| (Read span) | | (Edit span) | | (Task - inject) |
+------------------+ +-----------------+ +--------+--------+
|
+----------v----------+
| SUB-AGENT |
| SessionStart |
| (NEW root_span_id)|
+----------+----------+
|
+----------v----------+
| SubagentStop |
| (has session_id) |
+---------------------+
plugmcp 把任意工具接入任意智能体。面向非开发者的 MCP 服务器目录；网关承载流量，n8n 承载应用。
PlugMCP, 2026
Hook Event Flow Hook Trigger Creates Key Fields SessionStart Session begins Root span session_id, root_span_idUserPromptSubmit User sends prompt Turn span prompt, turn_numberPreToolUse Before tool runs (modifies Task prompts) tool_input.promptPostToolUse After tool runs Tool span tool_name, input, outputStop Turn completes LLM spans model, tokens, tool_callsSubagentStop Sub-agent finishes (no span) session_id of sub-agentSessionEnd Session ends (finalizes root) turn_count, tool_count
Trace Hierarchy Session (task span) - root_span_id = session_id
|
+-- Turn 1 (task span)
| |
| +-- claude-sonnet (llm span) - model call with tool_use
| +-- Read (tool span)
| +-- Edit (tool span)
| +-- claude-sonnet (llm span) - response after tools
|
+-- Turn 2 (task span)
| |
| +-- claude-sonnet (llm span)
| +-- Task (tool span) -----> [Sub-agent session - SEPARATE trace]
| +-- claude-sonnet (llm span)
|
+-- Turn 3 ...
Sub-Agent Tracing: What Works and What Doesn't
What Doesn't Work SessionStart doesn't receive the Task prompt.
We tried injecting trace context into Task prompts via PreToolUse:
# PreToolUse hook injects:
[BRAINTRUST_TRACE_CONTEXT]
{"root_span_id": "abc", "parent_span_id": "xyz", "project_id": "123"}
[/BRAINTRUST_TRACE_CONTEXT]
But SessionStart only receives session metadata, not the modified prompt. The injected context is lost.
What DOES Work Task spans in parent session contain everything:
agentId - identifier for the sub-agent runtotalTokens, totalToolUseCount - metricscontent - full agent response/summarytool_input.prompt - original task prompttool_input.subagent_type - agent type (e.g., "oracle") SubagentStop hook receives the sub-agent's session_id:
This equals the sub-agent's orphaned trace root_span_id
Allows correlation between parent Task span and child trace
The Correlation Pattern Current state: Sub-agents create orphaned traces (new root_span_id).
Query parent session's Task spans for agent metadata
Match agentId or timing with orphaned traces
Sub-agent's session_id = its trace's root_span_id
Future solution (not yet implemented):
SubagentStop fires -> writes session_id to temp file
PostToolUse (Task) -> reads temp file -> adds child_session_id to Task span metadata
This would link: Task.agentId + Task.child_session_id -> orphaned trace root_span_id
State Management
Per-Session State Files ~/.claude/state/braintrust_sessions/
{session_id}.json # Per-session state
Each session file contains:
{
"root_span_id": "abc-123",
"project_id": "proj-456",
"turn_count": 5,
"tool_count": 23,
"current_turn_span_id": "turn-789",
"current_turn_start": 1703456789,
"started": "2025-12-24T10:00:00.000Z",
"is_subagent": false
}
Global State ~/.claude/state/braintrust_global.json # Cached project_id
~/.claude/state/braintrust_hook.log # Debug log
Debugging Commands
Check if Tracing is Active # View hook logs in real-time
tail -f ~/.claude/state/braintrust_hook.log
# Check if session has state
cat ~/.claude/state/braintrust_sessions/*.json | jq -s '.'
# Verify environment
echo "TRACE_TO_BRAINTRUST=$TRACE_TO_BRAINTRUST"
echo "BRAINTRUST_API_KEY=${BRAINTRUST_API_KEY:+set}"
Query Braintrust Directly # List recent sessions
uv run python -m runtime.harness scripts/braintrust_analyze.py --sessions 5
# Analyze last session
uv run python -m runtime.harness scripts/braintrust_analyze.py --last-session
# Replay specific session
uv run python -m runtime.harness scripts/braintrust_analyze.py --replay <session-id>
# Find sub-agent traces (orphaned roots)
uv run python -m runtime.harness scripts/braintrust_analyze.py --agent-stats
Debug Hook Execution # Enable verbose logging
export BRAINTRUST_CC_DEBUG=true
# Test hooks manually
echo '{"session_id":"test-123","type":"resume"}' | \
bash "$CLAUDE_PROJECT_DIR/.claude/plugins/braintrust-tracing/hooks/session_start.sh"
# Test PreToolUse (Task injection)
echo '{"session_id":"test-123","tool_name":"Task","tool_input":{"prompt":"test"}}' | \
bash "$CLAUDE_PROJECT_DIR/.claude/plugins/braintrust-tracing/hooks/pre_tool_use.sh"
Troubleshooting Checklist
No traces appearing:
Check TRACE_TO_BRAINTRUST=true in .claude/settings.local.json
Verify API key: echo $BRAINTRUST_API_KEY
Check logs: tail -20 ~/.claude/state/braintrust_hook.log
Sub-agents not linking:
This is expected - sub-agents create orphaned traces
Use --agent-stats to find agent activity
Correlate via timing or agentId in parent Task span
Missing spans:
Check current_turn_span_id in session state
Ensure Stop hook runs (turn finalization)
Look for "Failed to create" errors in log
State corruption:
Remove session state: rm ~/.claude/state/braintrust_sessions/*.json
Clear global cache: rm ~/.claude/state/braintrust_global.json
Key Files File Purpose .claude/plugins/braintrust-tracing/hooks/common.shShared utilities, API, state management .claude/plugins/braintrust-tracing/hooks/session_start.shCreates root span, handles sub-agent context .claude/plugins/braintrust-tracing/hooks/user_prompt_submit.shCreates Turn spans per user message .claude/plugins/braintrust-tracing/hooks/pre_tool_use.shInjects trace context into Task prompts .claude/plugins/braintrust-tracing/hooks/post_tool_use.shCreates tool spans, captures agent/skill metadata .claude/plugins/braintrust-tracing/hooks/stop_hook.shCreates LLM spans, finalizes Turns .claude/plugins/braintrust-tracing/hooks/session_end.shFinalizes session, triggers learning extraction scripts/braintrust_analyze.pyQuery and analyze traced sessions ~/.claude/state/braintrust_sessions/Per-session state files ~/.claude/state/braintrust_hook.logDebug log
Environment Variables Variable Required Default Description TRACE_TO_BRAINTRUSTYes - Set to "true" to enable BRAINTRUST_API_KEYYes - API key for Braintrust BRAINTRUST_CC_PROJECTNo claude-codeProject name BRAINTRUST_CC_DEBUGNo falseVerbose logging BRAINTRUST_API_URLNo https://api.braintrust.devAPI endpoint
Session Learnings
What We Learned About Sub-Agent Tracing (Dec 2025) Attempted: Inject trace context via PreToolUse into Task prompts.
Result: Failed - SessionStart only receives session metadata, not the prompt.
Discovery: Task spans already contain rich sub-agent data:
metadata.agent_type - agent type from subagent_typemetadata.skill_name - skill from Skill tooltool_input - full prompt sent to agenttool_output - agent response Current correlation path:
Parent session Task span has agentId and timing
Sub-agent creates orphaned trace with root_span_id = session_id
SubagentStop provides the sub-agent's session_id
Manual correlation: match timing or use session_id link
Future work: Write child_session_id to Task span metadata from PostToolUse after SubagentStop.
What We Learned About Sub-Agent Correlation
The Problem
Sub-agents spawned via Task tool create orphaned Braintrust traces
Parent session has Task spans with agentId, sub-agent has separate session_id
No built-in link between them
What DOESN'T Work 1. Prompt injection via PreToolUse
SessionStart hook only receives session metadata (session_id, type, cwd), NOT the prompt. Injected trace context is never seen.
{
"session_id": "...",
"type": "start|resume|compact|clear",
"cwd": "...",
"env": {...}
}
No prompt field exists - context injection is impossible at SessionStart.
2. SubagentStop → PostToolUse file handoff
Race condition. These are independent async hooks with no timing guarantees:
SubagentStop fires when sub-agent session ends
PostToolUse (Task) fires when Task tool completes
No ordering guarantee between them
Writing to a correlation file creates a race
3. PreToolUse correlation files
SessionStart can't access the task_span_id because it has no context about which Task spawned it. PreToolUse modifies prompts but doesn't create a reliably accessible state file that SessionStart can find.
What DOES Work Post-hoc matching for dataset building:
Parent session Task spans contain:
agentId - identifier for the sub-agent runtotalTokens, totalToolUseCount - aggregated metricscontent - full agent response/summarytool_input.prompt - original task prompttool_input.subagent_type - agent type (e.g., "oracle")Start/end timestamps
Sub-agent sessions contain:
session_id (equals orphaned trace root_span_id)Start/end timestamps
All internal spans and tool calls
Export parent session traces (query parent root_span_id)
Export sub-agent traces (query all sessions created within parent's time window)
Match by:
Timing: Task span end ≈ sub-agent session end
Metadata: subagent_type from Task prompt
IDs: SubagentStop hook provides session_id (can be captured and logged)
Architecture Insight SessionStart input is intentionally minimal - it contains no prompt or tool context:
interface SessionStartInput {
session_id: string;
type: "start" | "resume" | "compact" | "clear";
cwd: string;
env: { [key: string]: string };
// NO: prompt, tool_context, task_span_id, parent_span_id
}
This design boundary prevents real-time correlation at hook time.
Recommendation For building agent run datasets with sub-agent correlation:
In-session logging: Capture SubagentStop session_id in logs or statePost-session export: Query Braintrust API for parent and sub-agent tracesOffline correlation: Match traces by timing and metadata in a scriptDon't try real-time linking: Hooks don't have necessary context # 1. Export parent session
braintrust_analyze.py --replay <parent-session-id> > parent_traces.json
# 2. Query for orphaned sub-agent traces (those created during parent's time window)
braintrust_analyze.py --agent-stats > all_agent_traces.json
# 3. Correlate in Python:
# - Parent Task spans -> agentId, timestamps, subagent_type
# - Orphaned traces -> root_span_id, timestamps
# - Match by timing and type
This approach is reliable, testable, and doesn't require hooks to maintain implicit state.
How do I install braintrust-tracing? Download .claude/skills/braintrust-tracing/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does braintrust-tracing live? The publisher keeps it at https://github.com/parcadei/Continuous-Claude-v3.
Which agents can use braintrust-tracing? Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.