Setting up the Slack Bot

Relevant source files

The following files were used as context for generating this wiki page:

• packages/mom/README.md
• packages/mom/src/main.ts
• packages/mom/src/slack.ts
• packages/mom/src/agent.ts
• packages/mom/src/log.ts
• AGENTS.md

The mom (Master Of Mischief) package provides a self-managing Slack bot powered by the Claude language model. It can execute bash commands, manage files, and interact with a development environment through Slack. The bot is designed to be minimal, building its own tools and managing its own workspace, including installing dependencies and configuring credentials autonomously.

This document outlines the necessary steps to configure and run the mom Slack bot, its architecture, and its core operational flows. The bot connects to Slack via Socket Mode, responds to @mentions and direct messages, and uses a persistent data directory to maintain context, conversation history, and custom-created tools (skills).

Sources: packages/mom/README.md

1. Configuration

1.1. Environment Variables

The bot requires several environment variables to be set for connecting to Slack and the Anthropic API.

Variable	Description	Required
MOM_SLACK_APP_TOKEN	The Slack app-level token, starting with xapp-....	Yes
MOM_SLACK_BOT_TOKEN	The Slack bot user OAuth token, starting with xoxb-....	Yes
ANTHROPIC_API_KEY	The Anthropic API key.	Yes (or ANTHROPIC_OAUTH_TOKEN)
ANTHROPIC_OAUTH_TOKEN	An alternative Anthropic OAuth token.	Yes (or ANTHROPIC_API_KEY)

Sources: packages/mom/README.md, packages/mom/src/agent.ts:43-49

1.2. Slack App Setup

A new Slack app must be created and configured with the correct permissions and event subscriptions.

1. Create a Slack App: Go to https://api.slack.com/apps to create a new app.
2. Enable Socket Mode: In "Settings" -> "Socket Mode", enable the feature.
3. Generate App-Level Token: Create an app-level token with the connections:write scope. This token is used for MOM_SLACK_APP_TOKEN.
4. Configure Bot Token Scopes: Under "OAuth & Permissions", add the following bot token scopes:
   • app_mentions:read
   • channels:history
   • channels:read
   • chat:write
   • files:read
   • files:write
   • groups:history
   • groups:read
   • im:history
   • im:read
   • im:write
   • users:read
5. Subscribe to Bot Events: Under "Event Subscriptions", subscribe to these events:
   • app_mention
   • message.channels
   • message.groups
   • message.im
6. Install App: Install the app to your workspace to get the "Bot User OAuth Token" for MOM_SLACK_BOT_TOKEN.
7. Add to Channels: Invite the bot to any channels where it should be active.

Sources: packages/mom/README.md

2. Running the Bot

The bot is executed via the mom command-line interface. It is highly recommended to run the bot in an isolated Docker container to protect the host system.

2.1. CLI Options

The mom executable takes a working directory and an optional sandbox configuration.

mom [options] <working-directory>

Option	Description
--sandbox=host	Run tools directly on the host machine. Not recommended.
--sandbox=docker:<name>	Run tools inside a specified Docker container. Recommended.

Sources: packages/mom/README.md

2.2. Quick Start (Docker Mode)

1. Set Environment Variables:

   export MOM_SLACK_APP_TOKEN=xapp-...
   export MOM_SLACK_BOT_TOKEN=xoxb-...
   export ANTHROPIC_API_KEY=sk-ant-...
   

2. Create and Run a Docker Sandbox:
   This command starts a persistent Alpine Linux container named mom-sandbox and mounts a local ./data directory to /workspace inside the container.

   docker run -d \
     --name mom-sandbox \
     -v $(pwd)/data:/workspace \
     alpine:latest \
     tail -f /dev/null
   

3. Run the Bot:
   This command starts the bot and connects it to the mom-sandbox Docker container, using ./data as the persistent working directory.

   mom --sandbox=docker:mom-sandbox ./data
   

Sources: packages/mom/README.md

3. Architecture

The mom bot's architecture is composed of several key components that handle Slack communication, agent execution, and data persistence.

The following diagram illustrates the high-level architecture of the bot.

3.1. Event Handling

