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

# Slack Integration

> Connect Slack so channel messages route to Aether projects as tasks and updates post back to the thread.

Connect Slack to start tasks from chat. You create **routes** that map a Slack channel to an Aether [project](/guides/projects); a channel can route to several projects. A message in a routed channel opens a task, and the agent's updates post back to that message's thread. Slack can also deliver your task notifications as direct messages.

<Note>
  Slack is **config-gated**: it is only available when the deployment has Slack OAuth credentials configured. If you do not see Slack in **Settings → Connections** or the CLI commands return errors, the deployment has not enabled it. See [Integrations](/guides/integrations).
</Note>

## Prerequisites

A route targets an Aether project that has a **linked GitHub repo** — that is where the agent's work lands. Connect GitHub and import a repo first; see [GitHub integration](/guides/github-integration).

## Connecting Slack

<Tabs>
  <Tab title="Web">
    Go to **Settings → Connections → Slack** and click **Connect** to authorize Aether for your Slack workspace.
  </Tab>

  <Tab title="CLI">
    ```bash theme={"dark"}
    aether slack connect
    ```

    This opens your browser to authorize Aether, then polls until the connection completes. On success it prints the connected workspace.
  </Tab>
</Tabs>

Check the connection any time:

```bash theme={"dark"}
aether slack status
```

Status reports the connected workspace and team ID, plus whether direct-message notifications are wired up for your Slack user.

### Reconnecting for new permissions

The `/aether` slash command and the **Send to Aether** message shortcut need Slack's `commands` permission, which a workspace grants only when it connects. A workspace connected before Aether requested that permission must reconnect once: **Settings → Connections → Slack** shows a **Reconnect Slack** prompt until it does. Click **Reconnect Slack** and approve the same workspace — your routes and settings stay in place, and the prompt disappears once the new permission is stored.

## Listing Channels

Routes are keyed by channel, so look them up first:

```bash theme={"dark"}
aether slack channels
```

This lists channels the Aether app can see, with their IDs and whether each is private.

## Creating a Route

A route maps a Slack channel to an Aether project. A channel can have routes to several projects: create one route per project. A channel routes to a given project at most once — creating the same channel and project again fails with an error naming both.

```bash theme={"dark"}
# Pick a channel interactively, route to the selected Aether project
aether slack routes create

# Specify the channel explicitly and target a project
aether slack routes create \
  --channel-id <channel-id> \
  --channel-name <channel-name> \
  --aether-project a1b2c3d4
```

`--channel-id` and `--channel-name` must be provided together; omit both to pick a channel interactively. Add `--private` when supplying a private channel by ID. `--aether-project` accepts a project ID or short prefix and defaults to your [selected project](/guides/projects); it must be a project with a linked repo. New routes are enabled by default — pass `--enabled false` to create one paused.

In the web app, add routes under **Settings → Connections → Slack → Channel routes**. The channel picker lists every channel, including ones already routed to other projects.

## Starting Tasks from Slack

In a routed channel, post a message mentioning **@Aether** to start a task. Aether replies in that message's thread and posts its progress, result, project, task link, and PR link there as the task runs. Reply **`cancel`**, **`stop`**, or **`abort`** in the thread to cancel the task.

If your Slack user's direct messages are wired up (shown by `aether slack status`), Aether can also deliver your [task notifications](/concepts/automation) as Slack DMs.

### Channels Routed to Several Projects

When a channel has more than one active route, name the project in your message to start the task there directly: its project name, or its repo as `owner/name` or just the repo name. A message that names none of the channel's projects, or more than one, gets **Which project?** in the mention's thread instead, with one button per active route, labeled by project name and in project-name order (more than five projects become a single dropdown). Paused routes are not offered.

Anyone in the channel can pick. The task starts in the chosen project as the request of the person who mentioned @Aether, not the person who clicked, and the **Which project?** message becomes the task card: it updates in place with the task's progress, and the agent's replies continue in the same thread.

### Unrouted or Paused Channels

A mention in a channel with no routes, or whose routes are all paused, starts no task. Aether answers with a private note that only the person who mentioned it can see — "No projects are linked to #channel." or "Aether is paused in this channel." — with a link to the Slack settings page, where you can add a route or resume one.

### The `/aether` command

Type `/aether` in a routed channel, optionally followed by your request:

```text theme={"dark"}
/aether fix the flaky login test
```

