Configuring Slack Integration for Orchestrate Task Status Updates in Cursor Plugins

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, 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 file

The CLI helper in 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 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:

// 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:

// 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 validates destinations starting with slack: and forwards them to postCommentInThread. Additionally, the Andon component in 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:

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:

{
  "slackChannel": "C01ABCD2EFG"
}

3. Execute with CLI Flags

Run Orchestrate with explicit channel targeting:

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 – 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 – Coordinates Slack adapter creation, manages plan.slackKickoffRef, and mirrors task state changes to the thread.

• core/loop.ts – Propagates the Slack kickoff reference to worker processes during orchestration execution.

• cli/util.ts – Parses CLI-level Slack flags and injects helper instructions into generated plan files.

• schemas.ts – Defines the slackChannel and slackKickoffRef schema fields used in plan.json validation.

• core/comment-retry-queue.ts – Filters destinations for Slack-prefixed strings and manages retry logic for thread comments.

• 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 and 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}