Skip to Content
OpenInspect
Integrations

Slack

Start OpenInspect sessions from Slack channels and DMs, continue them in threads, set personal defaults in App Home, and let agents post updates.

Last reviewed View as MarkdownEdit on GitHubGive feedback

Mention the OpenInspect bot in a channel or DM it, pick a target if asked, and continue the session in the same Slack thread. Mention the bot again on interactive channel follow-ups, unless your mention started the session and its acknowledgement said you can reply without one; DM follow-ups need no mention.

This page is for people using Slack day to day. Installing the Slack app and deploying the worker is operator work; see Getting started in the repository.

Quick start

Invite the bot

Invite the OpenInspect Slack app to any channel where you want to use it.

Send a request

In a channel, mention the bot. In a DM, just type the request.

@OpenInspect fix the failing checkout tests in acme/web

Pick a target if asked

If OpenInspect cannot tell which repository you mean, choose a repository, an environment, or No repository from the dropdown.

Follow the work

Use View Session to open the full web session while the agent works. To continue, reply in the same thread and mention the bot if it is a channel thread (not needed in a solo thread). In a DM thread, just reply.

The whole exchange stays in one Slack thread:

What Slack can do

WorkflowHow it works
Start from a channelInvite the bot, then @mention it with a request
Start from a DMSend the bot a direct message
Continue a sessionReply in the same thread; @mention the bot unless the thread is solo
Send images to the agentAttach PNG, JPEG, WebP, or GIF images to an interactive request
Forward a messageShare another Slack message with the bot; text, images, and source travel
Pick the session targetUse a repository, environment, or empty sandbox
Set personal defaultsUse the Slack app's Home tab for model, reasoning effort, and branch
Follow the resultRead the completion reply or open the full session with View Session
Review generated mediaCharts, screenshots, and small recordings can be attached to the thread
Ask the agent to post to SlackEnable agent notifications, then explicitly ask the agent to post
Auto-trigger from a channelWatch a channel so matching messages start an automation

There are no slash commands. In channels, interactive requests need an @mention. Ordinary channel messages can only start work through a Slack message automation.

Starting a session

From a channel

Invite the bot first, then mention it. Name the repository when the request could apply to more than one:

@OpenInspect update the billing docs in acme/api

OpenInspect picks a target in this order: a matching routing rule, then a channel association, then a classifier that looks at your message, the channel, and recent thread context. The classifier can pick an environment as well as a repository, and it can pick No repository when the task does not need a codebase. If the match is unclear, OpenInspect asks you to choose in the thread.

Channel sessions do not use your personal memories, because their replies post where others read them. Repository and environment memories still apply.

From a DM

Open a direct message with the bot and send the request. No mention is needed; if you include one, it is stripped before the request reaches the agent.

To continue a DM session, reply in the thread Slack created for that request. A new top-level DM is a new request and may start target selection again.

A DM session uses your personal memories the way a web session does, when your Use my personal memories in my sessions setting is on. See Memories.

Model and reasoning flags

Start a request with !model or !reasoning to override your App Home defaults:

@OpenInspect !model anthropic/claude-sonnet-4-6 !reasoning max investigate the flaky test
Where you use the flagsEffect
On the request that starts a sessionThey become that session's defaults. Every follow-up in the thread keeps them. The "Starting work..." acknowledgement names the model when it differs from your App Home default
On a follow-up in an existing threadThey apply to that one request only. The session's defaults do not change

A running session's defaults cannot be changed. To go back to your defaults for good, start a new session in a new thread. Both flags accept a space or a colon before the value (!model:openai/gpt-5.6-sol, !reasoning:high), and all flags must appear together at the start of the request. Models must be enabled under Settings › Models, and the reasoning value must be supported by the model.

A thread runs on one agent harness for its whole life. On a request that starts a session, a !model that your harness cannot run is refused and no session starts. On a follow-up, the control plane rejects a !model that the thread's harness cannot run, and the bot replies in the thread:

Model "openai/gpt-5.4" cannot run on the Claude Agent harness. A thread keeps the harness its session started on. Reply without !model, or start a new thread to use that model.

A !reasoning-only follow-up keeps the thread's session model, as a follow-up without flags does, even if an administrator has since disabled that model. The thread's harness was chosen to run that model, so the follow-up always runs.

Image attachments

Attach PNG, JPEG, WebP, or GIF images to a DM, to a channel request that mentions the bot, or to an interactive thread follow-up, with instructions or on their own (for example a screenshot with "fix the visible error"). Limits: at most six images per message, 10 MiB each. Images on earlier messages in the thread can also be forwarded as context; the current request's images take priority within the six-image limit.

