This repository is generated. It is built from braintrustdata/braintrust-coding-agent-plugins. Don't edit files here — make changes and file issues in that repository, and they will be rebuilt into this one.
A Claude Code plugin marketplace for tracing Claude Code sessions to Braintrust.
- A Braintrust account
- Claude Code with exec-form command hook support
- The Braintrust CLI
on Claude Code's
PATH. On Windows,btmust resolve to the nativebt.exe, not a.cmdor.batshim.
This marketplace plugin supports Claude Code CLI and Claude Code mode in the
desktop app. It does not currently support the Cowork tab, which runs tools and
hooks inside a separate VM without the host's bt installation, Braintrust
configuration, or environment variables.
In Cowork, use the Braintrust connector provided through Claude for MCP access. Automatic Cowork session tracing is not currently supported.
Authenticate and install the published tracing plugin:
bt login
bt trace enable claude --project my-coding-agentSetup adds the marketplace and installs or enables trace-claude-code.
The plugin forwards lifecycle events locally; bt owns authentication,
trace construction, and delivery.
Use --profile or --org when needed. Setup stores only non-secret routing
settings under ~/.claude/braintrust.json. Restart Claude Code after setup.
Every registered lifecycle event is forwarded synchronously to
bt trace hook --source claude-code, preserving per-session ordering. Hook
failures never fail a Claude Code turn.
Hooks use command: "bt" with a separate args array, bypassing Claude Code's
hook shell. This capture path has been verified with Claude Code 2.1.284.
This marketplace does not install or configure the Braintrust MCP server. Use your agent's native connector or MCP configuration when you want MCP access.
Tracing forwards Claude Code's native hook payloads and reads the session transcript to construct traces. This can include user prompts, tool inputs and outputs, model requests and responses, and session metadata. Each turn records the effective Claude permission mode. Root-span metadata includes, when Claude provides it, the complete client system prompt.
System prompts and the other captured content can contain confidential instructions, file contents, or secrets. The plugin does not redact these values locally. Configure the applicable Braintrust content-redaction controls before enabling tracing, and do not trace content that must not be sent to Braintrust. Redaction cannot remove data that has already been delivered.
For a persistent route, pass a JSON object to bt trace enable claude --additional-metadata '<JSON>' to tag the root span of every Claude Code
session. Standard session metadata takes precedence if keys conflict.
For one invocation without changing the persistent configuration, use
bt trace run --additional-metadata '{"ci":true,"run_id":"abc-123"}' claude,
or set BRAINTRUST_ADDITIONAL_METADATA before that command (bt trace run
still accepts it; a launched claude session's live hooks do not).
Use repeatable --tag options to apply filterable tags to every root span in a
route. Tags can be persisted with setup, supplied to one invocation, or added
while importing a transcript:
bt trace enable claude --tag ci --tag release-validation
bt trace run claude --tag ci -- "review this change"
bt trace import claude session-id --tag historical-importFor automation, set BRAINTRUST_TAGS to a comma-separated list before
invoking setup, a run, or an import:
BRAINTRUST_TAGS=ci,release-validation bt trace run claude -- "review this change"bt trace run --project my-coding-agent claude -- -p "summarize this repository"
bt trace import claude SESSION_ID
bt trace import claude SESSION_ID --attachrun leaves your saved settings alone. import reads a saved transcript;
--attach follows it until Ctrl-C. Imports include only what the agent recorded.
bt trace doctor claude
bt trace status
bt trace update claude
bt trace disable claudeSee the tracing plugin guide for the capture architecture and supported surfaces.