Agent SlackBot

A TypeScript CLI tool that enables AI agents and humans to interact with Slack workspaces using bot tokens (xoxb-). Unlike agent-slack which extracts user tokens from the desktop app, agent-slackbot uses standard Slack Bot tokens for server-side and CI/CD integrations.

Key Concepts

Before diving in, a few things about Slack Bot integration:

Bot tokens (xoxb-) — Issued from the Slack App config (api.slack.com/apps). Bots act as the bot user, not as you. Different name, different permissions, different identity.
Workspace + Bot hierarchy — Each workspace can have multiple bot tokens (one per Slack App). The CLI stores bots under their workspace and lets you switch between them.
Channel access requires invitation — Bots must be invited to private channels with /invite @YourBotName before they can read or post.
Bot scopes are immutable per-token — Token capabilities are baked in at App creation. Adding a new scope means re-installing the App and refreshing the token.
Edit/delete is bot-scoped — A bot can only edit/delete messages it sent. It cannot modify other users' messages.
Real-time events — Available via the SDK's Socket Mode listener (separate xapp- app-level token required), not via the CLI.

Quick Start

# Set your bot token
agent-slackbot auth set xoxb-your-bot-token

# Or set with a custom bot identifier for multi-bot setups
agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"

# Verify authentication
agent-slackbot auth status

# Send a message
agent-slackbot message send C0ACZKTDDC0 "Hello from bot!"

# List channels
agent-slackbot channel list

Authentication

Bot Token Setup

agent-slackbot uses Slack Bot tokens (xoxb-) which you get from the Slack App configuration:

# Set bot token (validates against Slack API before saving)
agent-slackbot auth set xoxb-your-bot-token

# Set with a custom bot identifier
agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"

# Check auth status
agent-slackbot auth status

# Clear stored credentials
agent-slackbot auth clear

Multi-Bot Management

Store multiple bot tokens and switch between them:

# Add multiple bots
agent-slackbot auth set xoxb-deploy-token --bot deploy --name "Deploy Bot"
agent-slackbot auth set xoxb-alert-token --bot alert --name "Alert Bot"

# List all stored bots
agent-slackbot auth list

# Switch active bot
agent-slackbot auth use deploy

# Use a specific bot for one command (without switching)
agent-slackbot message send C0ACZKTDDC0 "Alert!" --bot alert

# Remove a stored bot
agent-slackbot auth remove deploy

# Disambiguate bots with same ID across workspaces
agent-slackbot auth use T123456/deploy

The --bot <id> flag is available on all commands to override the active bot for a single invocation.

For bot token setup (Slack App creation, required scopes, app manifest) and CI/CD environment variables, see references/authentication.md.

Memory

The agent maintains a ~/.config/agent-messenger/MEMORY.md file as persistent memory across sessions. This is agent-managed — the CLI does not read or write this file. Use the Read and Write tools to manage your memory file.

Reading Memory

At the start of every task, read ~/.config/agent-messenger/MEMORY.md using the Read tool to load any previously discovered workspace IDs, channel IDs, user IDs, and preferences.

If the file doesn't exist yet, that's fine — proceed without it and create it when you first have useful information to store.
If the file can't be read (permissions, missing directory), proceed without memory — don't error out.

Writing Memory

After discovering useful information, update ~/.config/agent-messenger/MEMORY.md using the Write tool. Write triggers include:

After discovering workspace IDs (from auth status)
After discovering useful channel IDs and names (from channel list, etc.)
After discovering user IDs and names (from user list, etc.)
After the user gives you an alias or preference ("call this the alerts bot", "my main workspace is X")
After setting up bot identifiers (from auth list)

When writing, include the complete file content — the Write tool overwrites the entire file.

What to Store

Workspace IDs with names
Channel IDs with names and purpose
User IDs with display names
Bot identifiers and their purposes
User-given aliases ("alerts bot", "deploys channel")
Any user preference expressed during interaction

What NOT to Store

Never store bot tokens, credentials, or any sensitive data. Never store full message content (just IDs and channel context). Never store file upload contents.

Handling Stale Data

If a memorized ID returns an error (channel not found, user not found), remove it from MEMORY.md. Don't blindly trust memorized data — verify when something seems off. Prefer re-listing over using a memorized ID that might be stale.

Format / Example

# Agent Messenger Memory

## Slack Workspaces (Bot)

- `T0ABC1234` — Acme Corp

## Bots (Acme Corp)

- `deploy` — Deploy Bot (active)
- `alert` — Alert Bot

## Channels (Acme Corp)

- `C012ABC` — #general (company-wide announcements)
- `C034DEF` — #engineering (team discussion)
- `C056GHI` — #deploys (CI/CD notifications)

## Users (Acme Corp)

- `U0ABC123` — Alice (engineering lead)
- `U0DEF456` — Bob (backend)

## Aliases