In an interactive channel thread, mention the bot on a follow-up for its text, images, or forwarded messages to reach the agent. Without a mention, the follow-up does not send an instruction to the session, except in a solo thread. In a DM, no mention is needed. Watched-channel automations are a separate workflow and can respond to unmentioned text.

  • If OpenInspect asks you to choose a target, choose normally; the images are retrieved after you pick and sent with the saved request.
  • If some images cannot be read, the rest still reach the agent and the bot posts a warning in the thread. If an image-only request loses every image, nothing is sent.
  • Remote files hosted outside Slack and non-image attachments are not forwarded.

Slack app scope

Inbound images need the Slack app's files:read scope, and a reinstall after adding it.

Forwarded messages

Share (forward) another Slack message to a DM, to a channel request that mentions the bot, or to a thread follow-up (with an @mention in channels, unless it is a solo thread). Add a comment such as "deal with this" and the comment becomes the instruction; forward without a comment and the shared message is the whole request.

The agent receives the forwarded text with links as written, its images (same six-image, 10 MiB limits), and its author, source channel, permalink, channel id, and timestamp. You can forward up to ten messages per request; each is truncated at 4,000 characters. Link previews are skipped.

Target dropdowns

Dropdowns show the repositories and environments available in the channel's scope plus No repository (an empty sandbox). They belong to the pending thread, not to a personal GitHub repository list. OpenInspect keeps the original request for one hour; once you choose, it rechecks the binding and starts with that request and thread context. A picker saved before a channel changes teams cannot launch into the new team.

The planned model is rechecked before launch. If it was disabled while the request was pending, the bot refuses to start a session rather than substituting another model. Send a new request with an enabled model.

In shared channels, only the original requester can choose. If the dropdown has expired, send the request again and name the target.

Threaded conversations

A top-level request starts a thread. For interactive sessions, reply in that thread with an @mention in channels; in a DM thread, reply without a mention. Text, images, and forwarded messages on unmentioned channel replies are not delivered as interactive follow-ups, except in a solo thread. Slack message automations handle unmentioned channel text separately.

Solo threads

A channel thread becomes a solo thread when your @mention of the bot starts its session and the bot's acknowledgement says: "You can reply without mentioning me while you are the only person in this thread." The bot adds that line only when it reads the thread as the session starts and finds that only you and bots have posted. In a solo thread, your replies send an instruction to this session without mentioning the bot.

ThreadDoes a reply need an @mention to send an instruction?
Solo thread, reply from the person who started the sessionNo
Another person has posted in the threadYes, for everyone, from then on
Another person posted before the session startedYes; the acknowledgement has no solo line
DM threadNo

When the bot notices another person in a solo thread, from their post or from the thread it reads for your next unmentioned reply, it posts a message in the thread for everyone: "This thread now has multiple people. From now on, mention @bot to send an instruction to this session." In rare cases, such as two people posting at the same moment, that message can appear twice. The thread then needs an @mention for good, even if that person deletes their message. Other bots and Slackbot do not count as people.

An unmentioned reply only continues the thread's open session; it never starts one. It needs something to run: text, an image, or a forwarded message. A reply that opens by mentioning a teammate (@alice can you check this?) is left for them. Edits and replies also sent to the channel are not sent. The bot reads the thread on each unmentioned reply and does not send the reply if Slack cannot return the whole thread.

A reply that is sent gets the same :eyes: reaction as a mentioned follow-up, works the same way, including !model and !reasoning, and does not also run Slack message automations. A reply that is not sent gets no response from the bot, except the message above when the thread shows another person, or the error for a malformed !model or !reasoning flag. It can still reach the session as thread context with your next instruction or match a Slack message automation. A thread stays solo for about 7 days after its session starts.

The thread stays connected to the session for about 7 days. Replying after that, or outside the thread, may start target selection again and create a new session.

A failure on an existing mapping does not create a replacement session. A missing session or a channel-scope refusal produces a closed-thread message. On a follow-up 404, the bot separately checks publication access and marks the mapping closed only if that check confirms denial. An actor-specific 403 does not close the thread for other authorized people; neither does an actor-concealed 404 when publication to the channel remains allowed. The bot also rechecks bindings on mapped follow-ups. A closed mapping can reopen when its original binding matches again and publication is allowed.

Each follow-up includes up to ten recent thread messages posted after the previous prompt and before the new one, encoded as untrusted records with speaker and timestamp. The bot adds an eyes reaction while it works on a follow-up and removes it when the completion reply is posted.

What gets posted back

When a request is accepted, OpenInspect posts a working reply in the thread and adds a View Session button once the web session exists. When the agent finishes, the completion reply contains:

  • The agent's final response, rendered as Markdown (headings, lists, links, tables) and shortened if it is too long for Slack. Broadcast mentions such as @here and @channel are removed.
  • Created artifacts such as pull requests or branches
  • A few key tool actions, such as edits or commands
  • The final status, model, session target, and reasoning effort when available
  • Any personal MCP server warnings for the prompt, with a Your MCP Connections button
  • A View Session button

