Slack Bot minimal setup guide

Let mikan create and update the app

mikan can create the Slack app and keep it configured, so a release that adds a slash command, scope, or event needs no change in Slack’s settings. It needs a Slack app configuration token: open api.slack.com/apps, find Your App Configuration Tokens at the bottom, generate one for your workspace, and copy its Refresh Token (xoxe-1-…).

• New app: run mikan onboard, pick Slack, then Create a new Slack app for me. mikan creates the app, prints its install link, and asks for the bot token and the Socket Mode token, the two steps Slack keeps in its web pages.
• Existing app: run mikan slack token and paste the refresh token. On its next start mikan replaces the app’s configuration with its own manifest; settings added by hand in Slack are removed.
• Name and description: mikan slack set --name <name> --description <text> saves them in ~/.mikan/slack.json, and the next start applies them. The name is both the app’s name and the bot’s name in conversations; Slack accepts only letters, digits, spaces, ., _, and - in a bot’s name, so for any other name the bot stays mikan. Edits made in Slack’s settings pages are overwritten.

mikan rotates the token on every start and keeps the newest one in ~/.mikan/slack-config-token.json (0600). Each rotation revokes the previous token, so give one token to one mikan install. When a release adds a scope, mikan DMs the person who created the token a reinstall link; the bot keeps running with the scopes it has until then. The token belongs to that person: if they leave the workspace, store a token from another collaborator. mikan applies the classic manifest below, so do not store a token for an app built from the agent manifest.

You can also create the app from an example manifest. There are two, because Slack offers two surfaces and mikan serves both:

Manifest	Surface	Use when
deploy/examples/slack-app-manifest.json	Classic app	People talk to mikan by @mentioning it in channels and by DM.
deploy/examples/slack-agent-manifest.json	Agent (AI app)	You also want mikan in the Agents & AI apps sidebar, with its own pane, greeting, suggested prompts, and a conversation list.

The agent manifest is the classic one plus three things: the agent_view feature, the assistant:write scope, and the assistant_thread_started / assistant_thread_context_changed events. Everything else — slash commands, Socket Mode, message events — is identical, and the same mikan process serves either. Start from the classic one if you are not sure; adding the agent surface later is an edit to the same app.

The agent surface needs a paid Slack plan. Slack’s own wording is that these features “require a paid plan, despite being visible in the app settings on any plan” — so on a free workspace every toggle turns on, the events save, the app reinstalls, and then nothing is ever delivered. There is no error to find; a listener that never fires is the only symptom. If you are only developing, the Slack Developer Program provisions a fully-featured sandbox for free, which is the cheaper answer than upgrading a real workspace. The classic app surface — mentions, DMs, slash commands, Block Kit — is unaffected and works on any plan.

Which is to say: mikan’s side of the agent surface is written, tested, and waiting — the greeting, the suggested prompts, the per-thread sessions, the conversation titles — and it has never once run against a real paid workspace, because the author’s is free. It has been verified the only way a free plan allows: by proving Slack sends nothing at all. If you are on a paid plan and want mikan as your team’s agent, open an issue. Getting that surface exercised against a workspace that actually delivers the events would be a good day, and the support will be enthusiastic.

agent_view and assistant_view are two surfaces, not two spellings of one. The events and the assistant.threads.* methods kept their names, but which events mean “someone opened a conversation” changed: agent_view uses app_home_opened (with tab: "messages") and app_context_changed, while assistant_view uses assistant_thread_started and assistant_thread_context_changed. mikan handles both, so either manifest works. New apps can only choose agent_view; assistant_view still works but Slack has said it will eventually be deprecated.

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 (agent surface only — the assistant.threads.* methods that set the pane’s status, suggested prompts, and conversation title)
• channels:history
• channels:read
• chat:write
• chat:write.customize (subagent persona: without it Slack silently drops the custom username/icon on a subagent’s final answer and posts it under the bot’s own identity instead — no error, no warning, just the wrong name)
• 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 Agent mode

1. Enable Agent or Assistant under Agents & AI Apps.

This is what puts mikan in the Agents & AI apps sidebar with its own pane. Skip it for a classic app.

In the pane, mikan greets the person when they open a conversation, offers suggested prompts shaped by the channel they are viewing, shows a working status while it thinks, and names each conversation from its first message so the sidebar list is navigable. Each conversation there is a thread, and mikan gives every thread its own session — the sidebar is a list of separate conversations, not one transcript, and continuity across them comes from memory rather than from a shared session.

5. Subscribe to bot events

Go to Features → Event Subscriptions and enable events.

Subscribe to these bot events:

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

Plus, for the agent surface, the events that say someone opened the pane and where they are looking. Subscribe the pair that matches your manifest key — subscribing all four is harmless and covers either:

• agent_view: app_context_changed (and app_home_opened, already above)
• assistant_view: assistant_thread_started, assistant_thread_context_changed

Without them the pane has no suggested prompts and its conversations stay untitled in the sidebar.

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-compact → summarize older messages to free up context
• /pi-session → session viewer
• /pi-model → switch this conversation’s LLM (provider/model[:thinking], for example anthropic/claude-sonnet-4-6:off)
• /pi-sandbox → inspect or tune this conversation’s sandbox
• /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 — then:

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

mikan

mikan keeps its state in ~/.mikan, and the working directory defaults to ~/.mikan/workspace; pass a path argument to change it. 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.

9. Choose a sandbox

Without --sandbox, mikan runs tools directly on the host. Office visibility follows the Slack conversation type: public channels are public offices that write the shared MEMORY.md and skills/, while private channels and DMs are private offices that only read them and cannot be read by any other office. Host mode cannot enforce private offices; it runs them with a one-time logged warning. Pick one before your first real conversation:

• Recommended. Use the managed sandbox, which gives each conversation its own container and enforces office visibility with no settings change:

  mikan --sandbox=oci

• Host mode, only on a machine you already trust with the whole workspace: every conversation, including DMs and private channels, can read every other conversation’s files.

See Sandbox for the full comparison.