co-mono/packages/mom/README.md

@mariozechner/pi-mom

A Slack bot powered by Claude that can execute bash commands, read/write files, and interact with your development environment. Designed to be your helpful team assistant.

Features

• Slack Integration: Responds to @mentions in channels and DMs
• Full Bash Access: Execute any command, install tools, configure credentials
• File Operations: Read, write, and edit files
• Docker Sandbox: Optional isolation to protect your host machine
• Persistent Workspace: Each channel gets its own workspace that persists across conversations
• Thread-Based Details: Clean main messages with verbose tool details in threads

Installation

npm install @mariozechner/pi-mom

Quick Start

# Set environment variables
export MOM_SLACK_APP_TOKEN=xapp-...
export MOM_SLACK_BOT_TOKEN=xoxb-...
export ANTHROPIC_API_KEY=sk-ant-...
# or use your Claude Pro/Max subscription
# to get the token install Claude Code and run claude setup-token
export ANTHROPIC_OAUTH_TOKEN=sk-ant-...

# Run mom
mom ./data

Slack App Setup

1. Create a new Slack app at https://api.slack.com/apps
2. Enable Socket Mode (Settings → Socket Mode → Enable)
3. Generate an App-Level Token with connections:write scope → this is MOM_SLACK_APP_TOKEN
4. Add Bot Token Scopes (OAuth & Permissions):
   • app_mentions:read
   • channels:history
   • channels:read
   • chat:write
   • files:read
   • files:write
   • im:history
   • im:read
   • im:write
   • users:read
5. Subscribe to Bot Events (Event Subscriptions):
   • app_mention
   • message.channels
   • message.im
6. Install the app to your workspace → get the Bot User OAuth Token → this is MOM_SLACK_BOT_TOKEN

Usage

Host Mode (Default)

Run tools directly on your machine:

mom ./data

Docker Sandbox Mode

Isolate mom in a container to protect your host:

# Create the sandbox container
./docker.sh create ./data

# Run mom with sandbox
mom --sandbox=docker:mom-sandbox ./data

Talking to Mom

In Slack:

@mom what's in the current directory?
@mom clone the repo https://github.com/example/repo and find all TODO comments
@mom install htop and show me system stats

Mom will:

1. Show brief status updates in the main message
2. Post detailed tool calls and results in a thread
3. Provide a final response

Stopping Mom

If mom is working on something and you need to stop:

@mom stop

CLI Options

mom [options] <working-directory>

Options:
  --sandbox=host              Run tools on host (default)
  --sandbox=docker:<name>     Run tools in Docker container

Docker Sandbox

The Docker sandbox treats the container as mom's personal computer:

• Persistent: Install tools with apk add, configure credentials - changes persist
• Isolated: Mom can only access /workspace (your data directory)
• Self-Managing: Mom can install what she needs and ask for credentials

Container Management

./docker.sh create <data-dir>   # Create and start container
./docker.sh start               # Start existing container
./docker.sh stop                # Stop container
./docker.sh remove              # Remove container
./docker.sh status              # Check if running
./docker.sh shell               # Open shell in container

Example Flow

User: @mom check the spine-runtimes repo on GitHub
Mom:  I need gh CLI. Installing...
      (runs: apk add github-cli)
Mom:  I need a GitHub token. Please provide one.
User: ghp_xxxx...
Mom:  (configures gh auth)
Mom:  Done. Here's the repo info...

Workspace Structure

Each Slack channel gets its own workspace:

./data/
  └── C123ABC/                    # Channel ID
      ├── log.jsonl               # Message history (managed by mom)
      ├── attachments/            # Files shared in channel
      └── scratch/                # Mom's working directory

Environment Variables

Variable	Description
MOM_SLACK_APP_TOKEN	Slack app-level token (xapp-...)
MOM_SLACK_BOT_TOKEN	Slack bot token (xoxb-...)
ANTHROPIC_API_KEY	Anthropic API key
ANTHROPIC_OAUTH_TOKEN	Alternative: Anthropic OAuth token

Security Considerations

Host Mode: Mom has full access to your machine. Only use in trusted environments.

Docker Mode: Mom is isolated to the container. She can:

• Read/write files in /workspace (your data dir)
• Make network requests
• Install packages in the container

She cannot:

• Access files outside /workspace
• Access your host credentials
• Affect your host system

Recommendations:

1. Use Docker mode for shared Slack workspaces
2. Create a dedicated GitHub bot account with limited repo access
3. Only share necessary credentials with mom

License

MIT