Skip to main content
Muse Code is Meta’s coding agent for the terminal and CI. You can connect it to Braintrust in two ways:
  • Trace Muse Code sessions to record session, turn, model call, tool, and subagent spans in Braintrust.
  • Connect to Braintrust MCP to work with Braintrust projects, experiments, logs, and other data from Muse Code.
Braintrust tracing for Muse Code requires bt v0.28.0 or later and Muse Code 1.3.0 or later.

​
Trace Muse Code sessions

bt traces Muse Code sessions through Muse Code’s command hooks. There is no separate plugin to install.

​
Set up tracing

1

Install Muse Code

If you haven’t already, install Muse Code 1.3.0 or later. Make sure its muse command is available in your terminal.
2

Install and authenticate bt

Follow the bt CLI quickstart to install bt, authenticate, and set your active context.
3

Enable tracing

Run this command in a terminal:
This command:
  • Adds Braintrust hook entries for each Muse Code lifecycle event to the hooks object in $XDG_CONFIG_HOME/muse/settings.json (defaults to ~/.config/muse/settings.json). Other hooks and settings in the file are preserved.
  • Writes $XDG_CONFIG_HOME/muse/braintrust.json (defaults to ~/.config/muse/braintrust.json), which records whether tracing is enabled and which project receives traces.
The tracing file stores settings, not credentials. These settings apply across projects during normal sessions.For more information, see bt trace enable.
4

Log a test trace

Muse Code loads hooks when a session starts, so start a new Muse Code session. Then ask Muse Code to do something simple. When the turn finishes, open your Braintrust project and confirm that the trace appears on the Logs page.

​
What Braintrust traces

Muse Code traces in Braintrust include:
  • Session spans with the session ID, local username, working directory, model, provider, permission mode, Muse Code version in metadata.muse_version, Git repository metadata when available, the final response of the last completed turn, and token totals.
  • Turn spans with prompts and final responses. Turns that fail record the error.
  • Model call spans with conversation input, tool definitions, response output, token metrics, and the finish reason, response ID, status, and request options in metadata.
  • Tool spans with inputs, outputs, and errors, and the result in metadata.tool_outcome.
  • Subagent spans with the subagent ID and child session ID.
  • Context compaction spans, tagged compaction, and permission request and notification spans, tagged permission-request and notification.
Every span records its origin as braintrust.plugin.muse in context.span_origin. Each turn span and every span under it records the turn’s span ID in metadata.turn_span_id. bt sends pending spans at the end of each turn.

​
Common workflows

Use bt trace run to trace a single Muse Code invocation without changing the saved tracing configuration:
This workflow launches muse from the terminal. Set BRAINTRUST_MUSE_BIN to launch a different executable. bt adds its hooks to that invocation only and doesn’t send events through the hooks saved by bt trace enable, so the session isn’t traced twice.To change the saved destination, profile, or organization, rerun bt trace enable muse with the corresponding options. Running bt switch does not change the saved tracing configuration.To add root-span metadata, pass --additional-metadata '<JSON>' to bt trace run for one invocation or to bt trace enable for future sessions. Standard session metadata takes precedence when keys conflict.Pass --tag ci --tag release-validation to either command to tag session spans.
Use bt trace import with muse and the session ID to import a past session, even if tracing was not enabled when it ran. Pass --all to import every saved session. bt reads sessions with muse export, so muse must be on your PATH, or set BRAINTRUST_MUSE_BIN to its path.Imported sessions include prompts, final responses, model calls with responses and token usage, and tool calls. They don’t include the conversation sent to each model call, and they have no subagent, compaction, permission request, or notification spans.To follow an active session, pass --attach with its session ID. Pressing Ctrl-C stops following the session without ending it. To record the rest of the session, attach again or import it after it finishes.To nest an imported session under an existing span or send it to an experiment, pass --parent or --destination to bt trace import.
When you resume a Muse Code session, new turns are added to its existing Braintrust trace.
Use bt trace disable muse to remove the Braintrust hook entries from Muse Code’s settings.json and delete its tracing configuration. Other hooks and saved bt profiles and credentials are preserved.

​
Update the tracing hooks

Updating bt also updates the Braintrust hooks in Muse Code’s settings. To update them, follow these steps:
1

Update bt

Follow the CLI migration guide to update bt to the latest version and complete the applicable migrations.
2

Update the hooks

bt trace update refreshes the Braintrust hook entries in Muse Code’s settings.json without changing your saved tracing configuration. If the hooks aren’t installed, run bt trace enable muse instead.
3

Verify in a new session

Start a new Muse Code session, run a short task, and confirm that its trace appears on the Logs page in the intended Braintrust project.

​
Troubleshooting tracing

First, run bt trace doctor muse. The report warns when Muse Code is missing or earlier than 1.3.0, when bt isn’t on your PATH, and when the Braintrust hooks in settings.json are missing or outdated. Then, review the following:
Muse Code’s hooks run bt by name, so confirm that bt is on the PATH of the environment that launches muse. If a Muse Code session was running when you enabled tracing, start a new session.Run bt trace doctor muse and confirm that tracing is enabled and routed to the intended project.If authentication succeeds but traces do not appear, confirm that your account has permission to write logs to the selected project.For authentication, tracing destination, or endpoint problems, see bt trace troubleshooting.
bt trace enable muse and bt trace run muse stop with an error when Muse Code’s settings or managed hooks already contain a Braintrust forwarder, a bt trace hook command that bt didn’t write, so the session isn’t traced twice. Remove the manually added Braintrust hook entries and rerun the command.bt trace run muse also stops when a .muse/hooks.json file in the working directory or one of its parent directories already includes Braintrust tracing.

​
Connect to Braintrust MCP

The Braintrust MCP server lets Muse Code query and update Braintrust data. MCP is configured independently from tracing.
1

Choose authentication

Use OAuth when your client supports it. Your client opens a Braintrust authorization page where you sign in and approve access. The server acts with the permissions of the account you sign in with.
  • No Braintrust API key required
  • No OAuth client ID or client secret to configure
The server implements OAuth 2.0 with dynamic client registration and publishes its metadata at /.well-known/oauth-authorization-server on the same host as your MCP endpoint (see next step), so a client can register itself.
Your bt login doesn’t authenticate the MCP server.
2

Choose your endpoint

Use the endpoint for your organization’s data plane region:Other connection details:
  • Self-hosted: Copy the MCP URL from Settings > Data plane. This is your Braintrust API URL with /mcp appended.
  • Transport: If your client asks you to choose a transport, choose HTTP (also called streamable HTTP). SSE-only clients can’t connect.
3

Add the server to Muse Code

Follow the Muse Code guide to add the remote server.
4

Verify the connection

To verify the connection, ask Muse Code to list your recent Braintrust projects. If it can’t connect, see Braintrust MCP troubleshooting.
5

Start using Braintrust tools

Muse Code can query logs, compare experiments, work with datasets, and use other Braintrust tools. For example:
  • “Show me my recent Braintrust experiments.”
  • “Query the last 10 logged requests with errors.”
  • “Compare accuracy scores between my two latest experiments.”
See what the Braintrust MCP can do for more workflows and example prompts.

​
Next steps