Slack

Connect Archon to Slack so you can interact with your AI coding assistant from any Slack workspace.

Prerequisites

• Archon server running (see Getting Started)
• A Slack workspace where you have permission to install apps

Overview

Archon uses Socket Mode for Slack integration, which means:

• No public HTTP endpoints needed
• Works behind firewalls
• Simpler local development
• Not suitable for Slack App Directory (fine for personal/team use)

Step 1: Create a Slack App

1. Go to Slack API Apps
2. Log in if prompted
3. Choose the workspace for your app
4. Click Create New App
5. Choose From scratch
6. Enter:
   • App Name: Any name (this is what you will use to @mention the bot)
   • Workspace: Select your workspace
7. Click Create App

Step 2: Enable Socket Mode

1. In the left sidebar, click Socket Mode
2. Toggle Enable Socket Mode to ON
3. When prompted, create an App-Level Token:
   • Token Name: socket-mode
   • Scopes: Add connections:write
   • Click Generate
4. Copy the token (starts with xapp-) — this is your SLACK_APP_TOKEN
5. Copy the token and put it in your .env file

Step 3: Configure Bot Scopes

1. In the left sidebar, click OAuth & Permissions
2. Scroll down to Scopes > Bot Token Scopes
3. Add these scopes to bot token scopes:
   • app_mentions:read — Receive @mention events
   • chat:write — Send and edit messages (covers chat.update on the bot’s own messages)
   • channels:history — Read messages in public channels (for thread context)
   • channels:join — Allow bot to join public channels
   • groups:history — Read messages in private channels (optional)
   • im:history — Read DM history (for DM support)
   • im:write — Send DMs
   • im:read — Read DM history (for DM support)
   • mpim:history — Read group DM history (optional)
   • mpim:write — Send group DMs
   • reactions:write — Add lifecycle reactions (🔄 / ✅ / ❌) to the triggering message
   • commands — Required for the /archon and /archon-workflow slash commands
   • users:read — Look up real names via users.info for user attribution. The adapter degrades gracefully if this scope is missing (real names won’t appear in the Archon DB, but messages still flow); a one-time slack.users_info_missing_scope warning surfaces the misconfiguration in the server log.

Step 4: Subscribe to Events

1. In the left sidebar, click Event Subscriptions
2. Toggle Enable Events to ON
3. Under Subscribe to bot events, add:
   • app_mention — When someone @mentions your bot
   • message.im — Direct messages to your bot
   • message.channels — Messages in public channels (optional, for broader context)
   • message.groups — Messages in private channels (optional)
4. Click Save Changes

Step 4b: Enable Interactivity

Interactive buttons (Approve / Reject / Cancel on workflow runs) ride the same Socket Mode connection — no public URL needed.

1. In the left sidebar, click Interactivity & Shortcuts
2. Toggle Interactivity to ON
3. Leave the Request URL field blank — Socket Mode handles routing
4. Click Save Changes

Step 4c: Register Slash Commands

Two slash commands give the team an alternative to @mention:

Command	What it does
/archon <message>	Talks to Archon in the current channel. Equivalent to @archon <message>.
/archon-workflow <subcommand>	Direct workflow control. Supports list, status, run <name> <args>, approve <id> [comment], reject <id> [reason], abandon <id>, resume <id>.

For each command:

1. In the left sidebar, click Slash Commands
2. Click Create New Command
3. Fill in:
   • Command: /archon (or /archon-workflow)
   • Request URL: leave blank — Socket Mode handles routing
   • Short Description: e.g. “Talk to Archon” or “Archon workflow control”
   • Usage Hint: e.g. <message> or <subcommand>
4. Save

Reinstall the app (Step 5) after adding scopes or commands so Slack issues a fresh token with the new permissions.

Step 5: Install to Workspace

1. In the left sidebar, click Install App
2. Click Install to Workspace
3. Review the permissions and click Allow
4. Copy the Bot User OAuth Token (starts with xoxb-) — this is your SLACK_BOT_TOKEN
5. Set the bot token in your .env file

Step 6: Set Environment Variables

Add to your .env file:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token

Step 7: Invite Bot to Channel

1. Go to the Slack channel where you want to use the bot
2. Type /invite @your-bot (your bot’s display name)
3. The bot should now respond to @mentions in that channel

Configure User Whitelist (Optional)

To restrict bot access to specific users:

1. In Slack, go to a user’s profile > click ”…” > “Copy member ID”
2. Add to environment:

SLACK_ALLOWED_USER_IDS=U01ABC123,U02DEF456

When set, only listed user IDs can interact with the bot. When empty/unset, the bot responds to all users.

Configure Streaming Mode (Optional)

SLACK_STREAMING_MODE=batch  # batch (default) | stream

For streaming mode details, see Configuration.

Usage

@Mention in Channels

@your-bot /clone https://github.com/user/repo

Continue Work in Thread

Reply in the thread created by the initial message:

@your-bot /status

Start Parallel Work (Worktree)

@your-bot /worktree feature-branch

Direct Messages

You can also DM the bot directly — no @mention needed:

/help

In-Thread UX

When a workflow runs in a Slack thread, Archon now:

• Adds 🔄 to your triggering message when the run starts, and swaps it for ✅ on completion or ❌ on failure / cancellation
• Posts a single status message in the thread that’s edited in place as DAG nodes start, complete, fail, or get skipped
• Renders approval gates as interactive Approve / Reject buttons in-thread — no need to leave Slack to resume a paused run
• Adds a Cancel button on the status message while the run is non-terminal, so anyone on the allowed user list can abandon a runaway run with a click
• Appends a small italic cost / token footer after direct-chat replies (e.g. _cost: $0.0234 · 12.4k tokens · stop: end_turn_) and on the final status message when a workflow completes
• Annotates long responses split across multiple Slack messages with _part i/n_ footers so it’s clear they belong together

All clicks on Approve / Reject / Cancel run through the same SLACK_ALLOWED_USER_IDS whitelist as inbound messages — unauthorized clicks are silently dropped and logged.

Troubleshooting

Bot Doesn’t Respond

1. Check that Socket Mode is enabled
2. Verify both tokens are correct in .env
3. Check the app logs for errors
4. Ensure the bot is invited to the channel
5. Make sure you’re @mentioning the bot (not just typing)

“channel_not_found” Error

The bot needs to be invited to the channel:

/invite @your-bot

“missing_scope” Error

Add the required scope in OAuth & Permissions and reinstall the app.

Thread Context Not Working

Ensure these scopes are added:

• channels:history (public channels)
• groups:history (private channels)

Security Recommendations

1. Use User Whitelist: Set SLACK_ALLOWED_USER_IDS to restrict bot access
2. Private Channels: Invite the bot only to channels where it’s needed
3. Token Security: Never commit tokens to version control

Reference Links

• Slack API Documentation
• Bolt for JavaScript
• Socket Mode Guide
• Permission Scopes