Slack Bot Minimal Setup Guide

Slack Bot Minimal Setup Guide

This guide lists the minimum Slack app settings needed to run mikan over Socket Mode.

You can also create the app from the example manifest at examples/slack-app-manifest.json.

1. Create the Slack app

1. Open https://api.slack.com/apps.
2. Click Create New App.
3. Choose From scratch.
4. Pick an app name, for example mikan, and select your workspace.

2. Enable Socket Mode

1. Go to Settings → Socket Mode.
2. Turn Enable Socket Mode on.
3. Create an app-level token with the connections:write scope.
4. Save the token as SLACK_APP_TOKEN.

The token starts with xapp-.

3. Configure bot token scopes

Go to OAuth & Permissions → Scopes → Bot Token Scopes and add:

• app_mentions:read
• assistant:write
• channels:history
• channels:read
• chat:write
• files:read
• files:write
• groups:history
• groups:read
• im:history
• im:read
• im:write
• users:read

Then install or reinstall the app to your workspace and save the bot token as SLACK_BOT_TOKEN.

The token starts with xoxb-.

4. Enable App Home and Agent mode

1. Go to Features → App Home.
2. Enable Home Tab.
3. In Agents & AI Apps, enable Agent or Assistant.

This allows Slack’s native assistant thread events and working indicators to reach the bot.

5. Subscribe to bot events

Go to Features → Event Subscriptions and enable events.

Subscribe to these bot events:

• app_home_opened
• app_mention
• assistant_thread_context_changed
• assistant_thread_started
• message.channels
• message.groups
• message.im

6. Enable interactivity

Go to Features → Interactivity & Shortcuts and turn interactivity on.

A public request URL is not required for Socket Mode-only local development, but Slack may still ask for one in some app configurations.

7. Optional slash commands

The example manifest includes slash commands for common controls:

• /pi-login → login portal
• /pi-new → start a new DM session
• /pi-session → session viewer
• /pi-model → switch this conversation’s LLM (provider/model[:thinking], e.g. anthropic/claude-sonnet-4-6:off)
• /pi-auto-reply → manage group/channel auto-reply rules

Slash commands are optional because text commands also work in supported contexts. Keep stop as a text command (stop or /stop) so thread-local stop routing can target the correct session.

8. Run mikan

export SLACK_APP_TOKEN=xapp-...
export SLACK_BOT_TOKEN=xoxb-...

mikan --state-dir ~/.mikan /path/to/workspace

The bot responds in DMs and when mentioned in channels. Slack thread replies use isolated thread sessions with the thread timestamp as part of the session key.