> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Muse Code

> Trace Muse Code sessions to Braintrust and access your Braintrust data through the MCP server

[Muse Code](https://dev.meta.ai/docs/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.

> [!NOTE]
>
> 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](https://dev.meta.ai/docs/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](https://docs.braintrust.dev/reference/cli/quickstart) to install `bt`, authenticate, and set your active context.

**3. Enable tracing**

Run this command in a terminal:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace enable muse --project <your-project>
```

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`](https://docs.braintrust.dev/reference/cli/trace#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\*\*](https://www.braintrust.dev/app/~/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

> [accordion] Use different tracing settings for one session
>
> Use [`bt trace run`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-run) to trace a single Muse Code invocation without changing the saved tracing configuration:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt trace run --project <your-project> muse
> bt trace run --project <your-project> muse -- exec "summarize this repo"
> ```
>
> 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`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-enable) with the corresponding options. Running [`bt switch`](https://docs.braintrust.dev/reference/cli/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](https://docs.braintrust.dev/reference/cli/trace.md#tag-traces).

> [accordion] Trace a saved Muse Code session
>
> Use [`bt trace import`](https://docs.braintrust.dev/reference/cli/trace#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`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-import).

> [accordion] Resume a Muse Code session
>
> When you resume a Muse Code session, new turns are added to its existing Braintrust trace.

> [accordion] Stop tracing Muse Code sessions
>
> Use [`bt trace disable muse`](https://docs.braintrust.dev/reference/cli/trace#bt-trace-disable) 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](https://docs.braintrust.dev/reference/cli/migrate.md) to update `bt` to the latest version and complete the applicable migrations.

**2. Update the hooks**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt trace update muse
```

[`bt trace update`](https://docs.braintrust.dev/reference/cli/trace#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\*\*](https://www.braintrust.dev/app/~/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:

> [accordion] Traces do not appear after setup
>
> 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](https://docs.braintrust.dev/reference/cli/trace.md#project-log-permissions).
>
> For authentication, tracing destination, or endpoint problems, see [`bt trace` troubleshooting](https://docs.braintrust.dev/reference/cli/trace#troubleshooting).

> [accordion] Setup reports an unrecognized Braintrust forwarder
>
> `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**

> [tab] OAuth (recommended)
>
> 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.

> [tab] API key
>
> Use an API key for clients without OAuth support or for programmatic connections. The server acts with the permissions of the account the key belongs to.
>
> 1. Create a key in \*\* Settings\*\* > [\*\* API keys\*\*](https://www.braintrust.dev/app/~/configuration/api-keys).
> 2. Configure your client to send this header on every request, replacing `YOUR_BRAINTRUST_API_KEY` with your key:
>
>    ```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
>    Authorization: Bearer YOUR_BRAINTRUST_API_KEY
>    ```

> [!NOTE]
>
> Your [`bt login`](https://docs.braintrust.dev/reference/cli/login) doesn't authenticate the MCP server.

**2. Choose your endpoint**

Use the endpoint for your organization's [data plane region](https://docs.braintrust.dev/admin/organizations.md#data-plane-region):

| Region | MCP endpoint |
| - | - |
| US | `https://api.braintrust.dev/mcp` |
| EU | `https://api-eu.braintrust.dev/mcp` |

Other connection details:

* **Self-hosted:** Copy the **MCP URL** from \*\* Settings\*\* > [\*\* Data plane\*\*](https://www.braintrust.dev/app/~/configuration/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](https://dev.meta.ai/docs/muse-code/extending#mcp) 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](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#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](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#what-the-mcp-can-do) for more workflows and example prompts.

## Next steps

* **Learn the CLI**: See the full [`bt trace` reference](https://docs.braintrust.dev/reference/cli/trace).
* **Run evaluations**: Follow the [evaluation guide](https://docs.braintrust.dev/evaluate/run-evaluations.md).
* **Explore MCP tools**: See the [Braintrust MCP tool reference](https://docs.braintrust.dev/integrations/developer-tools/mcp.md#tools).
* **Browse the source**: View the [coding-agent plugins repository](https://github.com/braintrustdata/braintrust-coding-agent-plugins).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.