If the agent created a branch but no pull request, Slack may also show a Create PR button. Detailed event logs stay in the web session.

Generated PNG, JPEG, WebP, or MP4 session artifacts are attached to the completion: at most five files, 10 MiB per file, 25 MiB total. Anything beyond that stays available through View Session. Files merely written into the repository are not uploaded. Media delivery needs the Slack app's files:write scope and a one-time reinstall.

App Home preferences

Open the OpenInspect app in Slack and go to the Home tab.

SettingWhat it controls
Agent harnessWorkspace default, OpenCode, Claude Agent, or Codex for new sessions you start from Slack
ModelThe model used when you start a new session from Slack
Reasoning effortReasoning depth, shown for models that support it
BranchA global branch override for new Slack sessions
Branch by repoA branch override for one repository

The model list comes from the models enabled under Settings › Models and shows only models your agent harness can run. If Slack cannot load that list, Home shows a temporary-unavailability notice and preserves your configured model and reasoning without treating the model as disabled. If compatible enabled models are available but your current model is disabled or incompatible, the picker shows "Choose a model" with nothing selected and a refusal note. If no enabled model can run on the selected harness, Home shows a message instead of a picker, asking you to choose another harness or have an admin enable a compatible model. The "Currently using" summary names your model and agent harness, or marks the model as needing replacement. Branch priority is: repository-specific override, then global override, then the repository default branch. Preferences are per Slack user and affect new sessions only. A !model or !reasoning flag overrides them for the session it starts, or for a single follow-up, without changing them.

Without an App Home model or agent harness, new sessions use the workspace default model and agent harness.

Settings › Integrations › Slack

Administrators manage these workspace-wide Slack settings.

Default model and agent harness

SettingWhat it controls
Default modelThe model for new sessions when the requester has not chosen one in App Home. The list shows only models the selected harness can run.
Agent harnessOpenCode (default), Claude Agent, or Codex for new Slack-started sessions when the requester has not chosen one in App Home

A new session runs on the requester's App Home Agent harness, or on the workspace Agent harness when the requester has not chosen one. Model selection for a new session uses this priority, highest first:

  1. !model and !reasoning flags on the request that starts the session.
  2. The requester's App Home model and reasoning effort.
  3. The Slack Default model.
  4. The deployment default model.

The effective model must be enabled under Settings › Models. If the App Home model, Slack Default model, or deployment/system default used by the request is disabled, the bot refuses to start a new session. It never substitutes a lower-priority default or the first enabled model. Re-enable the model or update the applicable preference or default. An enabled App Home model or leading !model override still works when a lower-priority default is disabled, provided the session's harness can run it. Existing-thread follow-ups without !model keep the session's model, even if it has since been disabled.

If the session's harness cannot run that model, the bot starts no session. Claude Agent runs Anthropic models only, so with Claude Agent as the harness, an OpenAI App Home model or !model openai/gpt-5.4 is refused. After its "Starting work..." message, the bot replies in the thread:

Model "openai/gpt-5.4" cannot run on the Claude Agent harness. Start your request with !model and a model Claude Agent can run, or change your model or agent harness in the Slack app's Home tab.

The settings form lists only models the selected harness can run and rejects saving a harness with a model it cannot run. With Claude Agent or Codex selected, a Default model is required: the form disables Save and shows the message for the selected harness, such as "Choose a default model Codex can run.", until you pick one, and the control plane rejects saving either harness without one. Use system default is not offered for either, because the settings page cannot see the deployment default model, which may be one the harness cannot run.

A harness change applies to new sessions. Each thread keeps the harness its session started on. If the bot cannot read the Slack settings, App Home may show OpenCode as the workspace-harness display fallback without changing the user's saved App Home harness. This does not permit a new launch: new session requests are refused until Slack settings are available.

Slack sessions are unattended, so Claude Agent sessions started from Slack are automated sessions. They use the default Claude account when its Automated authentication allows it, otherwise ANTHROPIC_API_KEY. This applies when a user picks Claude Agent in App Home too, even if the workspace harness is OpenCode. Set Automated authentication to No account (API key) to keep them on the key. See Provider accounts.

Claude Agent loads repository configuration

A Claude Agent session loads the repository's CLAUDE.md and .claude/ settings and hooks, and code the agent runs can read the Anthropic credential. Let Slack channels reach only repositories whose .claude/ configuration you trust, on any branch users can pick in App Home. See Agent harnesses.

A repository's first Claude Agent sessions can start without its prebuilt image if that image is older than the Claude Agent image floor, so they take longer until the image is rebuilt.

