mama

A multi-platform AI agent bot for Slack, Telegram, and Discord — based on pi-mom, with the goal of merging improvements back upstream.

📜 Attribution & Origins

This project is a forked and extended version of the mom package from badlogic/pi-mono by Mario Zechner, licensed under MIT.

• Original project: pi-mom (22K+ stars)
• Base version: forked from pi-mom v0.57.1 (synchronized with @mariozechner/* packages)
• Primary motivation: Internal services urgently needed a multi-platform bot — this fork enables rapid iteration while preparing changes to contribute back upstream

🎯 Positioning & Roadmap

| Aspect | Description | | ------------------ | ------------------------------------------------------------------------------ | | Current Status | Temporary standalone fork for urgent internal deployment | | Ultimate Goal | Merge all improvements back into pi-mono monorepo | | Unique Value | Multi-platform support (Slack + Telegram + Discord) to be contributed upstream |

Why a temporary fork?

Our internal services urgently needed a multi-platform bot, and we couldn't wait for upstream release cycles. This fork allows us to:

1. Ship fast: Deploy to production immediately while internal demand is high
2. Iterate freely: Test multi-platform adapters (Slack, Telegram, Discord) without monorepo constraints
3. Contribute back: All work here is intended to be merged into pi-mono — mama is not a replacement for mom

Contribution Philosophy 🔄

"This is not a separate product — it's a temporary fork for urgent internal needs, and all improvements will be contributed back to pi-mono."

We actively track the upstream pi-mom and plan to:

• ✅ Submit PRs for platform adapters (Telegram, Discord)
• ✅ Contribute cross-platform abstractions
• ✅ Keep dependencies synchronized with pi-mono releases
• ✅ Document what we learn from production use

Features

• Multi-platform — Slack, Telegram, and Discord adapters out of the box
• Thread sessions — each thread / reply chain gets its own isolated conversation context
• Concurrent threads — multiple threads in the same channel run independently
• Sandbox execution — run agent commands on host or inside a Docker container
• Persistent memory — workspace-level and channel-level MEMORY.md files
• Skills — drop custom CLI tools into skills/ directories
• Event system — schedule one-shot or recurring tasks via JSON files
• Multi-provider — configure any provider/model supported by pi-ai

Requirements

• Node.js >= 20
• One of the platform integrations below

Installation

npm install -g @geminixiang/mama

Or run directly after cloning:

npm install
npm run build

Quick Start

Slack

1. Create a Slack app with Socket Mode enabled (setup guide).
2. Add the app_mentions:read, chat:write, files:write, and im:history OAuth scopes.
3. Enable the Home Tab:
   • App Home → Show Tabs — toggle Home Tab on
   • App Home → Agents & AI Apps — toggle Agent or Assistant on
   • Event Subscriptions → Subscribe to bot events — add app_home_opened
4. Copy the App-Level Token (xapp-…) and Bot Token (xoxb-…).

export MOM_SLACK_APP_TOKEN=xapp-...
export MOM_SLACK_BOT_TOKEN=xoxb-...

mama [--sandbox=host|docker:<container>] <working-directory>

The bot responds when @mentioned in any channel or via DM. Each Slack thread is a separate session.

Telegram

1. Message @BotFather → /newbot to create a bot and get the Bot Token.
2. Optionally disable privacy mode (/setprivacy → Disable) so the bot can read group messages without being @mentioned.

export MOM_TELEGRAM_BOT_TOKEN=123456:ABC-...

mama [--sandbox=host|docker:<container>] <working-directory>

• Private chats — every message is forwarded to the bot automatically.
• Group chats — the bot only responds when @mentioned by username.
• Reply chains — replying to a previous message continues the same session.
• Say stop or /stop to cancel a running task.

Discord

1. Go to the Discord Developer Portal → New Application.
2. Under Bot, enable Message Content Intent (required to read message text).
3. Under OAuth2 → URL Generator, select scopes bot + permissions Send Messages, Read Message History, Attach Files. Invite the bot to your server with the generated URL.
4. Copy the Bot Token.

export MOM_DISCORD_BOT_TOKEN=MTI...

mama [--sandbox=host|docker:<container>] <working-directory>

• Server channels — the bot responds when @mentioned.
• DMs — every message is forwarded automatically.
• Threads — messages inside a Discord thread share a single session.
• Reply chains — replying to a message continues that session.
• Say stop or /stop to cancel a running task.

Options

| Option | Default | Description | | ------------------------- | ------- | -------------------------------------------------------- | | --sandbox=host | ✓ | Run commands directly on host | | --sandbox=docker:<name> | | Run commands inside a Docker container | | --download <channel-id> | | Download channel history to stdout and exit (Slack only) |

Download channel history (Slack)

mama --download C0123456789

Configuration

Create settings.json in your working directory to override defaults:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-5",
  "thinkingLevel": "off",
  "sessionScope": "thread"
}

| Field | Default | Description | | --------------- | ------------------- | ---------------------------------------------- | | provider | anthropic | AI provider (env: MOM_AI_PROVIDER) | | model | claude-sonnet-4-5 | Model name (env: MOM_AI_MODEL) | | thinkingLevel | off | off / low / medium / high | | sessionScope | thread | thread (per thread/reply chain) or channel |

Working Directory Layout

<working-directory>/
├── settings.json          # AI provider/model config
├── MEMORY.md              # Global memory (all channels)
├── SYSTEM.md              # Installed packages / env changes log
├── skills/                # Global skills (CLI tools)
├── events/                # Scheduled event files
└── <channel-id>/
    ├── MEMORY.md          # Channel-specific memory
    ├── log.jsonl          # Full message history
    ├── attachments/       # Downloaded user files
    ├── scratch/           # Agent working directory
    ├── skills/            # Channel-specific skills
    └── sessions/
        └── <thread-ts>/
            └── context.jsonl   # LLM conversation context

Docker Sandbox

# Create a container (mount your working directory to /workspace)
docker run -d --name mama-sandbox \
  -v /path/to/workspace:/workspace \
  alpine:latest sleep infinity

# Start mama with Docker sandbox
mama --sandbox=docker:mama-sandbox /path/to/workspace

Events

Drop JSON files into <working-directory>/events/ to trigger the agent:

// Immediate — triggers as soon as mama sees the file
{"type": "immediate", "channelId": "C0123456789", "text": "New deployment finished"}

// One-shot — triggers once at a specific time
{"type": "one-shot", "channelId": "C0123456789", "text": "Daily standup reminder", "at": "2025-12-15T09:00:00+08:00"}

// Periodic — triggers on a cron schedule
{"type": "periodic", "channelId": "C0123456789", "text": "Check inbox", "schedule": "0 9 * * 1-5", "timezone": "Asia/Taipei"}

Skills

Create reusable CLI tools by adding a directory with a SKILL.md:

skills/
└── my-tool/
    ├── SKILL.md    # name + description frontmatter, usage docs
    └── run.sh      # the actual script

SKILL.md frontmatter:

---
name: my-tool
description: Does something useful
---

Usage: {baseDir}/run.sh <args>

Development

npm run dev     # watch mode
npm test        # run tests
npm run build   # production build

📦 Dependencies & Versions

| Package | mama Version | pi-mom Synced Version | | ------------------------------- | ------------ | ----------------------------- | | @mariozechner/pi-agent-core | ^0.57.1 | ✅ Synchronized | | @mariozechner/pi-ai | ^0.57.1 | ✅ Synchronized | | @mariozechner/pi-coding-agent | ^0.57.1 | ✅ Synchronized | | @anthropic-ai/sandbox-runtime | ^0.0.40 | ⚠️ Newer (pi-mom uses 0.0.16) |

License

MIT — see LICENSE.

Note: This project inherits the MIT license from pi-mom and aims to keep its contributions compatible with the upstream ecosystem.