Slack

Overview⁠

Connect Slack to start Capy threads directly from messages, sync conversations, and let agents read and search your Slack workspace for context.

For an overview of working with Capy from Slack, see Capy for Slack.

Installing the Slack app⁠

The Connect Slack button that adds Capy to Slack is in Capy's settings, so you sign in to Capy first. Any member of your Capy organization can install and authorize Capy from Slack settings. The connection applies to your entire organization. The default project handles DMs and channels without an explicit mapping.

  1. Sign up for Capy

    Go to capy.ai and sign up, or sign in if you already have an account.

  2. Name your organization

    Capy creates an organization for you during setup. Enter a Workspace name and click Continue. If a teammate invited you, accept the invitation to join their organization instead.

  3. Connect GitHub

    Click Connect GitHub, install the Capy GitHub App, and choose the repositories Capy can access. See GitHub.

  4. Connect Slack

    Open Settings → Integrations → Slack and click Connect Slack. Slack opens its install page for your workspace. Review the permissions and click Allow.

  5. Link your Slack account

    On the same page, click Link account next to Personal Slack account, so the threads you start from Slack belong to you. Capy also links you automatically when your Slack email matches your Capy email, and sends you a link prompt when you mention @Capy in Slack.

  6. Optional: read Slack as you

    Next to Read Slack as you, click Connect and approve the read-only permissions in Slack. Capy can then read a conversation the Capy app isn't in, after you approve it in the thread. See Permissions.

To start, mention @Capy in a channel. If Capy doesn't respond, type /invite @Capy in that channel first.

Slack integration settings with a connected workspace and personal account linkSlack integration settings with a connected workspace and personal account link
Connect a workspace and link your Slack identity.

Note

Capy's replies and code changes are AI-generated and can be wrong. Check its work before you merge a pull request or act on an answer.

A paid Slack plan is required to access AI assistant features, such as Capy in Slack's agent panel. Mentions, direct messages, and the Ask with Capy shortcut work on every Slack plan.

Starting threads from Slack⁠

Mention @Capy in any channel where the app is installed. Capy starts a thread from your message and responds in a Slack thread. You can continue the conversation there - messages are synced to the Capy thread.

You can also share images and files in the message. Capy will pick them up as context for the thread.

Thread controls⁠

Use thread controls to manage what Capy sees and when it responds inside a Slack thread. Type help, !help, or @Capy help to see every shortcut and command in a message only you can see.

Aside messages⁠

Prefix a message with aside (or its alias !aside) to exclude it from Capy's processing entirely.

  • Capy won't see the message
  • Capy won't respond to it
  • It won't appear in the agent's context when Capy reads thread history

This works with aside ... and @Capy aside .... The check is case-insensitive, and aside must be at the start of the message.

Tip

Use aside when you want to talk with teammates in a Capy thread without the agent picking those messages up.

Mute and unmute⁠

Mute a thread to stop Capy from responding to regular thread replies.

  • Type mute, !mute, or @Capy mute in the thread to mute it
  • Type unmute, !unmute, or @Capy unmute to turn replies back on
  • When muted, Capy ignores regular thread replies
  • Direct @Capy mentions still go through
  • DMs still work

Capy confirms the change with an ephemeral message visible only to you:

  • Thread muted - Capy will ignore messages here unless directly mentioned with @Capy.
  • Thread unmuted - Capy will respond to messages in this thread again.

If the thread is already in the requested state, Capy does nothing. Mute state is stored per thread.

Archive⁠

Archive a Slack thread to stop Capy and close the Capy thread.

  • Type archive, !archive, or @Capy archive in the thread
  • Capy stops any running work and archives the Capy thread
  • Later messages and direct mentions in the archived Slack thread are ignored and do not unarchive it
  • Type unarchive, !unarchive, or @Capy unarchive to explicitly reopen it
  • To keep the archived thread closed, start a new @Capy mention outside the old Slack thread

Capy confirms with: Thread archived - Capy has stopped and this session is closed.

When explicitly reopened, Capy confirms with: Thread unarchived - Capy will respond to messages here again.

Stop⁠

Stop the current run without archiving the thread.

  • Type stop, !stop, or @Capy stop in the thread
  • Capy stops the current run and keeps the thread active
  • Send another message in the thread when you want Capy to start again

Capy confirms with Capy stopped the current run. If no run is active, it replies with Capy is not currently running.

Type unlink, !unlink, or @Capy unlink as the whole reply to pause Slack sync for the current thread. The Capy thread keeps running on web, and Slack receives a pause notice with an Open in Capy link. Resume sync from the thread's Slack control on web.

