Slack
Connect Archon to Slack so you can interact with your AI coding assistant from any Slack workspace.
Slack runs as a chat plugin, chat-slack, released with Archon. The server starts the plugin as its own process and talks to it over the chat plugin protocol; the server itself contains no Slack code. You create a Slack app, set its two tokens in the server environment, and install the plugin. Docker provisions the image-provided plugin automatically when SLACK_BOT_TOKEN is configured.
New identities are created as members. The operator can designate admins with archon user role <id> admin; only a run’s starter or an admin can act on it. See Who can act on a run.
Prerequisites
Section titled “Prerequisites”- Archon server running (
archon serve; see Web UI) - A Slack workspace where you have permission to install apps
- An Archon release that publishes the Slack plugin asset (
archon-chat-slack-<os>-<arch>)
Overview
Section titled “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
Section titled “Step 1: Create a Slack App”- Go to Slack API Apps
- Log in if prompted
- Choose the workspace for your app
- Click Create New App
- Choose From scratch
- Enter:
- App Name: Any name (this is what you will use to @mention the bot)
- Workspace: Select your workspace
- Click Create App
Step 2: Enable Socket Mode
Section titled “Step 2: Enable Socket Mode”- In the left sidebar, click Socket Mode
- Toggle Enable Socket Mode to ON
- When prompted, create an App-Level Token:
- Token Name:
socket-mode - Scopes: Add
connections:write - Click Generate
- Token Name:
- Copy the token (starts with
xapp-) — this is yourSLACK_APP_TOKEN
Step 3: Configure Bot Scopes
Section titled “Step 3: Configure Bot Scopes”- In the left sidebar, click OAuth & Permissions
- Scroll down to Scopes > Bot Token Scopes
- Add these scopes to bot token scopes:
app_mentions:read— Receive @mention eventschat:write— Send and edit messages (coverschat.updateon the bot’s own messages)channels:history— Read messages in public channels (for thread context)channels:join— Allow bot to join public channelsgroups:history— Read messages in private channels (optional)im:history— Read DM history (for DM support)im:write— Send DMsim:read— Read DM history (for DM support)mpim:history— Read group DM history (optional)mpim:write— Send group DMsreactions:write— Add lifecycle reactions (🔄 / ✅ / ❌) to the triggering messagecommands— Required for the/archonand/archon-workflowslash commandsusers:read— Look up real names viausers.infofor user attribution. Without this scope messages still flow, but real names do not appear in the Archon database.
Step 4: Subscribe to Events
Section titled “Step 4: Subscribe to Events”- In the left sidebar, click Event Subscriptions
- Toggle Enable Events to ON
- Under Subscribe to bot events, add:
app_mention— When someone @mentions your botmessage.im— Direct messages to your botmessage.channels— Messages in public channels (optional, for broader context)message.groups— Messages in private channels (optional)
- Click Save Changes
Step 4b: Enable Interactivity
Section titled “Step 4b: Enable Interactivity”Interactive buttons (gate decisions and Cancel on workflow runs) ride the same Socket Mode connection — no public URL needed.
- In the left sidebar, click Interactivity & Shortcuts
- Toggle Interactivity to ON
- Leave the Request URL field blank — Socket Mode handles routing
- Click Save Changes
Step 4c: Register Slash Commands
Section titled “Step 4c: Register Slash Commands”Two slash commands give the team an alternative to @mention:
| Command | What it does |
|---|---|
/archon <message> | Starts a new thread in the current channel. To continue an existing thread, post @archon <message> in that thread. |
/archon-workflow <subcommand> | Direct workflow control. Supports list, status, get <id>, run <name> <args>, approve <id> [comment], reject <id> [reason], respond <id> <decision> [text], abandon <id>, resume <id>. |
For each command:
- In the left sidebar, click Slash Commands
- Click Create New Command
- 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>
- Command:
- 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
Section titled “Step 5: Install to Workspace”- In the left sidebar, click Install App
- Click Install to Workspace
- Review the permissions and click Allow
- Copy the Bot User OAuth Token (starts with
xoxb-) — this is yourSLACK_BOT_TOKEN
Step 6: Set Environment Variables
Section titled “Step 6: Set Environment Variables”Add both tokens to the server’s env file (~/.archon/.env, or the compose .env in Docker):
SLACK_BOT_TOKEN=xoxb-your-bot-tokenSLACK_APP_TOKEN=xapp-your-app-tokenIn Docker, a nonempty SLACK_BOT_TOKEN declares installation at startup, including tokens in /.archon/.env. Both tokens are required for a connection.
The plugin reads them from the environment the server starts it with. If either is missing, the plugin fails to start and the server does not retry it.
Step 7: Install the Slack Plugin
Section titled “Step 7: Install the Slack Plugin”With the release binary or Homebrew:
archon plugin add coleam00/Archon/plugins/chat-slackIn a source checkout, run bun run cli plugin add coleam00/Archon/plugins/chat-slack.
In Docker, restart the container with its tokens configured. The image-provided release installs offline before the server starts, writes a verified receipt to /.archon/plugins, and logs why it was provisioned. No manual install is needed. A valid installed Slack plugin is retained at its current version. See Building the image for the release pin and build args.
Without a tag, manual plugin add installs the latest release. Restart the server; Slack appears in /api/health once the plugin connects. Keep the plugin current with archon plugin update coleam00/Archon/plugins/chat-slack, and remove it with archon plugin remove coleam00/Archon/plugins/chat-slack. In Docker, remove Slack tokens from every effective env source as well, or the image plugin is reinstalled on restart. Outside Docker, removal followed by a restart keeps Slack off. See archon plugin.
Step 8: Invite Bot to Channel
Section titled “Step 8: Invite Bot to Channel”- Go to the Slack channel where you want to use the bot
- Type
/invite @your-bot(your bot’s display name) - The bot should now respond to @mentions in that channel
Configure User Whitelist (Optional)
Section titled “Configure User Whitelist (Optional)”To restrict bot access to specific users:
- In Slack, go to a user’s profile > click ”…” > “Copy member ID”
- Add to environment:
SLACK_ALLOWED_USER_IDS=U01ABC123,U02DEF456When set, only listed user IDs can interact with the bot. When empty/unset, the bot responds to all users. The server enforces this list, for messages and for button clicks alike, before anything reaches Archon.
Configure Streaming Mode (Optional)
Section titled “Configure Streaming Mode (Optional)”SLACK_STREAMING_MODE=batch # batch (default) | streamFor streaming mode details, see Configuration.
Select a registered project by posting @your-bot /setproject <name> in the target thread. To register a local directory first, post @your-bot /register-project [--folder] <name> <path>, then select it; registration alone does not bind the conversation. Projectless questions still work. Selection applies to that conversation, not every channel.
Slack registers /archon and /archon-workflow, not raw /setproject or /register-project slash commands. /archon <message> creates a new thread; use an @mention in the existing thread to scope that conversation.
Once scoped, the assistant launches and manages runs through its native tools (Claude, Codex, Pi) or the existing CLI (Copilot/OpenCode). CLI launches are detached and headless, use CLI identity and return a run ID for inspection; they do not deliver progress or results to the originating chat. See Deprecated providers.
@Mention in Channels
Section titled “@Mention in Channels”@your-bot /clone https://github.com/user/repoContinue Work in Thread
Section titled “Continue Work in Thread”Reply in the thread created by the initial message:
@your-bot /statusStart Parallel Work (Worktree)
Section titled “Start Parallel Work (Worktree)”@your-bot /worktree feature-branchDirect Messages
Section titled “Direct Messages”You can also DM the bot directly — no @mention needed:
/helpIn-Thread UX
Section titled “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 execution completion or ❌ on execution failure / cancellation. If a declared authored outcome disagrees, it also adds the outcome reaction, so both facts remain visible
- Posts a single status message in the thread that’s edited in place as DAG nodes start, complete, fail, or get skipped
- When approval details are available, renders the gate’s declared decisions as
buttons, using labels when supplied and sending the exact decision ID.
Legacy gates keep Approve / Reject.
The fallback text lists
/archon-workflow respond <id> <decision> [text]commands; use these to include optional text with a decision. For a parent blocked on a child run, these parent controls redirect to the child instead of recording a parent decision. Answer the child run using the displayed child command - If approval details cannot be loaded, posts an Approval details unavailable notice naming the run instead of decision buttons or response commands. Check the run status before responding
- Adds a Cancel button on the status message while the run is non-terminal, so the run’s starter or an admin 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 - Labels execution status and a non-null authored outcome separately in the final status message; workflows without an authored outcome retain the existing status-only message
- Annotates long responses split across multiple Slack messages with
_part i/n_footers so it’s clear they belong together
All gate-decision and Cancel clicks run through the same
SLACK_ALLOWED_USER_IDS whitelist as inbound messages — clicks from users
outside it are dropped. A member who is not the run’s starter or an admin sees
a refusal only they can see.
/archon connect github replies with a pointer to the Web UI or
archon auth github; it does not run the GitHub device flow in Slack.
Upgrading From the Bundled Slack Adapter
Section titled “Upgrading From the Bundled Slack Adapter”Earlier Archon versions ran Slack inside the server whenever SLACK_BOT_TOKEN and
SLACK_APP_TOKEN were set. The server no longer contains that adapter: without the
plugin, Slack stays off. When SLACK_BOT_TOKEN is set and no Slack plugin is installed,
startup logs a chat.bundled_adapter_retired warning with Docker provisioning guidance and the manual install command.
In Docker, existing token configuration provisions the image-provided plugin offline on restart; no manual step is needed. The boot log names the release and why it was installed. Outside Docker, install the plugin (Step 7) and restart. Nothing else changes: the tokens, the Slack app
configuration, SLACK_ALLOWED_USER_IDS and SLACK_STREAMING_MODE stay as they are, and
existing conversations, linked identities and workspaces carry over because the plugin
keeps the platform id slack.
Troubleshooting
Section titled “Troubleshooting”Bot Doesn’t Respond
Section titled “Bot Doesn’t Respond”- Check that the plugin is installed:
archon plugin listshowscoleam00/Archon/plugins/chat-slack - Check that Socket Mode is enabled
- Verify both tokens are correct in
.env, then check the server log forchat.bundled_adapter_retiredor a plugin start failure - Ensure the bot is invited to the channel
- Make sure you’re @mentioning the bot (not just typing)
“channel_not_found” Error
Section titled ““channel_not_found” Error”The bot needs to be invited to the channel:
/invite @your-bot“missing_scope” Error
Section titled ““missing_scope” Error”Add the required scope in OAuth & Permissions and reinstall the app.
Thread Context Not Working
Section titled “Thread Context Not Working”Ensure these scopes are added:
channels:history(public channels)groups:history(private channels)
Security Recommendations
Section titled “Security Recommendations”- Use User Whitelist: Set
SLACK_ALLOWED_USER_IDSto restrict bot access - Private Channels: Invite the bot only to channels where it’s needed
- Token Security: Never commit tokens to version control
