trace-claude-code

Trace Claude Code sessions, turns, and tool calls to Braintrust.

20|11|Updated Dec 20, 2025
One-click install
npx skills add https://github.com/braintrustdata/braintrust-claude-plugin --skill trace-claude-code
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: trace-claude-code
Source: https://github.com/braintrustdata/braintrust-claude-plugin/tree/main/skills/trace-claude-code
Command: npx skills add https://github.com/braintrustdata/braintrust-claude-plugin --skill trace-claude-code

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires jq, curl, and includes hooks (resource) components.

What problem does it solve?

This Skill automatically captures every Claude Code conversation, tool call, and interaction, giving you complete visibility into your AI coding workflow.

Core Features & Use Cases

  • Hierarchical Tracing: See sessions, turns, and tool calls in a structured view.
  • Zero Configuration: One-click setup automatically configures all necessary hooks.
  • Use Case: Imagine debugging a complex code refactoring session. This Skill automatically traces every file read, edit, and terminal command, so you can review exactly what happened.

Quick Start

Run the setup script to automatically configure tracing for your current project.

Frequently Asked Questions about trace-claude-code

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I capture Claude Code sessions for debugging and observability?

Tracing automatically captures every Claude Code conversation, tool call, and interaction by emitting structured JSON spans through lifecycle hooks. This provides complete end-to-end visibility into your coding workflow for debugging and auditing without manual instrumentation.

What do I need to set up tracing for Claude Code?

You need a Braintrust API key and project configuration. The Skill's zero-configuration setup script automatically configures all necessary hooks, so no manual hook registration is required.

Can I trace hierarchical Claude Code sessions with file reads and tool calls?

Yes. Tracing captures sessions, turns, and tool calls in a hierarchical structure, so you can review exactly what happened—including every file read, edit, and terminal command—in a single view.

Does tracing work across multiple Claude Code sessions?

Yes. The Skill applies across all Claude Code sessions, capturing and emitting traces to Braintrust for each session, enabling persistent observability across your entire development workflow.

What are the dependencies for setting up session tracing?

You need jq for JSON processing and curl for sending traces to Braintrust. Both are lightweight CLI tools required to emit structured spans via the four lifecycle hooks.

Can I audit past Claude Code interactions after tracing is enabled?

Tracing captures sessions, turns, and tool calls as hierarchical traces stored in Braintrust, enabling you to review and audit past interactions end-to-end for compliance and debugging.