add-slack

name	add-slack
description	Add Slack as a channel. Can replace WhatsApp entirely or run alongside it. Uses Socket Mode (no public URL needed).
disable-model-invocation	true

Add Slack Channel

Status: Coming soon — this channel will be available as @deus-ai/slack-mcp. The MCP package is not yet available.

This skill will add Slack support to Deus once the MCP package is released. In the meantime, the setup/config/registration phases below describe what the integration will look like.

Phase 1: Setup (Future)

Create Slack App (if needed)

If the user doesn't have a Slack app, share SLACK_SETUP.md which has step-by-step instructions with screenshots guidance, troubleshooting, and a token reference table.

Quick summary of what's needed:

1. Create a Slack app at api.slack.com/apps
2. Enable Socket Mode and generate an App-Level Token (xapp-...)
3. Subscribe to bot events: message.channels, message.groups, message.im
4. Add OAuth scopes: chat:write, channels:history, groups:history, im:history, channels:read, groups:read, users:read
5. Install to workspace and copy the Bot Token (xoxb-...)

Configure environment

Add to .env:

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

Channels auto-enable when their credentials are present — no extra configuration needed.

Sync to container environment:

mkdir -p data/env && cp .env data/env/env

The container reads environment from data/env/env, not .env directly.

Phase 2: Registration (Future)

Get Channel ID

Tell the user:

1. Add the bot to a Slack channel (right-click channel → View channel details → Integrations → Add apps)
2. In that channel, the channel ID is in the URL when you open it in a browser: https://app.slack.com/client/T.../C0123456789 — the C... part is the channel ID
3. Alternatively, right-click the channel name → Copy link — the channel ID is the last path segment

The JID format for Deus is: slack:C0123456789

Register the channel

The channel ID, name, and folder name are needed. Use npx tsx setup/index.ts --step register with the appropriate flags.

For a main channel (responds to all messages):

npx tsx setup/index.ts --step register -- --jid "slack:<channel-id>" --name "<channel-name>" --folder "slack_main" --trigger "@${ASSISTANT_NAME}" --channel slack --no-trigger-required --is-main

For additional channels (trigger-only):

npx tsx setup/index.ts --step register -- --jid "slack:<channel-id>" --name "<channel-name>" --folder "slack_<channel-name>" --trigger "@${ASSISTANT_NAME}" --channel slack

Verify

Smoke test

Run the automated smoke test to verify service, DB, and channel connection:

npx tsx setup/index.ts --step smoke-test -- --channel slack

The smoke test checks: service running, registered group exists, DB write/read works, and channel connection appears in logs.

If the smoke test passes, tell the user "Slack channel is working."

If it fails, check the STATUS output for the specific failure (service down, no registered group, DB error, or no log connection). Guide the user to fix the issue before proceeding.

After the automated check, also ask the user to send a test message to verify real-time delivery:

Send a message in your registered Slack channel to confirm real-time delivery.

• For main channel: Any message works
• For non-main: @mention the bot

Troubleshooting

Bot not responding

1. Check SLACK_BOT_TOKEN and SLACK_APP_TOKEN are set in .env AND synced to data/env/env
2. Check channel is registered: sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE 'slack:%'"
3. For non-main channels: message must include trigger pattern
4. Service is running: launchctl list | grep deus

Bot connected but not receiving messages

1. Verify Socket Mode is enabled in the Slack app settings
2. Verify the bot is subscribed to the correct events (message.channels, message.groups, message.im)
3. Verify the bot has been added to the channel
4. Check that the bot has the required OAuth scopes

Bot not seeing messages in channels

By default, bots only see messages in channels they've been explicitly added to. Make sure to:

1. Add the bot to each channel you want it to monitor
2. Check the bot has channels:history and/or groups:history scopes

"missing_scope" errors

If the bot logs missing_scope errors:

1. Go to OAuth & Permissions in your Slack app settings
2. Add the missing scope listed in the error message
3. Reinstall the app to your workspace — scope changes require reinstallation
4. Copy the new Bot Token (it changes on reinstall) and update .env
5. Sync: mkdir -p data/env && cp .env data/env/env
6. Restart: launchctl kickstart -k gui/$(id -u)/com.deus

Getting channel ID

If the channel ID is hard to find:

• In Slack desktop: right-click channel → Copy link → extract the C... ID from the URL
• In Slack web: the URL shows https://app.slack.com/client/TXXXXXXX/C0123456789
• Via API: curl -s -H "Authorization: Bearer $SLACK_BOT_TOKEN" "https://slack.com/api/conversations.list" | jq '.channels[] | {id, name}'

After Setup

The Slack channel supports:

• Public channels — Bot must be added to the channel
• Private channels — Bot must be invited to the channel
• Direct messages — Users can DM the bot directly
• Multi-channel — Can run alongside WhatsApp or other channels (auto-enabled by credentials)

Known Limitations

• Threads are flattened — Threaded replies are delivered to the agent as regular channel messages. The agent sees them but has no awareness they originated in a thread. Responses always go to the channel, not back into the thread. Users in a thread will need to check the main channel for the bot's reply. Full thread-aware routing (respond in-thread) requires pipeline-wide changes: database schema, NewMessage type, Channel.sendMessage interface, and routing logic.
• No typing indicator — Slack's Bot API does not expose a typing indicator endpoint. The setTyping() method is a no-op. Users won't see "bot is typing..." while the agent works.
• Message splitting is naive — Long messages are split at a fixed 4000-character boundary, which may break mid-word or mid-sentence. A smarter split (on paragraph or sentence boundaries) would improve readability.
• No file/image handling — The bot only processes text content. File uploads, images, and rich message blocks are not forwarded to the agent.
• Channel metadata sync is unbounded — syncChannelMetadata() paginates through all channels the bot is a member of, but has no upper bound or timeout. Workspaces with thousands of channels may experience slow startup.
• Workspace admin policies not detected — If the Slack workspace restricts bot app installation, the setup will fail at the "Install to Workspace" step with no programmatic detection or guidance. See SLACK_SETUP.md troubleshooting section.