The MomBot class connects to Slack using Socket Mode and listens for incoming events. The primary events handled are app_mention (for public/private channels) and message (for direct messages and logging).

When a relevant message is received, the following sequence occurs:

This diagram shows the flow from a user mentioning the bot to receiving a response.

Sources: packages/mom/src/slack.ts:233-294

3.2. Agent Execution

The AgentRunner is responsible for a single conversational turn. For each incoming message, it performs these steps:

1. Prepare Context: It gathers recent messages, memory files, and constructs a detailed system prompt.
2. Create Agent: An ephemeral Agent instance is created with the context and tools.
3. Run Prompt: The user's message (prepended with recent history) is sent to the agent.
4. Handle Events: It subscribes to agent events to post "thinking" steps, tool usage, and final responses to Slack.
5. Log Everything: All user messages, tool calls, and bot responses are logged to the console and the channel's log.jsonl file.

The agent execution flow is visualized below.

3.3. Data Persistence (Workspace)

The bot uses a dedicated data directory to persist all information. This ensures context is maintained across restarts and allows for inspection and manual editing.

The directory structure is organized by Slack channel ID.

<working-directory>/
  ├── MEMORY.md                 # Global memory (shared across all channels)
  ├── skills/                   # Global custom CLI tools
  └── <channel_id>/             # e.g., C123ABC
      ├── MEMORY.md             # Channel-specific memory
      ├── log.jsonl             # Full conversation history for the channel
      ├── attachments/          # Files shared by users in the channel
      ├── scratch/              # Bot's working directory for this channel
      └── skills/               # Channel-specific custom CLI tools

• MEMORY.md: These files store long-term context. The agent reads both the global and channel-specific memory files to build its system prompt.
• log.jsonl: A file containing every message, tool call, and tool result as a JSON object on a new line. This provides the agent with a searchable history.
• skills/: Directories for custom CLI tools the bot creates for itself.

Sources: packages/mom/README.md, packages/mom/src/agent.ts:202-236

log.jsonl Format

Each line in log.jsonl is a JSON object with the following structure, allowing the bot to query its own history.

Field	Type	Description
date	string	ISO 8601 timestamp (e.g., "2025-11-26T10:44:00.123Z").
ts	string	Slack timestamp (e.g., "1732619040.123456"). Used for sorting.
user	string	User ID or "bot".
userName	string	User's handle (e.g., "mario").
text	string	The message content. For tools, this includes [Tool] or [Tool Result].
attachments	Array	List of attachments with original and local file paths.
isBot	boolean	true if the message is from the bot, false otherwise.

Sources: packages/mom/README.md, packages/mom/src/agent.ts:53-60

3.4. System Prompt

A detailed system prompt is constructed for every agent run. It provides the agent with all the necessary context to perform its tasks. The prompt includes:

• Current date and time.
• Slack channel and user ID mappings.
• A description of the execution environment (Docker or host).
• The workspace directory layout.
• Instructions on creating and using "skills" (custom CLI tools).
• The content of global and channel-specific MEMORY.md files.
• Critical instructions for querying log.jsonl using jq to manage context size.
• Definitions of available tools (bash, read, write, etc.).

Sources: packages/mom/src/agent.ts:238-360, AGENTS.md

3.5. Logging

The bot provides structured, color-coded console logging for real-time monitoring. The log.ts module centralizes all logging functions.

• User Messages: Logged in green.
• Bot Activity: Logged in yellow (tool usage, thinking, responses).
• System Info: Logged in blue (startup, connection status).
• Details: Dimmed text for arguments and truncated results.

This structured logging helps developers trace the bot's actions and debug issues.

Sources: packages/mom/src/log.ts

4. Security Considerations

Running a bot with shell access carries significant security risks.

• Prompt Injection: The bot can be tricked into executing malicious commands or leaking credentials.
• Docker vs. Host Mode: Docker mode is strongly recommended to isolate the bot's execution environment and limit its access to the host system. Host mode gives the bot full access to the user's machine.
• Access Control: For different security contexts, it is advised to run multiple, isolated mom instances, each with its own data directory, container, and set of credentials.

Sources: packages/mom/README.md