Muse Slack Bridge

Shared, bot-agnostic transport between Slack and Muse AI bots.

One listener daemon (slackd.py) receives Slack events over Socket Mode and appends them to events.jsonl. One post CLI (slack-post.py) sends text back, verbatim. Bots never talk to Slack or a browser. Each bot runs its own consumer over the shared log, with its own offset file and its own rules.

The bridge knows nothing about any particular bot's prefixes, reply policy, or conventions.

There is no public HTTP endpoint. Socket Mode does not need one.

Layout

slackd.py              # shared listener → events.jsonl
slack-post.py          # shared post CLI
example_consumer.py    # reference per-bot loop (~offset + rules)
manifest.json          # Slack app manifest
contrib/               # systemd user unit + cron healthcheck
muse_slack_bridge/     # library used by the scripts

One-time Slack app setup

1. Open api.slack.com/apps → Create New App → From an app manifest.
2. Paste manifest.json from this repo and create the app.
3. Basic Information → App-Level Tokens → generate a token with the connections:write scope. Copy the xapp- value.
4. OAuth & Permissions → Install to Workspace. Copy the bot token (xoxb-).
5. Invite the app to every channel it should see (/invite @Muse Bridge). Private channels are invisible until invited.

The committed manifest enables Socket Mode and subscribes to message.groups only (chat:write, groups:history, groups:read, users:read). Invite the app into each private channel it should see. It does not include a request URL or interactivity.

Configure

Tokens live in the process environment or in chmod-600 files. Never commit them. Never paste them into chat.

Default config directory: ~/.config/muse-slack-bridge/
Override with MUSE_SLACK_BRIDGE_HOME or --config-dir.

mkdir -p ~/.config/muse-slack-bridge
chmod 700 ~/.config/muse-slack-bridge

# Option A — environment
export SLACK_APP_TOKEN="xapp-..."
export SLACK_BOT_TOKEN="xoxb-..."
export WATCH_CHANNELS="C0123456789,C9876543210"

# Option B — files (must be chmod 600 or the listener refuses to start)
printf '%s\n' "$SLACK_APP_TOKEN" > ~/.config/muse-slack-bridge/app_token
printf '%s\n' "$SLACK_BOT_TOKEN" > ~/.config/muse-slack-bridge/bot_token
printf '%s\n' "$WATCH_CHANNELS" > ~/.