Connecting Slack

You talk to Wheems through Slack. By the end of this page you will have a Slack app called Wheems in your Slack workspace, its two tokens saved on your Mac, yourself on the list of people allowed to talk to agents, and a chief of staff answering you in Slack.

It takes about ten minutes, most of it in Slack’s app settings. You do it once: one Slack app serves every Wheems workspace.

You need:

• Wheems installed, with wheems doctor passing its System and Herdr core sections. See Installation.
• At least one engine installed and signed in (Claude Code, Codex or opencode). wheems setup → Engines does this. See Engines and accounts.
• A Slack workspace where you’re allowed to add apps. On some company Slack workspaces only admins can, or apps need an admin’s approval. A free Slack workspace of your own works well.
• The Slack desktop app or slack.com in a browser, signed in to that Slack workspace.

Wheems connects to Slack with Socket Mode. The Wheems service on your Mac opens a connection out to Slack, and Slack sends messages down it. Nothing connects in to your Mac, so you need no public address, no domain and no open port.

That needs two tokens, and Wheems checks both with Slack before saving them:

The bot is the app’s user in Slack. You message it directly, or invite it to a channel. Its answers appear under the bot’s name, or under your workspace’s own name and icon (see Identities).

wheems slack manifest prints the manifest. It’s the same one setup copies to your clipboard and saves to ~/wheems/.wheems/slack-app-manifest.yaml:

display_information:
  name: Wheems
  description: Your agents' chief of staff, from Wheems.
  background_color: "#2c2d30"
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: Wheems
    always_online: true
oauth_config:
  scopes:
    bot:
      - chat:write
      - chat:write.customize
      - im:history
      - im:read
      - im:write
      - channels:history
      - channels:read
      - groups:history
      - groups:read
      - reactions:write
      - users:read
settings:
  event_subscriptions:
    bot_events:
      - message.im
      - message.channels
      - message.groups
  interactivity:
    is_enabled: true
  org_deploy_enabled: false
  socket_mode_enabled: true
  token_rotation_enabled: false

Wheems acts only on plain messages from people. Edits, deletions, joins, other bots’ posts and its own posts are ignored.

Setup writes the tokens to a secrets file outside your install folder, so they’re never committed and never part of what an agent is given:

{
  "slack": {
    "bot_token": "xoxb-…",
    "app_token": "xapp-…"
  }
}

• The file is readable only by you (mode 600), in a folder only you can open (mode 700).
• It lives in $XDG_CONFIG_HOME/wheems/ when XDG_CONFIG_HOME is set. Set WHEEMS_SECRETS to use another file.
• slack is the entry’s name. secret: slack in install.yaml points the connection at it; without secret, the connection’s own name is used.
• Tokens never pass through an agent: you type them into setup, and only the service reads them. They aren’t in any agent’s instructions, notes or knowledge base.

Rotate a token when it may have leaked, or when someone who had it leaves.

allowed_users in install.yaml lists the Slack member IDs that may talk to agents. Everyone else is ignored: no reaction, no answer. The service log records each ignored message:

2026-11-13T09:12:04.512Z Ignored a message on slack from U034GHIJKL, who is not in allowed_users

A member ID starts with U or W, then letters and digits, such as U012ABCDEF. It isn’t your display name or email.

Setup asks for one member ID, the first time. To allow more people, edit the list by hand, then restart the service:

connections:
  slack:
    driver: slack
    secret: slack
    allowed_users: [U012ABCDEF, U034GHIJKL]

wheems validate
wheems service restart

Everyone on the list can talk to every workspace’s chief of staff. Wheems is built for one person today; roles for several people per workspace are planned for after version one.

Each workspace’s workspace.yaml says where you chat with its chief of staff, in channels.chat:

channels:
  chat: { connection: slack, direct: true }

channels:
  chat: { connection: slack, channel: acme-chat }

• direct: true means the bot’s direct messages. Only one workspace per Slack app can have them. wheems init gives them to the first workspace, and refuses a second without --channel.

• channel takes a name (acme-chat or #acme-chat) or a channel id (C0123ABCD for public, G0123ABCD for private). An id keeps working if the channel is renamed.

• Public and private channels both work. Invite the bot to either: /invite @Wheems.

• The service finds each channel when it starts. If it can’t find one, it logs this and skips the workspace until the next start:

  Workspace acme: the bot cannot see channel acme-chat; invite it to the channel

  When it does find it:

  Workspace acme: chat on slack C0123ABCD

• In a bound channel, every new message from an allowed person starts a conversation. You don’t need to mention the bot. Keep the channel for talking to the chief of staff.

To move a workspace to another channel, change channels.chat, invite the bot there, and restart the service.

• Each new message starts a conversation. In direct messages and in a channel alike, a message that isn’t in a thread is a new conversation, with an engine session of its own.
• Reply in the thread to carry on. Wheems answers in your message’s thread, and every reply in that thread goes to the same session, with everything said so far. A new top-level message starts afresh.
• 👀 means it has reached the agent. It goes when the agent answers.
• Answers come from the engine’s own record, not the screen. The agent’s last message of each turn is posted as its answer. Long answers are split into several posts.
• Progress notes. For long work, the agent posts a short note first with wheems reply "…".
• Messages while it’s working are passed on when it finishes its turn.
• Notices from Wheems itself start with Wheems:, such as when the agent is waiting for an answer at the Mac.
• Each conversation is a Herdr session. Watch it, or take over, with the command Wheems gives in its notices, such as hc attach t7. hc ls lists them; their names start with the workspace id.
• At most four sessions per workspace run at once. The least recently used idle one is stopped to make room, and its conversation resumes where it left off when you next reply in its thread.
• Restarts don’t lose threads. Which thread belongs to which session is kept in ~/wheems/.wheems/conversations.json, so a reply after a restart, or days later, resumes the same conversation.
• Quiet conversations write a note. After 30 minutes without new messages, Wheems asks the agent for a note for the knowledge base, as a turn of its own. That turn’s answer is never posted to Slack. See Knowledge base and search.

You create the Slack app once. Every Wheems workspace binds a channel on it: one gets its direct messages, the rest get a channel each. The tokens are saved once, under the connection slack in install.yaml.

wheems setup and wheems init assume this one connection, named slack. Connecting a second Slack workspace isn’t supported by setup today.

Each workspace’s posts can appear under its own name and icon, through the chat:write.customize scope. wheems init sets the name; add an icon if you like:

identity: { name: Acme chief of staff, icon: ':office:' }

icon is an emoji code such as :house:, or the URL of an image. Without identity, answers appear under the bot’s own name. Notices from Wheems (Wheems: …) always use the bot’s own name.

Work down this list after connecting Slack, or whenever something seems wrong.

Start with wheems doctor and wheems service logs. Most problems show up in one of them.

Wheems works on Slack’s free plan:

• Apps: a free Slack workspace can add up to 10 apps and integrations. Wheems uses one, however many Wheems workspaces you have.
• History: a free plan shows the last 90 days of messages. Older threads disappear from view. What matters is kept on your Mac: conversations in ~/wheems/.wheems/conversations.json and what was learned in each workspace’s knowledge base.
• Channels: each workspace after the first needs a channel. Projects with their own lead and channel (milestone 4) will need more.

• Quick start: the rest of setup, from nothing to a first reply.
• Running as a service: logs, restarts and launchd.
• Configuration reference: every key in install.yaml and workspace.yaml.