> ## Documentation Index
> Fetch the complete documentation index at: https://atcyrus.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack

> How Cyrus integrates with Slack — @mention triggers, thread context, and MCP tools

Cyrus connects to your Slack workspace so you can trigger agent sessions directly from Slack. Mention the Cyrus bot in any channel, and it will start working — then respond in a thread.

***

## Setup

Connect Slack from your [Integrations settings](https://app.atcyrus.com/settings/integrations).

<Steps>
  <Step title="Connect your workspace">
    Click **Connect Slack** in the Slack integration card. You'll be redirected to Slack to authorize the Cyrus bot for your workspace.
  </Step>

  <Step title="Grant permissions">
    Approve the requested bot permissions. These allow Cyrus to receive `@mentions`, read channel context, and reply with messages.
  </Step>

  <Step title="Start using it">
    Once connected, mention the Cyrus bot in any channel it's been added to. Cyrus will pick up the message and start a session.
  </Step>
</Steps>

<Note>
  After connecting, you may need to **invite the Cyrus bot to specific channels** before it can receive mentions there. Use `/invite @Cyrus` in any channel where you want to interact with the agent.
</Note>

***

## @mention triggers

Mention the Cyrus bot in a Slack channel or thread to start a session. Cyrus will:

1. Receive the mention event via webhook
2. Validate your team's subscription and plan
3. Start an agent session with the message as context
4. Reply in a thread on the original message

### Thread context

When you mention Cyrus in a **thread**, the agent session includes the full thread history as context. This means:

* Other participants' messages are visible to Cyrus
* Messages from other bots (Sentry alerts, CI notifications, GitHub updates) are preserved in context
* Follow-up mentions in the same thread continue the same session, so Cyrus remembers prior conversation

This makes Slack threads a natural place for multi-turn conversations with Cyrus — ask a question, get an answer, then follow up without losing context.

***

## When to use Slack vs Linear

Slack sessions and Linear sessions serve different purposes:

|                 | Slack Sessions                                                                    | Linear Sessions                                                |
| --------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| **Environment** | Runs in a temporary empty directory — no repository checkout                      | Runs in an isolated Git worktree with full repo access         |
| **Best for**    | Quick questions, research, brainstorming, searching docs, Slack workspace queries | Code changes, bug fixes, feature implementation, pull requests |
| **Output**      | Conversational replies in Slack threads                                           | Commits, branches, and pull requests on GitHub                 |

<Info>
  Slack sessions do **not** create Git worktrees or have access to your codebase. For any work that involves reading or modifying code, create a Linear issue and assign it to Cyrus instead.
</Info>

***

## Slack MCP tools

When the Slack integration is connected, Cyrus automatically gains access to Slack MCP tools during agent sessions. These tools let Cyrus:

* **Read channels** — browse message history in channels the bot has access to
* **Search messages** — find relevant messages and files across the workspace
* **Look up users** — resolve user information and email addresses

These tools are available in both Slack-triggered sessions and Linear-triggered sessions, so Cyrus can reference Slack conversations regardless of where the session started.

***

## How it works

Under the hood, the integration uses Slack's Events API and OAuth 2.0:

| Component      | Description                                                                 |
| -------------- | --------------------------------------------------------------------------- |
| **OAuth**      | Bot token is securely stored and encrypted at rest                          |
| **Webhooks**   | `app_mention` events are verified using HMAC-SHA256 signature verification  |
| **Forwarding** | Verified events are routed to your Cyrus instance for processing            |
| **Responses**  | Cyrus replies using Slack's native `mrkdwn` formatting for proper rendering |

Webhook events are deduplicated automatically — if Slack retries a delivery, Cyrus won't process the same event twice.

***

## Disconnecting

To disconnect Slack:

1. Go to [Integrations settings](https://app.atcyrus.com/settings/integrations)
2. Click the dropdown on the Slack integration card
3. Select **Disconnect Slack**

This removes the bot token and stops all Slack event processing. You can reconnect at any time by going through the setup flow again.

***

## Troubleshooting

**Cyrus doesn't respond to my mention**

* Make sure the Cyrus bot has been invited to the channel (use `/invite @Cyrus`)
* Verify the Slack integration shows as connected in [Integrations settings](https://app.atcyrus.com/settings/integrations)
* Confirm your team has an active subscription

**Messages aren't formatted correctly**

* Cyrus uses Slack's native `mrkdwn` syntax. If formatting looks off, it may be a rendering issue in an older Slack client — try updating Slack

**Bot token issues after reconnecting**

* If Cyrus stops responding after reconnecting, try disconnecting and connecting again from the Integrations settings page
* The bot token is synced to your infrastructure automatically during connection

***

<Card title="Cyrus Community" href="https://discord.com/invite/prrtADHYTt" img="https://mintcdn.com/ceedaraiinc/75NMRUlNh03-gDHX/images/cyrus-f1.png?fit=max&auto=format&n=75NMRUlNh03-gDHX&q=85&s=947d2de0018937ce613572349bc91f06" width="1120" height="928" data-path="images/cyrus-f1.png">
  Get support on Discord
</Card>