A form opens with a **Project** list of the channel's enabled projects and a **Request** field holding what you typed after `/aether` (empty if you typed nothing). The project is preselected to the one your most recent Slack task in this channel ran in, or the first project by name. **Start a task** is chosen at the top of the form; choose **Review a pull request** there to [review a pull request](#reviewing-a-pull-request) instead. Submit the form and it closes; Aether posts the task's card in the channel. Reply in the card's thread to follow up, or reply **`cancel`**, **`stop`**, or **`abort`** there to cancel the task.

* **A request is required.** Submitting an empty request shows an error in the form and starts nothing.
* **No projects here.** In a channel with no linked or enabled projects, the form explains why and links to Slack settings; there is nothing to submit.
* **Invite the app first.** Aether can only post the card in a channel its app is a member of. If it is not, Aether sends you a direct message asking you to invite it to the channel, and starts nothing.
* **Attribution.** The task is yours if your Slack identity is linked to Aether; otherwise Aether starts it as the workspace's default user and prompts you to link your identity.

<Note>
  `/aether` always starts a new conversation in the channel: Slack does not deliver slash commands sent from inside a thread. To start a task from a thread, mention **@Aether** in it or use **Send to Aether** on one of its messages.
</Note>

### Send to Aether

To turn any message in a routed channel into a task, open the message's **⋯** menu and choose **Send to Aether**. The same task form as `/aether` opens, with the **Request** field holding the message's text (its first 3,000 characters for a longer message) and the project preselected as for `/aether`. Edit the request if you like, then submit.

The task runs in that message's thread, as if you had mentioned **@Aether** there: Aether posts the task's card in the thread, a reply in the thread follows up on the task, and **`cancel`**, **`stop`**, or **`abort`** there cancels it. On a reply inside a thread, the task runs in that thread, not under the reply.

* **Pull request links.** On a message that links exactly one pull request, the form also offers to review it; see [Without pasting the link](#without-pasting-the-link).
* **One task per thread.** If the message's thread already has an Aether task, submitting the form shows an error in it and starts nothing; reply in the thread to follow up on that task instead.
* **The rest is as for `/aether`.** A request is required, a channel with no enabled projects gets the explanatory form, Aether sends you a direct message if its app is not in the channel, and the task is yours if your Slack identity is linked. The message's original author is recorded on the task's first message.

### Change project

When a task ran in the wrong project, rerun it in the right one from its card. Task cards in a channel that routes to two or more enabled projects carry a **Change project** button; cards in a channel with a single project do not.

The button opens a form whose **Project** list holds the channel's other enabled projects (the task's current project is left out) and whose **Request** field holds the task's original prompt, which you can edit. When you submit it, Aether:

1. stops the current task, as if you had pressed its **Stop** button, and drops any follow-ups still queued for it;
2. starts a new task with your request in the project you chose, in the same thread;
3. moves the thread to the new task: from then on, replies in the thread are follow-ups to the new task, **`cancel`**, **`stop`**, or **`abort`** there cancels the new task, and the old task receives nothing more from the thread.

The old task's card stays in the thread and shows it stopped; the new task's card appears below it.

* **Link your identity first.** Only a Slack user linked to an Aether member of the org can change a task's project. Anyone else gets the prompt to link their identity, and nothing changes.
* **One change per thread at a time.** Once a thread has moved to a new task, **Change project** on an older card in it explains that the thread has moved on; use the button on the newest card instead.
* **Submitting twice changes once.** Slack redelivering the same submission stops the old task and starts the new one only once.
* **Long requests.** A task whose original request is longer than a Slack form holds (3,000 characters) cannot be rerun from Slack; the button explains this and links to the task in Aether instead.

## Reviewing a pull request

Ask Aether to review a pull request with a mention or the slash command:

```text theme={"dark"}
@Aether review https://github.com/acme/web/pull/18
/aether review https://github.com/acme/web/pull/18
```

This is the same review as commenting **`aether review`** on the pull request or clicking **Re-review at head** in Aether: it wakes the pull request's review run at its current head, or starts one if the pull request has none, and the verdict is posted on the pull request. No task is started.

To pick the pull request from a list instead of pasting its link, run `/aether` and choose **Review a pull request** at the top of the form. The form then lists the open pull requests of the repositories of the channel's enabled projects, newest first, each as `repo #N title` (up to 100). Choose one and click **Request review**: Aether posts the review's card in the channel, as for `/aether review`. If none of those repositories has an open pull request, the form says so and there is nothing to submit. Choose **Start a task** to go back to the task form.

