# Configuring Slack Integration for Orchestrate Task Status Updates in Cursor Plugins

> Easily configure Slack integration for Orchestrate task status updates in Cursor plugins. Mirror task states automatically to Slack threads by setting environment variables.

- Repository: [Cursor/plugins](https://github.com/cursor/plugins)
- Tags: how-to-guide
- Published: 2026-05-25

---

**Set the `SLACK_BOT_TOKEN` and `SLACK_CHANNEL_ID` environment variables to enable automatic Slack thread mirroring of Orchestrate task states.**

The cursor/plugins repository ships with a built-in Slack adapter that automatically mirrors Orchestrate task executions to dedicated Slack threads. When properly configured, the system posts a kickoff message in a designated channel and updates that thread with real-time status changes, reactions, and file uploads for every task execution.

## Prerequisites and Configuration Values

The integration requires three specific configuration pieces to authenticate and route messages correctly.

### Slack Bot Token

The **Slack bot token** authenticates API calls to Slack. Set this via the `SLACK_BOT_TOKEN` environment variable. If this variable is unset or cleared, the integration disables itself entirely. According to the source code in [`orchestrate/skills/orchestrate/scripts/cli/util.ts`](https://github.com/cursor/plugins/blob/main/orchestrate/skills/orchestrate/scripts/cli/util.ts), the CLI warns users that removing this token disables Slack functionality.

### Channel Target

The **Slack channel ID** determines where the kickoff thread is created. Configure this via:
- The `SLACK_CHANNEL_ID` environment variable, or
- The `plan.slackChannel` field in your [`plan.json`](https://github.com/cursor/plugins/blob/main/plan.json) file

The CLI helper in [`cli/util.ts`](https://github.com/cursor/plugins/blob/main/cli/util.ts) parses the `--slack-channel` flag and validates these targets before execution.

### Kickoff Reference Storage

The **kickoff reference** holds the `channel` ID and `thread_ts` (timestamp) of the root message. This value populates automatically on the first planner run and stores in `plan.slackKickoffRef`. The `AgentManager` in [`orchestrate/skills/orchestrate/scripts/core/agent-manager.ts`](https://github.com/cursor/plugins/blob/main/orchestrate/skills/orchestrate/scripts/core/agent-manager.ts) handles this persistence at line 1665, ensuring subsequent task updates reply to the correct thread.

## How the Slack Adapter Works

The Orchestrate engine implements a generic `SlackAdapter` interface through the concrete `SlackApiAdapter` class.

### Initialization in AgentManager

When the planner executes as the *root* run, `AgentManager` instantiates the adapter via `createSlackWebClient`. The initialization logic checks for existing references before creating new threads:

```typescript
// agent-manager.ts – line 1665
if (args.plan.slackKickoffRef) return;
if (!args.slackAdapter) return;
args.plan.slackKickoffRef = await args.slackAdapter.postRunKickoff({
    text: `Orchestrate run ${plan.runId}`,
    username: "cursor-bot"
});

```

### Kickoff Message Creation

The adapter immediately posts a kickoff message using `postRunKickoff`. This method returns a `SlackMessageRef` object containing the `channel` and `ts` (timestamp) values required for subsequent thread operations.

### Task State Mirroring

Every task state change triggers an update via `slackRenderForTask`, which computes the appropriate emoji and summary text. The system either creates a new message or edits an existing one:

```typescript
// agent-manager.ts – line 1329-1335
const ref = task.slackTs
    ? await this.slackAdapter.editThreadMessage({ threadTs, ts: task.slackTs, text })
    : await this.slackAdapter.postInThread({ threadTs, text });
task.slackTs = ref.ts;

```

### Comment and Reaction Handling

The **comment-retry queue** in [`orchestrate/skills/orchestrate/scripts/core/comment-retry-queue.ts`](https://github.com/cursor/plugins/blob/main/orchestrate/skills/orchestrate/scripts/core/comment-retry-queue.ts) validates destinations starting with `slack:` and forwards them to `postCommentInThread`. Additionally, the **Andon** component in [`orchestrate/skills/orchestrate/scripts/core/andon.ts`](https://github.com/cursor/plugins/blob/main/orchestrate/skills/orchestrate/scripts/core/andon.ts) retrieves thread reactions and replies via `getReactions` and `getThreadReplies` for status dashboards.

## Step-by-Step Configuration

Follow these steps to enable live Slack updates for your Orchestrate runs.

### 1. Configure Environment Variables

Export the required tokens before invoking the CLI:

```bash
export SLACK_BOT_TOKEN=xoxb-your-bot-token-here
export SLACK_CHANNEL_ID=C01ABCD2EFG

```

The bot token requires scopes including `chat:write`, `reactions:read`, and `files:write`.

### 2. Optional: Pin Channel in Plan Configuration

For sub-planners or persistent configurations, pin the channel in your [`plan.json`](https://github.com/cursor/plugins/blob/main/plan.json):

```json
{
  "slackChannel": "C01ABCD2EFG"
}

```

### 3. Execute with CLI Flags

Run Orchestrate with explicit channel targeting:

```bash
cursor orchestrate run --slack-channel C01ABCD2EFG

```

The first root planner automatically posts the kickoff message and persists the reference for the duration of the run.

## Key Source Files and Implementation Details

Understanding the source structure helps customize the integration:

- **[`adapters/slack/index.ts`](https://github.com/cursor/plugins/blob/main/adapters/slack/index.ts)** – Implements `SlackApiAdapter` with methods `postRunKickoff`, `postInThread`, `editThreadMessage`, and `postCommentInThread`. This file maps the generic interface to the official `@slack/web-api` client.

- **[`core/agent-manager.ts`](https://github.com/cursor/plugins/blob/main/core/agent-manager.ts)** – Coordinates Slack adapter creation, manages `plan.slackKickoffRef`, and mirrors task state changes to the thread.

- **[`core/loop.ts`](https://github.com/cursor/plugins/blob/main/core/loop.ts)** – Propagates the Slack kickoff reference to worker processes during orchestration execution.

- **[`cli/util.ts`](https://github.com/cursor/plugins/blob/main/cli/util.ts)** – Parses CLI-level Slack flags and injects helper instructions into generated plan files.

- **[`schemas.ts`](https://github.com/cursor/plugins/blob/main/schemas.ts)** – Defines the `slackChannel` and `slackKickoffRef` schema fields used in [`plan.json`](https://github.com/cursor/plugins/blob/main/plan.json) validation.

- **[`core/comment-retry-queue.ts`](https://github.com/cursor/plugins/blob/main/core/comment-retry-queue.ts)** – Filters destinations for Slack-prefixed strings and manages retry logic for thread comments.

- **[`core/andon.ts`](https://github.com/cursor/plugins/blob/main/core/andon.ts)** – Retrieves real-time reactions and thread replies for monitoring dashboards.

## Summary

- **Authentication**: Set `SLACK_BOT_TOKEN` to enable the adapter; omitting it disables Slack entirely.
- **Channel Targeting**: Use `SLACK_CHANNEL_ID` or `plan.slackChannel` to designate the destination channel.
- **Automatic Threading**: The system creates kickoff messages automatically and stores references in `plan.slackKickoffRef`.
- **Live Updates**: Task status changes, comments, and reactions sync to the thread via `AgentManager` and `SlackApiAdapter`.
- **Implementation**: Core logic resides in [`agent-manager.ts`](https://github.com/cursor/plugins/blob/main/agent-manager.ts) and [`adapters/slack/index.ts`](https://github.com/cursor/plugins/blob/main/adapters/slack/index.ts) within the cursor/plugins repository.

## Frequently Asked Questions

### How do I disable Slack integration after enabling it?

Unset the `SLACK_BOT_TOKEN` environment variable. According to [`cli/util.ts`](https://github.com/cursor/plugins/blob/main/cli/util.ts), clearing this token prevents the CLI from initializing the Slack adapter, effectively disabling all Slack mirroring without modifying other configuration values.

### Can I change the Slack channel for a running orchestration?

No. The `slackKickoffRef` is established during the first root planner run and stored in `plan.slackKickoffRef`. Changing channels requires starting a new orchestration run with a different `SLACK_CHANNEL_ID` or `--slack-channel` flag.

### What permissions does the Slack bot require?

The bot token requires `chat:write` to post messages, `reactions:read` to retrieve emoji reactions, and `files:write` to upload task outputs. These scopes allow the `SlackApiAdapter` to execute `postInThread`, `getReactions`, and related methods.

### Why are my task comments not appearing in Slack?

Ensure comment destinations use the `slack:` prefix (e.g., `slack:thread`). The [`comment-retry-queue.ts`](https://github.com/cursor/plugins/blob/main/comment-retry-queue.ts) validates destinations and only forwards those starting with `slack:` to `postCommentInThread`. Verify the original kickoff message posted successfully and that `plan.slackKickoffRef` contains valid channel and timestamp values.