Skip to content

README.md

Latest commit

 

History

History
55 lines (42 loc) · 2.27 KB

README.md

File metadata and controls

55 lines (42 loc) · 2.27 KB
Raw

Braintrust Claude Code tracing plugin

This plugin synchronously forwards Claude Code lifecycle payloads to:

bt trace hook --source claude-code

Use bt trace enable claude --project <project> to install and configure it. Hooks use Claude Code's exec form: command: "bt" and args: ["trace", "hook", "--source", "claude-code"]. Claude Code directly executes bt without a hook shell or intermediate forwarding script. On Windows, bt must resolve to the native bt.exe, not a .cmd or .bat shim. The plugin is credential-free; the bt CLI and shared daemon own authentication, event journaling, trace construction, and delivery.

Supported surfaces

This plugin supports Claude Code CLI and Claude Code mode in the desktop app. It does not support the Cowork tab. Cowork executes hooks in a separate VM that does not inherit the host's bt binary, saved Braintrust route, or credentials, so installing this plugin there does not enable tracing.

To add fields to each root trace span, pass a JSON object (as --additional-metadata or BRAINTRUST_ADDITIONAL_METADATA) to bt trace enable claude for a persistent configuration, or to bt trace run claude for one invocation. The hook itself never reads that environment variable — only bt trace enable, bt trace run, and bt trace import do.

Windows console windows

Exec-form hooks remove the shell launch, but Claude Code still controls how it starts bt.exe. The plugin cannot set Windows process-creation flags for that initial launch. If flashing persists, capture the process parent chain and visible window events to distinguish Claude's hook launch from children of the tracing daemon.

The shared daemon suppresses console creation for its Git and host-metadata commands. That change ships through an updated bt binary, not a plugin-only update. End-to-end window suppression still requires verification on Windows.

Tags and diagnostics

Use repeatable --tag flags for filterable root-span tags. Inspect the effective configuration with doctor and delivery state with status:

bt trace enable claude --tag coding-agent --tag development
bt trace doctor claude
bt trace status

See the distribution guide for installation, one-off runs, transcript import, updates, and disablement.