Braintrust coding-agent plugins
Trace coding-agent sessions in Braintrust.
This monorepo contains the plugins and the shared Rust tracing daemon embedded
in the Braintrust CLI (bt). Plugins forward native events locally; the daemon
builds traces, journals events for recovery, and delivers spans to Braintrust.
This repository also packages the Braintrust
plugin for submission to
the official ChatGPT and Codex plugin directory. It connects to Braintrust's
hosted MCP server through OAuth and requires no bt installation. Installing it
does not enable session tracing.
Get started
Install your coding agent and the
Braintrust CLI,
then authenticate and enable tracing. For example:
bt login
bt trace enable claude --project my-coding-agent
Replace claude with your agent's CLI name below. Restart the agent after
setup and follow any plugin or hook trust prompts.
Supported agents
All six support bt trace enable, update, disable, and doctor.
Use run to trace one invocation, import to trace a saved session, or
import --attach to follow an active transcript:
bt trace run --project my-coding-agent claude -- -p "summarize this repository"
bt trace import claude SESSION_ID
bt trace import claude SESSION_ID --attach
bt trace run --project my-coding-agent cursor
bt trace import cursor SESSION_ID --attach
See the agent guides for limitations.
Manage tracing
bt trace doctor claude
bt trace status
bt trace update claude
bt trace disable claude
doctor shows which configuration is in use and whether the running tracing
daemon can authenticate it. status reports trace delivery.
update keeps your settings; disable removes the plugin and its settings.
For command hooks, bt trace hook exits nonzero when it cannot capture an
event. Exit 0 means the daemon accepted the event into its journal; delivery
can still fail later. Use bt trace status --session-id <ID> or doctor to
inspect those later failures. See hook exit status
for the full contract.
Development
src/plugins/<agent>/content/ Plugin source copied into distribution builds
src/runtime/js-daemon-client/ Shared JavaScript event-forwarding client
src/skills/ Shared skills included in plugin builds
bt-daemon/ Rust daemon, translators, and integration tests
scripts/ Shared build and publishing tools
.github/workflows/ CI and release automation
Use Bash and Python 3 for plugin scripts, Node.js 24 and pnpm 11.21.0 for the
JavaScript packages, and stable Rust for the daemon. Run from the monorepo root:
make build # Build all plugins into dist/<agent>
make build-codex # Build one plugin
make codex-submission # Validate and build the MCP-only OpenAI ZIP
make test-codex-packaging # Test Codex packaging and release contracts
make test-codex-mcp-loading # Check installed MCP loading with a local Codex CLI
make test # Build and validate plugin packages and forwarders
cargo test --manifest-path bt-daemon/Cargo.toml --all-features --locked
Real-agent tests require installed agents and are run separately; see the
test harness guide. See the
daemon README for architecture and local debugging.
Releases and contributions
Edit plugin sources here. The per-agent GitHub distribution repositories and
npm packages are generated artifacts. See AGENTS.md for the release
PR and approval workflow, sandbox publishing, and npm release workflows.