A message asks for a review when, after the @Aether mention, it starts with `review` (in any case) and contains exactly one link to a GitHub pull request. A mention that has the word `review` and one pull request link but does not start with `review` gets a choice instead (see [Without pasting the link](#without-pasting-the-link)). Anything else — `review the login flow`, `reviewing <PR link>`, or links to two pull requests — starts a task as usual, and a mention in a thread that already has a task is a follow-up to that task.

* **The thread is the review's conversation.** Aether posts the review's card in the mention's thread; for `/aether review` and the form it posts the card in the channel, and the card's thread is the conversation. Reply in the thread to send the reviewer a follow-up, or reply **`cancel`**, **`stop`**, or **`abort`** to stop it.
* **The card shows the review.** While the review runs, the card says **Reviewing PR #18 of acme/web**. Once the review is posted, the card gives its verdict: **Approved PR #18**, **Changes requested on PR #18**, or **Commented on PR #18**. Its buttons open the review in Aether and the pull request on GitHub.
* **One conversation per review.** If the pull request's review already reports into another Slack thread, asking again still wakes it, but the review keeps reporting there: the new thread gets a note linking the pull request and the review instead of a second card.
* **The channel's projects.** The pull request's repository must be the repository of one of the channel's enabled projects.

A request Aether cannot act on, whichever way it was asked, gets a private note that only you can see, saying how to fix it, and asks for no review:

* the pull request's repository is not one of the channel's projects (with a link to Slack settings);
* no Aether project is connected to the repository, or more than one is;
* the pull request has not been synced from GitHub yet;
* the link is not a pull request, such as GitHub's page for opening one.

As for `/aether`, Aether sends you a direct message asking you to invite its app if `/aether review`, the form's review or a **Send to Aether** review is used in a channel the app is not in. Submitting the form twice for the same pull request asks for one review.

### Without pasting the link

Pull request links are often already in Slack, posted by a teammate or by GitHub's Slack app. You can ask for their review without typing the link again; each way below asks for the same review as `@Aether review <PR link>`, with the same card and the same private notes when Aether cannot act.

* **Reply under the link.** Reply **`@Aether review`** — the word alone — in the thread of a message that links exactly one pull request, in its text or in an attachment such as GitHub's Slack app and link previews post. Aether reviews that pull request, and the thread gets the review's card. Under a message with no pull request link, or links to two different pull requests, `@Aether review` starts a task as it always did.
* **Send to Aether.** On a message that links exactly one pull request, the [Send to Aether](#send-to-aether) form opens with a choice at the top: **Review this pull request** (preselected) or **Start a task**. A review needs no project and no request, so both fields are optional; submit, and the review's card appears in the message's thread. **Start a task** works as on any other message. A message with no pull request link, or links to several, gets the usual form with no choice.
* **Buttons when Aether is unsure.** A mention that has the word `review` and exactly one pull request link but does not start with `review` — `@Aether can you look at this and review the retry logic <PR link>` — gets a reply in its thread with two buttons, **Review PR #18** and **Start a task**, that anyone in the channel can click. **Review PR #18** asks for the review. **Start a task** starts the task the mention asks for, in the project the mention names or the channel's only project, or after **Which project?** otherwise. The buttons message becomes the review's or the task's card (or **Which project?** first).

The first click decides: a second click, by the same person or a teammate, on either button, changes nothing — also while a chosen task still waits on **Which project?** — and Slack redelivering a mention, a click or a form submission asks for nothing twice. As with **Which project?**, the request is the mention author's whoever clicks: a private note goes to them, and a refused review leaves the buttons in place, to click again once fixed or to start a task instead.

## Managing Routes

```bash theme={"dark"}
# List routes, grouped by channel
aether slack routes list

# Pause or resume a route
aether slack routes update <route-id> --enabled false
aether slack routes update <route-id> --enabled true

# Delete a route
aether slack routes delete <route-id> --force
```

`routes list` shows each channel once, on its first route, followed by that channel's routes in project-name order; **Settings → Connections → Slack** lists routes in the same order. Each route has its own `enabled` flag, so you can pause one project's route in a channel without deleting it or touching the channel's other routes. In Settings, each route also has its own agent profile and **Post task cards** toggle.

## Disconnecting Slack

```bash theme={"dark"}
aether slack disconnect --force
```

<Warning>
  Disconnecting removes all Slack routes. `--force` skips the confirmation prompt.
</Warning>

## API

The Slack endpoints are part of the frontend/CLI API surface, not the versioned `/v1` API, and are config-gated — see the [API overview](/api-reference/overview). Browse the operations under the Slack group, for example [list routes](/api-reference/account/slack/get-slack-routes) and [create a route](/api-reference/account/slack/post-slack-routes). The full CLI reference is at [`aether slack`](/cli/slack).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.