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.

Quick Start

CODEBLOCK0

Authentication

Bot Token Setup

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

CODEBLOCK1

Multi-Bot Management

Store multiple bot tokens and switch between them:

CODEBLOCK2

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

Getting a Bot Token

1. 1. Go to api.slack.com/apps
2. Create New App (or select existing)
3. Go to OAuth & Permissions
4. Add required bot token scopes (see below)
5. Install app to workspace
6. Copy the Bot User OAuth Token (starts with xoxb-)

Required Bot Token Scopes

Environment Variables (CI/CD)

For CI/CD pipelines, set these environment variables instead of using auth set:

CODEBLOCK3

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

CODEBLOCK4

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

Message Commands

CODEBLOCK5

Channel Commands

CODEBLOCK6

User Commands

CODEBLOCK7

Reaction Commands

CODEBLOCK8

Output Format

JSON (Default)

All commands output JSON by default for AI consumption:

CODEBLOCK9

Pretty (Human-Readable)

Use --pretty flag for formatted output:

CODEBLOCK10

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
• INLINECODE32 - Monitor channel for new messages
• INLINECODE33 - Generate workspace summary

Error Handling

All commands return consistent error format:

CODEBLOCK11

Common errors:

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

Configuration

Credentials stored in: INLINECODE38

Format:
CODEBLOCK12

Security: File permissions set to 0600 (owner read/write only)

Key Differences from agent-slack

Limitations

• - No real-time events / Socket Mode
• No message search (requires user token scope)
• No file upload/download
• 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:

CODEBLOCK13

If the package is NOT installed, use bunx agent-messenger slackbot:

CODEBLOCK14

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

References

• - Authentication Guide
• Common Patterns