Start a separate web thread⁠

Add !web anywhere in a message to start a separate thread on web without linking it to Slack. In an existing Capy Slack thread, the new thread starts with the source transcript while the original thread and its Slack sync remain unchanged. In an ordinary Slack conversation, mention @Capy; Capy reads a bounded snapshot as context, then leaves that conversation unlinked. Muted and archived Capy threads also require an explicit @Capy mention.

Capy posts a Started on web card with an Open in Capy link. Continue the new thread on web: later Slack replies never enter it, and its replies, status, pull-request cards, and completion stay off Slack. You can link it to a new Slack thread later from its web menu, but it does not reattach to the source conversation.

Channel mappings⁠

Map specific Slack channels to Capy projects so threads started from those channels are automatically assigned to the right project.

Channel mappings in Slack settings saves each channel's project.

Channels without a mapping fall back to the default project. DMs also use the default project.

Capy also offers to set defaults for you. When neither the channel nor the workspace has a default and Capy has to ask you to pick a project, an admin's pick is followed by a one-time offer: make that project the default everywhere, only for this channel, or don't ask again. Every choice is reversible on the Slack settings page.

Message directives⁠

Configure a thread with key=value directives anywhere in your @Capy message. Directives are stripped from the prompt before the agent sees it, and quoted values are supported.

DirectiveValuesDescription
projectproject name or IDStart the thread in a specific Capy project
folderfolder nameFile the new thread into a dashboard folder
channel#channel / nameStart the Capy thread in another Slack channel
titleany textSet the thread title
modelmodel ID or shortcutRun the thread on a specific model
reasoningoff, minimal, low through maxSet the model's reasoning effort
machinesmall, medium, large, ultra, hyperSet the machine size for a new thread or fork
Text
@Capy project="Payments platform" fix the deploy script
@Capy model=opus reasoning=high investigate the production incident
@Capy channel=at-capy title="Bug report triage" investigate this
@Capy machine=hyper !fast run the full test suite
@Capy !web investigate this on web

To talk to a Captain from Slack, use captain=<name>; see steer a Captain from Slack.

project, folder, title, and machine apply when Capy creates a thread, including channel=, !new, and !web starts. A machine= directive on a normal continuation is refused because an existing thread's machine cannot be resized. Project names match case-insensitively with a safe fuzzy match; when the match is uncertain, Capy asks you to pick instead of guessing.

model= accepts a full catalog ID (openai/gpt-5.6-sol), a model name without its route prefix (gpt-5.6-terra), or a shortcut phrase: fable, opus, sonnet, haiku, sol, terra, luna, gemini, grok, kimi, qwen, glm. A phrase served by more than one connected route (Capy-billed vs a subscription) asks you to pick a route once for the org; a phrase that matches nothing gets an error reply, never a silent guess. A reasoning effort or serving mode can ride on the phrase as trailing words: model=luna-xhigh-fast means the same as model=luna !xhigh !fast.

Use whitespace-delimited bang flags for thread, model, and delivery controls:

FlagEffect
!newFork into a separate Slack thread in the current conversation
!webStart a separate web thread without Slack sync
!fastEnable Fast mode and clear Pro mode
!proEnable Pro mode, clear Fast mode, and clear inherited reasoning
!standardClear Fast and Pro while preserving the model and reasoning
!off, !minimal, !low, !medium, !high, !xhigh, !maxSet reasoning effort
!queueQueue the prompt behind the active run
!steerSteer the active run without interrupting it

Capy refuses conflicting mode flags and an explicit Pro-plus-reasoning combination. A mode-only reply in an existing thread updates later replies and confirms the new selection once.

!new and !web also work in an existing active Capy thread without a mention. !new creates a new Slack thread, while !web creates a web-origin thread with the source conversation as context. !web cannot be combined with !new or channel=.

Repository and branch instructions are ordinary task context, not directives. Write them naturally - "use the backend repository on the staging branch" - and the agent handles them inside the selected project.

Personal connection⁠

Team members can link their Slack identity to their Capy account from Settings → Integrations → Slack. Linking attributes your Slack messages to your Capy user - threads you start from Slack belong to you on the dashboard, and replies carry your name into the agent's context. Unlinked teammates can still talk to Capy in threads; their messages just aren't tied to a Capy account.

Pull request cards⁠

