> ## 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.

# Loop in Slack

> Connect Slack to Braintrust and investigate your organization's data with Loop.

Loop in Slack lets you investigate your organization's data from a direct message (DM), the Braintrust app's **Agent** tab, or a channel thread.

> [!WARNING]
>
> Loop in Slack is in [private preview](https://docs.braintrust.dev/feature-lifecycle.md), available to a limited set of customers. Behavior can change during the preview. To request access, [contact Braintrust](https://braintrust.dev/contact).

## Connect Slack and Loop

Connect your Slack workspace once, then have each person link their own Braintrust account.

**1. Connect your workspace**

You need the **Manage settings** organization permission to connect a workspace. [Organization owners](https://docs.braintrust.dev/admin/access-control.md#built-in-permission-groups) have this permission by default. Otherwise, ask an owner to connect it.

1. Go to \*\* Settings\*\* > [\*\* Integrations\*\*](https://www.braintrust.dev/app/~/configuration/integrations).
2. Click **Connect Slack**. If a workspace is already connected, click  **Workspace** to add another.
3. Select your Slack workspace and authorize the app.

If Slack requires installation approval, ask a workspace owner or app manager to approve it.

> [accordion] Already connected?
>
> If your connected workspace shows a **Needs refresh** status, click  **Refresh permissions** in its row and authorize the requested permissions.

**2. Link your account**

Use a Braintrust account that belongs to an organization connected to your Slack workspace.

1. Open a DM with **Braintrust** and ask a question.
2. Click **Link Braintrust account** in Loop's reply.
3. Sign in to Braintrust and click **Approve**.

Loop answers your original question in the same thread.

You can also run `/braintrust link` to link your account before asking a question.

## Chat with Loop

See [What Loop can do](https://docs.braintrust.dev/loop.md) for investigation ideas.

### Choose where to chat

* **Private chat:** Open the Braintrust app's **Agent** tab or start a DM with **Braintrust**.
* **Channel:** Include `@Braintrust` in a new top-level message.

> [!WARNING]
>
> Conversations started in public Slack channels are visible to everyone in the
> conversation's Braintrust organization, including people outside the channel.
> Loop's replies are also visible to everyone in the Slack channel, including
> people without access to the underlying Braintrust data. Use a DM or the
> **Agent** tab for a private conversation.

### Ask a question

Describe what you want to investigate and include the project name and a time range. For example:

```text wrap theme={null}
Look at the errors in the Customer Support project's logs from the last 24 hours.

Which errors occur most often, and what do the affected traces have in common?

Summarize the findings and include links to representative traces.
```

New conversations use the channel or DM's [default organization](#set-the-default-organization), unless you include a Braintrust link to another eligible organization. To choose one yourself, send `@Braintrust /org` before your question.

> [accordion] How links select an organization
>
> Loop uses the organization from the first Braintrust link in your message if you belong to that organization and it is connected to the Slack workspace. When you bring Loop into an existing thread, it also checks the thread's first message if your mention has no Braintrust link. If neither message identifies an eligible organization, Loop uses the default.
>
> The link selects only the organization, not a project, and doesn't change channel defaults. Links in later replies don't change the organization automatically, but Loop can [propose a move](#move-a-thread-to-another-organization).

### Attach files

Loop reads files attached to the message that triggers it. When you [bring Loop into an existing discussion](#continue-the-conversation), it also reads files uploaded or forwarded in earlier messages as context, not as new requests.

* **Supported files:** PNG, JPEG, and WebP images, PDFs, and text files such as CSV and JSON.
* **Limits:** Up to 8 files per request, 20 MB per file, and 40 MB total. Files on the triggering message take priority.
* **Unsupported files:** Other image formats, video, audio, Slack canvases, files shown only in link previews, and files hidden by your workspace's Slack plan limits.

Loop identifies skipped files and explains why it couldn't read them. If Slack blocks a download, check whether the app needs a [permissions refresh](#connect-slack-and-loop) to grant `files:read` access.

### Continue the conversation

Reply in the same thread to use the conversation's history, including when asking about another project in the same organization. For example:

```text wrap theme={null}
For the most common error, compare affected traces with successful traces
from the same period.

What differences could explain the failures?
```

Send a follow-up while Loop is working to interrupt the request and steer the conversation. Send a new top-level message to start a separate conversation.

Click **Open in Braintrust** below Loop's latest reply to view the conversation in Braintrust. You can also find the link with `@Braintrust /configuration` once the conversation has started.

> [accordion] Bring Loop into an existing discussion
>
> Mention `@Braintrust` in a reply, with or without a question. Loop reads up to 100 messages from the start of the thread, including text posted by other bots and apps. Summarize important context from later messages in long threads.
>
> If other people have already posted, Loop answers your mention and then mutes itself. Mention `@Braintrust` or send `@Braintrust unmute` to continue. Bots and apps don't count as participants.

> [accordion] Conversations in channels
>
> Loop listens to replies without requiring `@Braintrust`, but mutes itself when:
>
> * A new participant replies without mentioning `@Braintrust`. If their first reply mentions Loop, it keeps listening.
> * A reply in a public channel mentions another person or app without mentioning `@Braintrust`. Loop doesn't answer that reply. Self-mentions don't mute Loop.
>
> Send `@Braintrust mute` to require mentions, or `@Braintrust unmute` to resume listening. After an unmute, new participants alone don't mute Loop again, but mentions of other people or apps still can.
>
> While Loop is muted, 🔇 `[muted]` appears next to **Open in Braintrust** below its replies in the thread.
>
> Teammates need a linked account and membership in the conversation's Braintrust organization, or read access to its project for a project-scoped conversation. Loop uses each participant's own permissions. In DMs and the **Agent** tab, mentions aren't required.

> [accordion] Investigate an alert
>
> Copy the alert text into a DM with Braintrust. Include the project name and the time range the alert covers, then ask Loop to investigate. Check that the DM uses the project's organization, and review the supporting traces before acting on a suggested cause.

## Approve Loop's actions

Loop asks for approval before it runs some tools or a list of proposed actions. It posts an **Approval required** card that names the tool or, for proposed actions, shows Loop's reason. Approving proposed actions covers only the current request, and **Always allow this tool** doesn't apply to them, so leave it unselected.

Only the person who sent the request can approve. Other participants see only **Deny**.

* **Allow:** Run this call with your Braintrust permissions.
* **Always allow this tool:** Select this option before clicking **Allow** to allow this tool for your subsequent requests in this thread and its current organization or project. This doesn't apply to teammates, new threads, or threads [moved to another organization](#move-a-thread-to-another-organization).
* **Deny:** Decline the call and let Loop continue without it.

Any participant with a linked account and access to the conversation's organization or project can deny a call.

> [accordion] Troubleshoot an approval
>
> * **No longer available:** The request that needed approval has ended. Send a new message to continue.
> * **Not authorized or no access:** Your linked Braintrust account can't access the conversation's organization or project. Ask a Braintrust admin to grant access.
> * **Can't deny another person's tool call:** If Loop asks you to update your data plane, ask a Braintrust admin to update the organization's data plane. Until then, only the requester can allow or deny calls.

## Connect GitHub

Loop prompts you to connect GitHub when a request needs access and your account isn't connected. Only the requester sees **Connect GitHub**.

1. Click **Connect GitHub** in Loop's reply.
2. In the browser, sign in with the same Braintrust account you linked to Slack and complete the connection.
3. Return to Slack. Loop resumes the request, and your connection is saved for future sessions.

Connection requests expire after five minutes. Ask Loop to try again if yours expires. If GitHub requires you to authorize single sign-on (SSO) for an organization's repositories, ask Loop to reconnect GitHub, even if your account is connected. See [GitHub access requirements](https://docs.braintrust.dev/loop/github.md#connect-your-github-account) for account and repository permissions.

> [accordion] Cancel or troubleshoot a connection
>
> Click **Cancel** in Slack, or **Cancel and continue in Slack** in the browser, to continue without connecting GitHub. Other participants can cancel from Slack if they have a linked account and access to the conversation's organization or project.
>
> If you cancel, Loop won't ask you to connect again unless you request it. A teammate's cancellation applies only to that request.
>
> * **Connection started by a different user:** Sign in with the Braintrust account linked to the Slack user who requested the connection.
> * **Connection started in a different workspace:** Return to the Slack workspace where the request started.
> * **Can't cancel another person's connection request:** If Loop asks for a data plane update, ask a Braintrust admin to update it. The requester can still cancel.

## Manage conversation settings

Use these commands to check or change the conversation's settings.

| Command | Action |
| - | - |
| `@Braintrust /org` | See or change this thread's organization. |
| `@Braintrust /configuration` | Show this thread's organization, model, reasoning effort, reply mode, and link to the conversation. |
| `@Braintrust /models` | List available models and the reasoning efforts each supports. |
| `@Braintrust /model` | Choose this thread's model. |
| `@Braintrust /effort` | Choose a reasoning effort supported by this thread's model. |
| `@Braintrust /help` | Show available commands and setup help. |

Send the command as the whole message. In channels, include an explicit `@Braintrust` mention. In DMs and the **Agent** tab, these commands work without a mention.

> [accordion] Choose a model and reasoning effort
>
> Model and effort settings persist for the thread. Use `/models` to find an available model ID and its supported efforts.
>
> * **Use a picker:** Send `@Braintrust /model`, then `@Braintrust /effort`. Choose a model before setting its effort.
> * **Set without asking a question:** Send `@Braintrust /model <model ID> effort=<effort>`. Omit the effort to change only the model, or send `@Braintrust effort=<effort>` to change only the effort.
> * **Set and ask:** Include `model=<model ID>` or `effort=<effort>` with your prompt.
>
> The pickers and settings-only messages don't start a request. If Loop is busy, wait before using a picker. `/configuration` shows **Default** for settings you haven't selected.

### Set channel defaults

Run `/braintrust configure` in the channel or DM, then choose an organization from **Select organization**. You need a linked account. The menu lists organizations connected to the workspace that you belong to.

Optionally, choose a **Default project** for new conversations. Changing the default organization clears this selection.

Defaults apply only to new conversations. Loop attaches the default project if the person starting the conversation can read it and it belongs to the selected organization. Otherwise, it skips the project. Attaching a project doesn't restrict the conversation to that project.

To change an existing conversation, [move the thread](#move-a-thread-to-another-organization). If Loop asks for a data plane update when setting a default project, ask a Braintrust admin to update it.

### Move a thread to another organization

> [!WARNING]
>
> Moving a thread stops any response in progress and copies the thread's
> messages and Loop's earlier replies to the new organization. Check that the
> conversation is appropriate to share there before moving it.

1. Send `@Braintrust /org` in the thread.
2. Select an organization you can access that is connected to the Slack workspace.

After a manual move, Loop waits for your next request in the new organization. It checks access again and doesn't treat copied messages or previous approvals as permission to repeat earlier actions. If your model isn't available there, Loop selects one that is.

> [accordion] When Loop proposes a move
>
> Ask Loop to switch organizations, or follow its suggestion when a request concerns another organization. Loop can propose a destination you can access that is connected to the Slack workspace and uses the same data plane. The card names the destination and any task to perform after moving.
>
> * **Approve organization switch:** Move the thread and authorize only the task described on the card, using your permissions.
> * **Cancel:** Dismiss the card and keep the thread in its organization. Loop waits for your next request.
>
> Only the requester can approve or cancel the card. If Loop can't propose a specific eligible destination, it can show a picker instead. Selecting an organization moves the thread and authorizes only the task described above the picker, using the selector's permissions.
>
> The picker is private to the requester in public channels and visible in the thread in private channels and DMs. Use `@Braintrust /org` to choose a destination yourself.

> [accordion] If a thread cannot move
>
> Older project-scoped threads cannot change organizations. Start a new thread instead.
>
> Both organizations' data planes must support organization switching. If Loop reports that a data plane doesn't support it, ask a Braintrust admin to update it.
>
> A move fails, and the previous organization stays selected, if:
>
> * The thread is in a channel and Loop responded privately earlier in it.
> * The thread is too long to copy.
> * A message in the thread contains files, including files in a forwarded message.
> * The organization proposed by Loop no longer uses this data plane. Use `@Braintrust /org` to choose an organization again.
> * Loop can't read the full thread.
>
> Loop copies only message text. It leaves out cards, such as link previews, previews of Slack messages and other apps, and embedded images, and skips messages that contain only cards.
>
> If a move fails, start a new thread and use `@Braintrust /org` before asking your question.

## Unlink your account

To disconnect your Braintrust account from Slack, run `/braintrust unlink`.

## Troubleshooting

For setup help and available commands, send `@Braintrust /help` in the thread, or run `/braintrust help` (or `/braintrust` without arguments).

> [accordion] Braintrust left a shared channel
>
> Braintrust doesn't work in Slack Connect channels, which are shared with other companies' Slack workspaces:
>
> * **Adding Braintrust to a shared channel:** Braintrust privately tells you it can't be added, then leaves.
> * **Sharing a channel Braintrust is in:** Braintrust posts a notice in the channel, then leaves.
> * **Mentioning `@Braintrust`:** Braintrust privately replies that it isn't available, and Loop doesn't respond.
> * **Braintrust links:** Links in shared channels don't expand.
>
> To use Loop, switch to a DM, the **Agent** tab, or an internal channel. If Braintrust stays in a shared channel, [refresh the workspace's permissions](#connect-slack-and-loop) so it can leave.

> [accordion] Account already linked to another Slack user
>
> Each Braintrust account can only be linked to one Slack user per workspace. Sign in with your own Braintrust account.

> [accordion] Can't access the default organization
>
> Run `/braintrust configure` to select another organization you belong to. If no eligible organizations appear, ask a Braintrust admin to grant access or configure the channel.

> [accordion] Lost organization access
>
> If `/configuration` reports that you no longer have access to the thread's organization, use `@Braintrust /org` to choose another before your first request. If you've already started a conversation, start a new thread and choose the organization there.

> [accordion] Request denied
>
> If Loop reports that Braintrust denied or couldn't authenticate the request, check that Slack is linked to the correct Braintrust account. Then ask a Braintrust admin to grant membership in the organization, or read access to the project for a conversation scoped to a project.

> [accordion] Model unavailable or credits exhausted
>
> If Loop reports an unavailable model, an unsupported model on the data plane, or exhausted built-in model credits, ask a Braintrust admin to check the organization's [models and providers](https://docs.braintrust.dev/loop/manage.md#models-and-providers).

## Limitations

* Workflows that depend on Braintrust UI controls, such as opening workspace panels or editing a query on the Query page, aren't available within Slack.
* Loop isn't available in Slack Connect channels, which are shared with other companies' Slack workspaces. See [Braintrust left a shared channel](#troubleshooting).


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