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

# Slack Integration

> Connect Slack to Capy to create coding tasks directly from messages, sync conversation threads, and give agents full context from your workspace.

## Overview

Connect Slack to create tasks directly from messages, sync conversation threads, and let agents read and search your Slack workspace for context.

## Installing the Slack app

<Steps>
  <Step title="Open Slack settings">
    Go to [Settings → Connections →
    Slack](https://capy.ai/settings/org/connections/slack). You need to be an
    org admin.
  </Step>

  <Step title="Install the app">
    Click **Install** and authorize Capy in your Slack workspace. This connects
    the workspace for your entire organization.
  </Step>

  <Step title="Set a default project">
    Choose a default project for Slack-originated tasks. This is used for DMs
    and channels without an explicit mapping.
  </Step>
</Steps>

## Creating tasks from Slack

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

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

## Thread controls

Use thread controls to manage what Capy sees and when it responds inside a Slack thread.

### Aside messages

Prefix a message with `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.
</Tip>

### Mute and unmute

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

* Type `mute` or `@Capy mute` in the thread to mute it
* Type `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 thread to stop Capy and close the session.

* Type `archive` or `@Capy archive` in the thread
* Capy stops any running work and archives the session
* The thread is closed — start a new `@Capy` mention to create a fresh session

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

## Channel mappings

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

1. Go to [Settings → Connections → Slack](https://capy.ai/settings/org/connections/slack)
2. Scroll to **Channel mappings**
3. Select a channel and a project, then click **Save**

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

## Default branch

Set a **default branch** in the Slack settings to control which branch Capy uses as the base for tasks started from Slack. If not set, the project's default branch is used.

## Message verbosity

Control how many messages Capy posts in Slack threads.

* **All messages** (default) — Capy posts every response as it works
* **Final message only** — Capy only posts the final response when the task completes

Set this in [Settings → Connections → Slack](https://capy.ai/settings/org/connections/slack) under **Message verbosity**. Individual threads can override this with the `verbose` flag.

## Message flags

Control task behavior by adding flags to your `@Capy` message. Flags are stripped from the prompt before processing.

### Bang flags

Prefix a flag with `!` to toggle a behavior. Bang flags can appear anywhere in the message.

| Flag    | Description                                            |
| ------- | ------------------------------------------------------ |
| `!fast` | Use fast model variants for quicker, cheaper responses |

Reasoning levels should be configured with `reasoning=...`. The shorthand bang flags `!off`, `!low`, `!medium`, `!high`, and `!xhigh` are still supported for backcompat and quick use.

```text theme={null}
@Capy !fast fix the typo in README.md
@Capy reasoning=high refactor the auth middleware to use dependency injection
@Capy !xhigh audit the query planner changes
```

### Directives

Use `key=value` pairs to configure task settings. Directives can appear anywhere in the message.

| Flag        | Values                                  | Description                                             |
| ----------- | --------------------------------------- | ------------------------------------------------------- |
| `repo`      | `owner/name`                            | Target a specific repository                            |
| `branch`    | branch name                             | Use a specific base branch                              |
| `verbose`   | `true` / `false`                        | Override the org-wide verbosity setting for this thread |
| `model`     | model name                              | Use a specific model (e.g. `opus`, `sonnet`, `haiku`)   |
| `reasoning` | `off`, `low`, `medium`, `high`, `xhigh` | Set reasoning effort                                    |
| `channel`   | `#channel` / name                       | Start the Capy thread in another Slack channel          |

```text theme={null}
@Capy repo=acme/backend branch=staging fix the deploy script
@Capy model=opus reasoning=xhigh investigate the production incident
@Capy channel=at-capy investigate this bug report
```

`channel` only applies to new Slack starts. Capy posts a new thread in the target channel with source attribution.

#### Verbosity

The `verbose` flag controls how many messages Capy posts in the Slack thread:

* `verbose=true` (or `on`, `yes`, `all`) — post every assistant message (default)
* `verbose=false` (or `off`, `no`) — only post the final response

You can set the default for your entire workspace in [Settings → Connections → Slack](https://capy.ai/settings/org/connections/slack) under **Message verbosity**. The per-message `verbose` flag overrides the org-wide setting.

#### Model aliases

The `model` flag accepts short aliases:

| Alias    | Model             |
| -------- | ----------------- |
| `opus`   | Claude Opus 4.7   |
| `sonnet` | Claude Sonnet 4.6 |
| `haiku`  | Claude Haiku 4.5  |
| `gpt`    | GPT 5.5           |
| `codex`  | GPT 5.3 Codex     |
| `gemini` | Gemini 3.1 Pro    |
| `grok`   | Grok 4.1 Fast     |
| `kimi`   | Kimi K2.5         |
| `qwen`   | Qwen3 Coder       |
| `glm`    | GLM 5.1           |

Full model IDs also work: `model=claude-opus-4-7`.

### Combining flags

Flags can be mixed freely:

```text theme={null}
@Capy !fast fix the auth redirect loop
@Capy model=opus reasoning=high repo=acme/api refactor the middleware
@Capy !fast verbose=false branch=staging run a quick code review
@Capy repo=acme/api branch=feature-x reasoning=xhigh add rate limiting to the /users endpoint
```

## Personal connection

Each team member can link their own Slack account for richer functionality. This lets Capy:

* Search messages on your behalf
* Read private channels you're a member of
* Read your DMs (if you grant permission)

To link your account:

1. Go to [Settings → Connections → Slack](https://capy.ai/settings/org/connections/slack)
2. Under **Personal connection**, click **Link account**
3. Authorize Capy with your Slack user token

### Permission levels

| Permission               | What it enables                                      | Default   |
| ------------------------ | ---------------------------------------------------- | --------- |
| Search & public channels | Read and search messages in public channels          | Always on |
| Private channels         | Read messages in private channels you're a member of | Off       |
| Direct messages          | Read your DMs and group DMs                          | Off       |

You can toggle these permissions anytime. Changes require reconnecting to Slack.

If an agent needs a permission you haven't granted, it will post a prompt in the Slack thread asking you to upgrade. You can disable these prompts in the settings.

## What agents can do with Slack

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

* **Read messages** from any channel or thread (respects your permission level)
* **Search messages** across the workspace
* **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 task. They can also send messages to other channels when needed.

## Permissions

| Permission                      | Purpose                      |
| ------------------------------- | ---------------------------- |
| Chat:write                      | Post messages and replies    |
| Channels:read                   | List and read channels       |
| Reactions:read, Reactions:write | Sync and add emoji reactions |
| Files:write                     | Upload file attachments      |
| Users:read                      | Resolve display names        |

## Troubleshooting

<AccordionGroup>
  <Accordion title="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 →
    Connections → Slack.
  </Accordion>

  <Accordion title="Tasks go to the wrong project">
    Check your channel mappings. If the channel isn't mapped, tasks use the
    default project. Set one in Settings → Connections → Slack.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Agent can't search or read private channels">
    The user who started the task needs to link their personal Slack account and
    enable private channel access. Go to Settings → Connections → Slack →
    Personal connection.
  </Accordion>

  <Accordion title="Permission upgrade prompts are annoying">
    Disable them in Settings → Connections → Slack → Permissions → Upgrade
    notifications.
  </Accordion>
</AccordionGroup>