When a Slack-started thread opens or takes over a pull request, Capy posts a card for it into the Slack thread and keeps it current from GitHub state - status, checks, branches, and diff totals update in place, so the card never goes stale as work continues.

  • One card per pull request per thread. A thread working across five PRs gets five cards, each updating independently.
  • Cards carry Open in Capy and View on GitHub actions.
  • Merging or closing a PR posts one compact follow-up sentence, so you're notified even after the card has scrolled away. Everything else - checks progressing, drafts flipping ready, reopens - only updates the card.
  • A muted thread gets no new cards, but its existing cards keep updating: muting silences conversation, not a status object you can already see.

Pull request links inside Capy's messages open the Capy pull request view by default. Slack settings can change the destination to GitHub. Each thread keeps the preference it started with, so old messages keep their original destinations.

What agents can do with Slack⁠

When a thread is started from Slack, agents have access to these capabilities:

  • Read messages from public channels and private channels where the Capy bot is a member
  • Send messages to channels or threads, with optional file attachments
  • React to messages with emoji
  • List channels to find the right conversation

Agents always respond in the Slack thread that started the Capy thread. They can also send messages to other channels when needed.

Permissions⁠

Capy asks Slack for these bot permissions when your organization connects a workspace. With them, Capy reads only channels it is a member of and direct messages people send it.

PermissionWhat Capy uses it for
app_mentions:readStart a Capy thread when someone mentions @Capy
assistant:writeShow that Capy is working in the thread while the agent runs
channels:historyFollow replies in Capy threads, and read a thread or channel a person asks Capy to use as context, in public channels Capy is a member of
channels:joinJoin a public channel when a person starts Capy there or asks it to post there; Capy never joins channels in bulk or on install
channels:readList public channels for channel mappings and find a channel by name
chat:writePost replies, progress, and pull request cards, and update cards in place
chat:write.customizeShow which Captain or Capy user a message comes from
chat:write.publicPost results to a public channel a person names, without inviting Capy first
commandsRun the Ask with Capy message shortcut, which starts a thread from any message
emoji:readReact with your workspace's custom emoji
files:readUse images and files attached to a request as context
files:writeUpload screenshots, logs, and reports the agent produces to the thread
groups:historySame as channels:history, in private channels Capy was invited to
groups:readSame as channels:read, for private channels Capy is a member of
im:historyRead direct messages people send to Capy
im:readRecognize direct message conversations with Capy
im:writeOpen a direct message to send a person something only they should see
links:readNotice Capy thread and pull request links shared in Slack
links:writeUnfurl those links into previews
mpim:readRequested at install because Slack's member_joined_channel event lists it; Capy does not read group direct message contents with it
reactions:readStart an automation when someone adds a chosen reaction to a message
reactions:writeAcknowledge a request with a reaction, and react when asked
team:readShow your workspace's name and icon in Capy settings
users:readShow people's names instead of user IDs in thread context
users:read.emailMatch a Slack user to their Capy account by email, so threads they start belong to them

Turning on Slack canvases in Slack settings asks for two more bot permissions. Capy works without them.

PermissionWhat Capy uses it for
canvases:readRead a canvas a person points Capy at
canvases:writeCreate a canvas or edit one when asked, for example to write a report or checklist

Read Slack as you is a personal setting on the same page. When a person turns it on, Slack asks them for these read-only user permissions, so Capy can read a conversation the Capy app isn't in after that person approves it. Capy never posts as them.

PermissionWhat Capy uses it for
channels:read, groups:read, im:read, mpim:readFind the public channel, private channel, direct message, or group direct message the person asked about
channels:history, groups:history, im:history, mpim:historyRead that conversation as the person

Data and privacy⁠

The Privacy Policy describes how Capy handles Slack data, and Subprocessors lists the service providers that process it. To remove Capy's access, choose Disconnect in the workspace menu in Slack settings, or remove the app from your Slack workspace.

Troubleshooting⁠

Capy doesn't respond to mentions
Make sure the Capy app is installed in the channel. Type /invite @Capy to add it. Also verify the Slack workspace is connected in Settings → Integrations → Slack.
Threads go to the wrong project
Check your channel mappings. If the channel isn't mapped, threads use the default project. Set one in Settings → Integrations → Slack.
Capy ignores messages in a thread
The thread may be muted. Type unmute or @Capy unmute in the thread to re-enable normal replies. Direct @Capy mentions still work while a thread is muted.
Capy didn't react to an `aside` message
That's expected. Messages starting with aside are excluded from Capy's processing and do not appear in the thread context the agent reads later.
Agent can't read a private channel
The Capy bot reads private channels only where it is a member. Invite it with /invite @Capy in that channel.
Open in Capy