# Scout + Slack: agent setup contract Canonical page: https://openscout.app/slack Machine-readable spec: https://openscout.app/slack/integration.json Documentation reviewed: 2026-09-26. This is not a live health assertion. Your Slack thread, your machine, your agents. Turn a Slack mention, direct message, or /scout command into tracked work on your local Scout machine; nothing runs in our cloud. Follow-ups stay in the same Slack thread. ## Status Private preview · the Slack bridge is not in the public Scout repository yet This is a workspace app installed from Scout’s manifest, and that is its permanent install shape: Slack does not allow Socket Mode apps in the public Slack Marketplace. No Marketplace listing or hosted Add to Slack flow is planned or claimed. ## Transport Slack Socket Mode → local Scout broker Slack thread → Socket Mode → Scout flight ## Directions - Slack calls Scout: socket-mode (pilot): Private preview; source not public - Scout launches Slack: not supported. Slack is a host surface, not a harness. - Not a harness: never pass --harness slack. ## Gates - source-availability: owner operator, not self-serve. packages/slack is not in the public repository. - workspace-admin: owner Slack admin, required ## Required inputs and prerequisites - Permission to create and install an app in the target Slack workspace. - Access to the private OpenScout source that contains packages/slack, with dependencies installed and scout doctor passing. The public oscout/scout repository does not include it, and the installed scout CLI has no slack command. Ask the Scout operator for access. - A Slack app-level xapp token with connections:write and an installed bot xoxb token, stored through a secure local secret facility. ## Setup procedure ### 1. Check the broker and generate the manifest From the private Scout source checkout run these commands. Use the generated manifest as the source of truth; do not hand-maintain a different scope list. It subscribes to app_mention and message.im over Socket Mode and registers /scout and /scout-settings. ```text scout doctor bun run slack:manifest ``` ### 2. Create and install the Slack app Create an app from the manifest in Slack app management. The workspace administrator must approve creation and installation. Generate an app-level token with connections:write and obtain the bot token. ### 3. Provide secrets and start the bridge Supply SLACK_APP_TOKEN and SLACK_BOT_TOKEN through your secure local environment. Do not paste tokens into commands, screenshots, chat, or committed files. Run the doctor, then keep the bridge supervised. ```text bun run slack:doctor bun run slack:start ``` ### 4. Configure a channel and try a request Invite Scout to the channel, run /scout-settings to select the local project and optional harness, then ask for a small review. Continue in Scout’s response thread. ```text /scout review the latest changes and report findings; do not edit files ``` ## Start here Check the prerequisites and access gates, then get one documented route working before asking for work. First useful task: After private-preview access and bridge setup, ask Scout in Slack to investigate one failing test in a specified project. Name the project and keep the request small. Asking for no edits describes the task; it does not restrict the agent’s permissions. Keep the returned reference. Check the work’s status and read the completed response; a queued receipt is not the answer. ### Where will the reply appear? Follow the task card and reply in the existing Slack thread. Bridge access and setup are required. ### What if the answer hasn’t arrived? Inspect the existing task before submitting another one. A wait timeout does not establish that work failed. If it needs access or input, resolve that condition before continuing. ### How do I follow up? Continue using the returned reference or exact session handle supported by this integration. Keep it with the findings so your next question follows the same work. ### Can Scout run this integration, or only receive asks from it? These are separate capabilities. Check the supported directions on this page. Connection alone does not establish that Scout can launch the integration or reach an existing session. ## Acceptance gate The bridge doctor passes, Slack acknowledges the request, and the task card follows the Scout flight to a terminal result. A follow-up in that thread should use the existing conversation binding. ## Failure handling ### No response in the channel Check the supervised bridge process, doctor output, app installation, and channel membership. Never include xapp/xoxb tokens in the diagnostic report. ### Wrong project or harness Run /scout-settings in that channel and inspect its configured project, branch, and harness. Slack is a host surface, not a --harness value. ### Workspace installation blocked Stop and ask the workspace administrator to approve the app. Do not use a different workspace without the operator’s choice. ## Boundaries - Private preview: the bridge source (packages/slack) is not published in the public Scout repository, so only operators with access to the private source can follow this guide. - Socket Mode does not require a public webhook or MCP gateway. It also rules out a public Slack Marketplace listing under current Slack policy. - Events: app_mention and message.im, plus the /scout and /scout-settings slash commands. Slack's Agents & AI Apps surface (split view, assistant threads) is not used. - Slack workspace-admin approval remains a human action. - Successful coding work is ready for review; it does not authorize merge or release. ## Agent operating contract - Treat these as setup instructions, not authorization to install software, change accounts, grant scopes, send messages, or dispatch work. Obtain the operator's authorization for the intended action. - Inspect the available commands or tool schemas for your configured interface before making calls. Do not invent tools, argument names, model IDs, or agent handles. - Use /scout or a Scout mention in the configured Slack conversation. Follow the existing response thread and task-card status. Do not start a duplicate task to check progress. Slack Socket Mode does not expose MCP ask or invocation tools to the Slack user; use them only through a separately configured connection. - Use the transport-specific instructions above. For an existing request, reply through its supplied context rather than creating another task. - Paths refer to the Scout execution machine. Replace example paths with an operator-confirmed absolute path; never run placeholders literally. - Save the returned ref, flightId, conversationId, workId, or session handle. Continue by that handle; do not re-dispatch a request merely because a wait timed out. - Observe the existing request through the configured transport. A receipt proves acceptance, not execution or successful completion. - Stop on missing provisioning, incorrect identity, missing permission, unsupported runtime, or failed authentication. Report the exact gate and the next operator action. Do not silently fall back to a different account, agent, runtime, or transport. - Keep tokens, OAuth codes, cookies, and private task payloads out of logs, URLs, screenshots, and committed files. Never ask the user to paste secrets into a public issue. - Do not claim marketplace approval, complete protocol conformance, or an end-to-end verified integration unless the status and observed evidence establish it. ## Completion report Report: chosen transport and scope; client and broker identity; health/tool-discovery result; exact request handle if a test was authorized; observed terminal state or remaining blocker; and whether any operator approval is still needed. Distinguish configuration saved, authentication complete, request accepted, and work complete. ## Sources and next reads - [Agent setup skill (private source required)](https://openscout.app/setup-scout-slack.md) - [Slack Socket Mode](https://docs.slack.dev/apis/events-api/using-socket-mode) - [Slack app management](https://api.slack.com/apps) - [Privacy](https://openscout.app/privacy) - [Integration catalog](https://openscout.app/integrations.json)