- "deploys" → `C056GHI` (#deploys in Acme Corp)

## Notes

- Deploy Bot is used for CI/CD notifications
- Alert Bot is used for error monitoring

Memory lets you skip repeated channel list and auth list calls. When you already know an ID from a previous session, use it directly.

Commands

Whoami Command

# Show current authenticated bot
agent-slackbot whoami
agent-slackbot whoami --pretty
agent-slackbot whoami --bot <bot-id>

Message Commands

# Send a message
agent-slackbot message send <channel> <text>
agent-slackbot message send C0ACZKTDDC0 "Hello world"

# Send a threaded reply
agent-slackbot message send C0ACZKTDDC0 "Reply" --thread <ts>

# List messages
agent-slackbot message list <channel>
agent-slackbot message list C0ACZKTDDC0 --limit 50

# Get a single message by timestamp
agent-slackbot message get <channel> <ts>

# Get thread replies (includes parent message)
agent-slackbot message replies <channel> <thread_ts>
agent-slackbot message replies C0ACZKTDDC0 1234567890.123456 --limit 50

# Update a message (bot's own messages only)
agent-slackbot message update <channel> <ts> <new-text>

# Delete a message (bot's own messages only)
agent-slackbot message delete <channel> <ts> --force

# Show typing/status indicator in an AI Assistant thread
agent-slackbot message typing <channel> <thread_ts>
agent-slackbot message typing <channel> <thread_ts> "is analyzing..."
agent-slackbot message typing <channel> <thread_ts> ""   # clear status

Typing indicators: message typing calls Slack's assistant.threads.setStatus API. It only works inside AI Assistant threads (not regular channels/DMs) and requires the chat:write bot scope. The status auto-clears when your bot posts the next message, or after 2 minutes if no message is sent. Pass an empty string "" to clear the status manually.

Channel Commands

# List channels the bot can see
agent-slackbot channel list
agent-slackbot channel list --limit 50

# Get channel info
agent-slackbot channel info <channel>
agent-slackbot channel info C0ACZKTDDC0

User Commands

# List users
agent-slackbot user list
agent-slackbot user list --limit 50

# Get user info
agent-slackbot user info <user-id>

Reaction Commands

# Add reaction
agent-slackbot reaction add <channel> <ts> <emoji>
agent-slackbot reaction add C0ACZKTDDC0 1234567890.123456 thumbsup

# Remove reaction
agent-slackbot reaction remove <channel> <ts> <emoji>

File Commands

# Upload a file to a channel (requires files:write scope)
agent-slackbot file upload <channel> <path>
agent-slackbot file upload C0ACZKTDDC0 ./report.pdf
agent-slackbot file upload C0ACZKTDDC0 ./log.txt --filename build-log.txt
agent-slackbot file upload C0ACZKTDDC0 ./screenshot.png --thread 1234567890.123456 --comment "FYI"

# List files visible to the bot (requires files:read scope)
agent-slackbot file list
agent-slackbot file list --channel C0ACZKTDDC0
agent-slackbot file list --user U123 --limit 50

# Show file details
agent-slackbot file info <file-id>

# Download a file by ID (saves to current dir or given path)
agent-slackbot file download <file-id>
agent-slackbot file download F0123ABC ./downloads/

# Delete a file (bot's own files only)
agent-slackbot file delete <file-id> --force

File scopes: file upload requires files:write; file list, file info, and file download require files:read. Add these to your Slack App's bot token scopes and reinstall the app. The bot can only delete files it uploaded.

Output Format

JSON (Default)

All commands output JSON by default for AI consumption:

{
  "ts": "1234567890.123456",
  "channel": "C0ACZKTDDC0",
  "text": "Hello world"
}

Pretty (Human-Readable)

Use --pretty flag for formatted output:

agent-slackbot channel list --pretty

Global Options

Option	Description
`--pretty`	Human-readable output instead of compact JSON
`--bot <id>`	Use a specific bot for this command (workspace/bot)

Common Patterns

See references/common-patterns.md for typical AI agent workflows.

Templates

See templates/ directory for runnable examples:

post-message.sh - Send messages with error handling
monitor-channel.sh - Monitor channel for new messages
workspace-summary.sh - Generate workspace summary

Error Handling

All commands return consistent error format:

{
  "error": "No credentials. Run \"auth set\" first."
}

Common errors:

missing_token: No credentials configured
invalid_token_type: Token is not a bot token (must start with xoxb-)
not_in_channel: Bot needs to join the channel first
slack_webapi_rate_limited_error: Hit rate limit (auto-retries with backoff)

Configuration

Credentials stored in ~/.config/agent-messenger/slackbot-credentials.json (0600 permissions). See references/authentication.md for format and security details.

Key Differences from agent-slack

Feature	agent-slack	agent-slackbot
Token type	User token (xoxc-)	Bot token (xoxb-)
Token source	Auto-extracted from desktop app	Manual from Slack App config
Message search	Yes	No (requires user token)
File operations	Yes	Upload/list/info/download/delete (with scopes)
Snapshot	Yes	No
Edit/delete messages	Any message	Bot's own messages only
Workspace management	Multi-workspace	Multi-bot, multi-workspace
CI/CD friendly	Requires desktop app	Yes (just set token)

Limitations

No real-time events in the CLI (real-time Socket Mode events are available via the SDK — see the README's "Real-time Events (Slack Bot)" section)
No message search (requires user token scope)
File operations require files:read / files:write scopes; bot can only delete files it uploaded
No workspace snapshot
Bot can only edit/delete its own messages
Bot must be invited to private channels
No scheduled messages
Plain text messages only (no blocks/formatting)

Troubleshooting

`agent-slackbot: command not found`

agent-slackbot is NOT the npm package name. The npm package is agent-messenger.

If the package is installed globally, use agent-slackbot directly:

agent-slackbot message send general "Hello"

If the package is NOT installed, use npx -y by default. Do NOT ask the user which package runner to use — just run it:

npx -y agent-messenger slackbot message send general "Hello"
bunx agent-messenger slackbot message send general "Hello"
pnpm dlx agent-messenger slackbot message send general "Hello"

If you already know the user's preferred package runner (e.g., bunx, pnpm dlx), use that instead.

NEVER run npx agent-slackbot, bunx agent-slackbot, or pnpm dlx agent-slackbot — it will fail or install a wrong package since agent-slackbot is not the npm package name.

For other troubleshooting (token issues, scopes, permissions), see references/authentication.md.

agent-slackbot