trace-claude-code

Tracing Claude Code conversations to Braintrust captures sessions, turns, and tool calls as hierarchical traces for observability. Run the setup script, set environment variables (TRACE_TO_BRAINTRUST, BRAINTRUST_API_KEY, BRAINTRUST_CC_PROJECT), and traces automatically flow to Braintrust for debugging and auditing.

Hierarchical traces capture sessions, turns, reads, edits, terminal interactions, and all tool calls with metadata. Cross-session correlation links handoffs to traces, enabling complete visibility into how decisions and tool uses occurred during long debugging sessions.

Yes. Prerequisites include a Braintrust account with API key, project name, and environment variables configured. Optional hooks (SessionStart, PostToolUse, Stop, SessionEnd) enable manual configuration for granular control over what gets traced.

Yes. Set the optional BRAINTRUST_CC_DEBUG environment variable to enable verbose logging, which outputs detailed trace information for troubleshooting and understanding trace capture behavior.

Review the hierarchical traces in Braintrust after your session ends. Traces show the full sequence of turns, tool calls, and decisions, letting you identify where issues occurred and audit the complete interaction history.

Automatic tracing works after setup with environment variables. Manual configuration uses four hooks (SessionStart, PostToolUse, Stop, SessionEnd) for fine-grained control over which events and data get captured in traces.