This repo is the single source of truth for Braintrust's coding-agent plugins. Each plugin is developed here, built, and deployed to a per-agent distribution repository that its marketplace installs from.

src/plugins/<agent>/         one directory per agent
  content/                   the deployable plugin tree, verbatim
  build.sh <dir>             assemble the deployable tree into <dir>
  validate.sh <dir>          validate manifests and required files
  publish.sh                 deploy a built tree to a distribution repo
scripts/publish.sh           dispatch PUBLISH_TARGETS to each plugin
bt-daemon/                   shared Rust tracing crate embedded by bt
Makefile                     build, test, and publish entry points
.github/workflows/           CI and release automation

Everything an agent installs lives under src/plugins/<agent>/content/. Plugin hooks are thin fail-open shell launchers that invoke bt trace hook; they do not contain or compile a second tracing runtime.

For complete integrations, use $add-coding-agent-integration to delegate the tracing audit, translator, capture, setup, managed run, import/attach, testing, and shipping work to the corresponding repo-local skills. Use a component skill directly for focused work. Every integration uses one source identity and daemon translator; hooks and plugins remain thin, fail-open, credential-free forwarders.

Follow the Braintrust instrumentation specification for trace hierarchy, message/tool-call formats, metadata allowlists, and token metrics. When native hooks cannot expose required per-call data, document the limitation and preserve known parent totals rather than inventing attribution.

Install the pinned tools with mise. mise install reads .tool-versions and mise.toml, then runs make install-deps:

mise install
make build
make build-codex
make test
cargo test --manifest-path bt-daemon/Cargo.toml --all-features

Background subprocesses must use bt-daemon/src/subprocess.rs (Rust) or src/runtime/js-daemon-client/src/background-process.ts (JavaScript), not raw process APIs. These helpers prevent Windows console flashes. Foreground commands and daemon detachment have explicit exceptions; do not reuse them for background work. Clippy and Oxlint enforce use of these helpers in CI.

User-facing environment variables must use the BRAINTRUST_ prefix (for example BRAINTRUST_DAEMON_SOCKET), matching bt and the Braintrust SDKs. Do not add new BT_* names. Read them through bt-daemon/src/env.rs; DEPRECATED_BT_ENV_VARS there only keeps old names working. BT_TRACE_MANAGED_RUN_ID and BT_TRACE_INVOCATION_SETTINGS remain the internal protocol between bt trace run and its child processes.

Versioning is per distribution. Claude, Codex, Cursor, and Grok plugins carry their version in their plugin manifests. scripts/set-plugin-version.py updates those manifests for a release. Antigravity's schema does not expose a version field, so its distribution is versioned by repository tags and GitHub Releases. Claude's marketplace manifest carries a separate catalog version; bump it independently for breaking marketplace changes. The Codex marketplace manifest is unversioned.

A distribution repository is a generated artifact. Each deploy clones it, replaces the tracked tree with a fresh build, and pushes the result. braintrustdata/test-coding-agent-dist is the shared release sandbox.

To deploy manually, provide a comma-separated plugin:repo map:

PUBLISH_TARGETS="codex:braintrustdata/test-coding-agent-dist" make publish
DRY_RUN=1 PUBLISH_TARGETS="codex:braintrustdata/test-coding-agent-dist" make publish

Cross-repository pushes use GH_TOKEN or ambient Git credentials.

Run Release Plugin (release.yml) on main with a plugin and version. It opens or updates release/<plugin>/v<version> using Braintrust Bot, with the manifest changes and a monorepo-only .github/release-versions/<plugin> approval record. The record gives Antigravity a reviewable diff without adding a native manifest version. Preparation never tags or deploys.

A human approves and merges the PR under the existing branch protection rules. That merge starts a new run of Release Plugin (release.yml), which calls _release.yml with the PR's exact merge SHA, verifies the reviewed versions, creates v<version>-<plugin> and its GitHub Release, deploys the distribution, and creates its v<version> tag/release. Preparation and publication are separate event-driven runs under one workflow entry, named Prepare … and Publish …; no runner waits for review. Closing a PR without merging skips publication. It never pushes source changes to main. CI runs on release PRs; the current rules require one approval but do not require passing CI.

Cursor production releases then package and publish braintrustdata.braintrust to Open VSX with GitHub Actions OIDC in the openvsx-cursor environment. Register the monorepo's release.yml as the trusted publisher; see src/plugins/cursor/content/CONTRIBUTING.md for the exact configuration. Sandbox releases and manual distribution pushes do not publish to Open VSX. No Open VSX access-token secret is required.

If publishing is interrupted, rerun the publication run in Release Plugin rather than manually preparing the merged version again. An existing source tag must match the approved merge SHA; an existing distribution tag still rejects publication. An unchanged Antigravity artifact may reuse its previous distribution commit under the new version tag. If only the Cursor Open VSX job failed after distribution publication succeeded, use Re-run failed jobs to preserve the completed distribution release.

The manual test-release.yml workflow calls _release.yml at the selected commit, stamps versions only on the runner, and overwrites the shared test distribution repository without committing source changes or creating tags or releases. It does not require a PR. Pi and OpenCode retain their separate npm workflows, dispatched against an already-merged version-bump SHA.

Codex and Cursor deployments can run their installed-plugin smoke workflows, which trace a real CLI session through the daemon when OPENAI_API_KEY or CURSOR_API_KEY is available. Cursor's generated distribution is separate from the existing Braintrust MCP extension; users may install either or both.

The root .tool-versions pins Node, pnpm, Rust, and vite-plus for local development; CI reads its Node, pnpm, and Rust pins without mise through actions/setup-node, .github/actions/setup-node-pnpm, and .github/actions/setup-rust. Bump versions there rather than in individual workflows. mise.toml holds local-only mise hooks.

CI builds and validates the plugin packages on Linux. It runs the JavaScript daemon client and the Pi and OpenCode unit tests, and builds, tests, and lints the Rust daemon, on Linux, macOS, and Windows. Pushes to main and manual runs refresh the Rust build cache that pull requests restore. Every push to main runs independently; superseded pull request runs are cancelled.

• BRAINTRUST_BOT_APP_ID / BRAINTRUST_BOT_PRIVATE_KEY are the braintrustdata/braintrust-bot GitHub App credentials. Preparation mints a monorepo-scoped token with contents:write and pull_requests:write so bot-created PRs trigger CI. The app must be installed on this monorepo with both permissions. Deployment separately mints a token scoped to contents:write on the one distribution repository being deployed; the app must also be installed there. Missing installation or permissions fail the token step; do not bypass branch protection. Source tags use GITHUB_TOKEN.
• OPENAI_API_KEY enables the optional real Codex smoke test.

Braintrust authentication is deliberately not stored in plugin or daemon settings. The embedding bt CLI owns profiles, OAuth, keychain access, API keys, token refresh, and backend URL resolution.

bt-daemon/ is one self-contained Rust crate. The library is embedded by bt; the feature-gated standalone binary exists for development and integration tests. It owns event journaling, agent-specific translation, span construction, recovery, transport, and delivery. See bt-daemon/README.md.