---
title: "Slack Bot minimal setup guide"
description: "Minimal Slack app permissions, events, and manifest settings required to run mikan through Socket Mode."
url: "https://geminixiang.github.io/slack-bot-minimal-guide/"
---

# Slack Bot minimal setup guide

You can also create the app with the example manifest in `examples/slack-app-manifest.json`.

## 1. Create a 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 on **Enable Socket Mode**.
3. Create an app-level token with the `connections:write` scope.
4. Store 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`
- `commands` (required only when using the optional slash commands below)
- `files:read`
- `files:write`
- `groups:history`
- `groups:read`
- `im:history`
- `im:read`
- `im:write`
- `reactions:write`
- `users:read`

Then install or reinstall the app to your workspace and store 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. Enable **Agent or Assistant** under **Agents & AI Apps**.

This enables Slack's assistant UI. mikan writes assistant working status through `assistant:write`; the subscribed assistant context events are reserved for Slack compatibility and are not separate agent triggers.

## 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 enable interactivity.

If you only use Socket Mode for local development, you do not need a public request URL, though Slack may still require one in some app settings.

## 7. Optional slash commands

The example manifest includes common control slash commands:

- `/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]`, for example `anthropic/claude-sonnet-4-6:off`)
- `/pi-auto-reply` → manage group/channel auto-reply rules
- `/pi-sandbox` → inspect or tune this conversation's sandbox
- `/pi-extensions` → list installed extensions
- `/pi-admin` → open the admin portal

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 point at the correct session.

## 8. Run mikan

mikan needs its global settings file and an LLM provider key once — `mikan --onboard` and `export ANTHROPIC_API_KEY=...`; see [Quickstart](/quickstart/) — then:

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

mikan
```

The state directory defaults to `~/.mikan` and the working directory to `<state-dir>/workspace`; pass `--state-dir=<dir>` or a path argument to change them. `mikan --help` lists all flags, and `mikan env` shows which variables are currently set.

The bot responds in DMs and when mentioned in channels. Triggered Slack thread work uses an isolated session whose key includes the thread timestamp. An ordinary unmentioned reply in a shared-channel thread is logged but does not start a run.