Team channel bindings

A team lead or workspace administrator binds channels in the team's Channels tab. Primary marks its main Slack binding; Source adds another channel that routes new interactive sessions to that team. Both determine session ownership, not the repository or an automatic notification destination. A channel belongs to only one team, and a team has at most one primary binding per provider. The bot must already be a member; externally shared Slack Connect channels cannot be bound.

The integration policy unboundChannels defaults to workspace: unbound channels start workspace-owned sessions. reject refuses new interactive requests in unbound channels until a binding is added. Unbound DMs remain workspace-scoped under either policy. Lookup failures stop the request rather than silently changing its ownership.

Classification and pickers use live channel- and actor-scoped catalogs. A bound team's catalog requires membership or workspace-admin access and is filtered by repository grants and eligible environments. Creating a team-owned session checks actual team membership and the selected target's grants. Being in the Slack channel does not make you a member of the OpenInspect team; routing rules do not grant access.

Team enforcement rollout

TEAMS_ENFORCEMENT still defaults to shadow, not on. Do not assume full team-read isolation in that mode. Binding, creation, catalog, Slack follow-up channel, private-access, and publication checks described here do not mean every team read is enforced.

Routing rules

Map keywords to repositories or environments under Routing rules so common requests route without guessing. With frontend → acme/web-app and api → acme/backend:

@OpenInspect fix the frontend nav bug        (routes to acme/web-app)
@OpenInspect add the new api endpoint         (routes to acme/backend)
RuleBehavior
Whole words, case-insensitiveapi matches "the api is down" but not "rapidly"
Channels and DMsRules apply everywhere, which helps in DMs where there is no channel association
Rules beat channel associationAn explicit keyword wins over the channel's default repository
Ambiguity asks, never guessesTwo keywords for two repositories open the picker seeded with those candidates
Stale targets are ignoredA rule whose repository is no longer accessible becomes inert
Active threads are not movedA keyword in a thread reply does not change that session's repository

Session instructions

Set workspace-wide instructions under Session Instructions. They are appended to the first prompt of every new Slack-started session as an ## Additional Instructions section, for standing guidance such as coding standards, preferred tools, or PR conventions. They apply to new sessions only, and are limited to 10,000 characters. Linear has the equivalent Issue Session Instructions.

Agent notifications

Interactive sessions get thread replies only while publication is allowed. Agent notifications are separate: with them enabled, the agent can post an extra message to a channel when you explicitly ask:

When you finish, post a short summary to #eng-updates.
  1. Turn on Enable agent notifications.
  2. Invite the OpenInspect bot to every channel agents may post to. Bot membership is necessary, but does not override publication checks.
  3. Optionally add repository overrides to inherit, force on, or force off notifications per repository.

Changes apply to new sessions. Slack can still reject missing, archived, inaccessible, or rate-limited targets.

Private-session output is refused. A channel bound to a different owning team also refuses output, even if the session is workspace-visible. These live checks cover notifications, managed completions, and generated media. An unbound destination is not automatically a cross-team refusal, so bindings are not an outbound allowlist.

The Mentions policy setting is workspace-wide and controls direct user mentions like <@U123>:

PolicyResult
AllowDirect user mentions are posted to Slack
EscapeMentions are rewritten as literal text like @U123; Slack does not notify the user
StripMentions are removed

Broadcast tokens (@channel, @here, @everyone, and subteam mentions) are always stripped from agent notifications.

Channel message triggers

An automation can start a session when someone posts a matching message in a watched channel, with no mention. Those runs take the message text only (attachments and forwarded bodies are not read), and authorized thread replies can continue the same session for 7 days. Runs retain the automation's saved owning team, not the channel's interactive routing choice. See Slack message triggers for authorization, publication, conditions, and setup.

Admin and safety notes

  • Slack bot tokens stay server-side and are never sent to sandboxes.
  • Slack requests are verified before OpenInspect acts on them.
  • The source-control installation is the outer repository boundary, not a per-Slack-user GitHub permission list. Team bindings, memberships, and repository grants further constrain team work.
  • Invite the bot only into trusted channels. Identity linking does not itself grant team membership.
  • The first time someone messages the bot, OpenInspect links them to the account with their Slack profile email. The bot won't act for a new user whose email it can't read, which is why the app needs users:read.email. External users in Slack Connect channels often have hidden emails, so new ones can't start using the bot yet; people the bot already knows keep working. If no account has that email, a new one is created only when the email passes the workspace's sign-in rules.
  • Bot messages are ignored, so the bot does not respond to itself.
  • Notification text is sanitized and shortened to fit Slack block limits; extremely large raw inputs are rejected.

Troubleshooting

Next steps

On this page