Documentation Index
Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
Use this file to discover all available pages before exploring further.
bt setup configures Braintrust integrations for coding agents (Claude, Cursor, Codex, Opencode). Run it once to give your agent access to Braintrust skills, workflow documentation, and MCP tools (optional).
On first run, bt setup walks you through authentication and API key creation interactively. No manual API key setup is required beforehand. The created API key is displayed after org selection, before project selection. Save it, as it will not be shown again.
bt setup # Interactive wizard (handles auth + API key creation)
bt setup --local --agent claude # Configure Claude for current repo
bt setup --global --agent codex # Configure Codex user-wide
--no-input. This requires --project <NAME>, either --api-key <KEY> or BRAINTRUST_API_KEY, and --agent <AGENT> unless exactly one supported agent is on PATH.
bt setup skills
Writes agent-specific skill files so your agent knows how to use Braintrust. Also prefetches workflow docs. Install locations by agent: Claude (.claude/skills/braintrust/SKILL.md), Cursor (.cursor/rules/braintrust.mdc), Gemini (symlinks .gemini/skills to .agents/skills/braintrust/SKILL.md).
bt setup skills --local --agent claude --workflow evaluate
bt setup skills --global --agent codex --agent cursor
bt setup instrument
Runs a coding agent against your repo to automatically add Braintrust SDK instrumentation (tracing, logging). The agent detects your project language, installs the exact SDK version, instruments your LLM clients, runs the app to verify the integration, and outputs a Braintrust permalink to the emitted trace.
bt setup instrument --agent codex
bt setup instrument --agent claude
bt setup instrument --agent claude --language typescript
- Verifies that
BRAINTRUST_API_KEY is set — aborts if missing
- Detects the project language from build files:
package.json → TypeScript, requirements.txt/pyproject.toml → Python, pom.xml/build.gradle → Java, go.mod → Go, Gemfile → Ruby, .csproj → C#
- Looks up and installs the latest exact SDK version (never uses
latest)
- Instruments LLM clients in the app entry point
- Runs the app to verify traces are emitted
- Outputs a Braintrust permalink to the captured trace
What the agent does NOT do: refactor unrelated code, add eval code, or add manual flush/shutdown logic. The app is required to run correctly without BRAINTRUST_API_KEY set.
Supported languages: Python, TypeScript/JavaScript, Go, Java, Ruby, C#
Instrumentation approach by language:
| Language | SDK package | Instrumentation |
|---|
| Python | braintrust | braintrust.init_logger() + braintrust.auto_instrument() or manual wrappers |
| TypeScript | braintrust | initLogger() + wrapOpenAI() / framework wrappers |
| Go | github.com/braintrustdata/braintrust-sdk-go | braintrust.New() + Orchestrion compile-time instrumentation |
| Java | dev.braintrust:braintrust-sdk-java | Braintrust.get() + BraintrustOpenAI.wrapOpenAI() |
| Ruby | braintrust gem | require "braintrust/setup" or braintrust exec wrapper |
| C# | Braintrust.Sdk NuGet | Braintrust.Get(config) + BraintrustOpenAI.WrapOpenAI() |
| Flag | Description |
|---|
--language <LANG> | Force language (repeatable): python, typescript, javascript, go, java, ruby, csharp |
--agent-cmd <CMD> | Override agent command (replaces the built-in default) |
--quiet / -q | Suppress streaming agent output |
--interactive / -i | Run agent in interactive mode |
--yolo | Grant full permissions and run in background without prompting |
bt setup mcp
Adds the Braintrust MCP server to your agent’s config so it can query Braintrust data directly.
bt setup mcp --local --agent claude
bt setup mcp --global --agent codex
bt setup doctor
Diagnoses your coding agent setup and reports what is and isn’t configured.
bt setup doctor --local
bt setup doctor --global
Common flags
| Flag | Description |
|---|
--agent <AGENT> | Agent to configure: claude, codex, cursor, gemini, opencode (repeatable; auto-detected if omitted) |
--local | Configure for the current git repo |
--global | Configure user-wide |
--workflow <WORKFLOW> | Prefetch docs for a workflow: instrument, observe, annotate, evaluate, deploy (repeatable) |
--no-input | Non-interactive mode for CI; requires --project, credentials, and --agent unless one agent is auto-detected |
--refresh-docs | Clear and re-fetch any previously downloaded docs |
