Agent Slack

A TypeScript CLI tool that enables AI agents and humans to interact with Slack workspaces through a simple command interface. Features seamless token extraction from the Slack desktop app and multi-workspace support.

Quick Start

CODEBLOCK0

Authentication

Credentials are extracted automatically from the Slack desktop app on first use. No manual setup required — just run any command and authentication happens silently in the background.

On macOS, the system may prompt for your Keychain password the first time (required to decrypt Slack's stored token). This is a one-time prompt.

IMPORTANT: NEVER guide the user to open a web browser, use DevTools, or manually copy tokens from a browser. Always use agent-slack auth extract to obtain tokens from the desktop app.

Multi-Workspace Support

CODEBLOCK1

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 workspace list)
• After discovering useful channel IDs and names (from channel list, snapshot, etc.)
• After discovering user IDs and names (from user list, user me, etc.)
• After the user gives you an alias or preference ("call this the deploys channel", "my main workspace is X")
• After discovering channel structure (sidebar sections, channel categories)

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
• User-given aliases ("deploys channel", "main workspace")
• Commonly used thread timestamps
• Any user preference expressed during interaction

What NOT to Store

Never store tokens, cookies, 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

CODEBLOCK2

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

Commands

Auth Commands

CODEBLOCK3

Message Commands

CODEBLOCK4

Channel Commands

CODEBLOCK5

User Commands

CODEBLOCK6

Reaction Commands

CODEBLOCK7

File Commands

CODEBLOCK8

Unread Commands

CODEBLOCK9

Activity Commands

CODEBLOCK10

Saved Items Commands

CODEBLOCK11

Drafts Commands

CODEBLOCK12

Channel Sections Commands

CODEBLOCK13

Snapshot Command

Get comprehensive workspace state for AI agents:

CODEBLOCK14

Returns JSON with:

• - Workspace metadata
• Channels (id, name, topic, purpose)
• Recent messages (ts, text, user, channel)
• Users (id, name, profile)

Output Format

JSON (Default)

All commands output JSON by default for AI consumption:

CODEBLOCK15

Pretty (Human-Readable)

Use --pretty flag for formatted output:

CODEBLOCK16

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

Error Handling

All commands return consistent error format:

CODEBLOCK17

Common errors:

• - NO_WORKSPACE: No authenticated workspace (auto-extraction failed — see Troubleshooting)
• INLINECODE24: Slack API returned an error
• INLINECODE25: Hit Slack rate limit (auto-retries with backoff)

Configuration

Credentials stored in: INLINECODE26

Format:
CODEBLOCK18

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

Limitations

• - No real-time events / Socket Mode
• No channel management (create/archive)
• No workspace admin operations
• No scheduled messages
• No user presence features
• Plain text messages only (no blocks/formatting in v1)

Troubleshooting

Authentication fails or no workspace found

Credentials are normally extracted automatically. If auto-extraction fails, run it manually with debug output:

CODEBLOCK19

Common causes:

• - Slack desktop app is not installed or not logged in
• macOS Keychain access was denied (re-run and approve the prompt)
• Slack was installed via a method that uses a different storage path

agent-slack: command not found

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

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

CODEBLOCK20

If the package is NOT installed, use bunx agent-messenger slack (note: slack subcommand, not agent-slack):

CODEBLOCK21

NEVER run bunx agent-slack — a separate, unrelated npm package named agent-slack exists on npm. It will silently install the wrong package with different (fewer) commands.

References

• - Authentication Guide
• Common Patterns