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 have this permission by default. Otherwise, ask an owner to connect it.
- Go to Settings > Integrations.
- Click Connect Slack. If a workspace is already connected, click Workspace to add another.
- Select your Slack workspace and authorize the app.
Already connected?
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.
- Open a DM with Braintrust and ask a question.
- Click Link Braintrust account in Loop’s reply.
- Sign in to Braintrust and click Approve.
/braintrust link to link your account before asking a question.Chat with Loop
See What Loop can do for investigation ideas.Choose where to chat
- Private chat: Open the Braintrust app’s Agent tab or start a DM with Braintrust.
- Channel: Include
@Braintrustin a new top-level message.
Ask a question
Describe what you want to investigate and include the project name and a time range. For example:@Braintrust /org before your question.
How links select an organization
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.
Attach files
Loop reads files attached to the message that triggers it. When you bring Loop into an existing discussion, 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.
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:@Braintrust /configuration once the conversation has started.
Bring Loop into an existing discussion
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.Conversations in channels
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.
@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.Investigate an alert
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.
- Deny: Decline the call and let Loop continue without it.
Troubleshoot an approval
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.- Click Connect GitHub in Loop’s reply.
- In the browser, sign in with the same Braintrust account you linked to Slack and complete the connection.
- Return to Slack. Loop resumes the request, and your connection is saved for future sessions.
Cancel or troubleshoot a connection
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.
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.
Choose a model and reasoning effort
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>oreffort=<effort>with your prompt.
/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. 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
- Send
@Braintrust /orgin the thread. - Select an organization you can access that is connected to the Slack workspace.
When Loop proposes a move
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.
@Braintrust /org to choose a destination yourself.If a thread cannot move
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 /orgto choose an organization again. - Loop can’t read the full thread.
@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).
Account already linked to another Slack user
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.
Can't access the default organization
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.Lost organization access
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.Request denied
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.
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.