Agent Slack

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 (with browser fallback) and multi-workspace support.

Quick Start

# Get workspace snapshot (credentials are extracted automatically)
agent-slack snapshot

# Send a message
agent-slack message send general "Hello from AI agent!"

# List channels
agent-slack channel list

Authentication

Credentials are extracted automatically from the Slack desktop app (or Chromium browser as fallback) 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.

Two ways to obtain tokens:

• agent-slack auth qr — recommended. Sign in with a QR code from Slack's "Sign in on mobile" screen. It's the safest and most reliable method: it authenticates through Slack's own login flow over plain HTTP instead of reading credentials off disk, and needs no desktop app or browser.
• agent-slack auth extract. Extracts tokens from the Slack desktop app first, falling back to Chromium browsers if the app isn't installed. Best for automated/headless environments.

QR Code Sign-In (Recommended)

Sign in with a QR code from any device where you're already logged into Slack — no desktop app, no browser automation, fully over HTTP:

# In Slack (desktop or web): your name (top-left) → "Sign in on mobile".
# Right-click the QR code → "Copy Image Address", then:
pbpaste | agent-slack auth qr

# Or pass the data URL directly:
agent-slack auth qr "data:image/png;base64,iVBORw0KGgo..."

This decodes the QR's one-time login link, establishes a session, and stores the resulting credentials like auth extract does. The QR link is single-use — generate a fresh one if it expires.

Multi-Workspace Support

# List all authenticated workspaces
agent-slack workspace list

# Switch to a different workspace
agent-slack workspace switch <workspace-id>

# Show current workspace
agent-slack workspace current

# Remove a workspace
agent-slack workspace remove <workspace-id>

# Check auth status
agent-slack auth status

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

# Agent Messenger Memory

## Slack Workspaces

- `T0ABC1234` — Acme Corp (default)
- `T0DEF5678` — Side Project

## 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)
- "main workspace" → `T0ABC1234` (Acme Corp)

## Notes

- User prefers --pretty output for snapshots
- Main workspace is "Acme Corp"

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

# Extract tokens from Slack desktop app or browser (usually automatic)
agent-slack auth extract
agent-slack auth extract --debug
agent-slack auth extract --browser-profile ~/browser-data
agent-slack auth extract --browser-profile ~/work-profile --browser-profile ~/personal-profile

# --browser-profile accepts repeatable or comma-separated Chromium profile/user-data dirs

# Sign in with a QR code from Slack's "Sign in on mobile" screen (no desktop app needed)
agent-slack auth qr "data:image/png;base64,..."
pbpaste | agent-slack auth qr
agent-slack auth qr --debug   # show each redirect hop for troubleshooting

# Check auth status
agent-slack auth status

# Logout from a workspace (defaults to current)
agent-slack auth logout
agent-slack auth logout <workspace-id>

Whoami Command

# Show current authenticated user
agent-slack whoami
agent-slack whoami --pretty

Output includes the authenticated user's identity information.

Message Commands

# Send a message
agent-slack message send <channel> <text>
agent-slack message send general "Hello world"

# Send a threaded reply
agent-slack message send general "Reply" --thread <ts>

# List messages
agent-slack message list <channel>
agent-slack message list general --limit 50

# Search messages across workspace
agent-slack message search <query>
agent-slack message search "project update"
agent-slack message search "from:@user deadline" --limit 50
agent-slack message search "in:#general meeting" --sort timestamp

# Get a single message by timestamp
agent-slack message get <channel> <ts>
agent-slack message get general 1234567890.123456

# Get thread replies (includes parent message)
agent-slack message replies <channel> <thread_ts>
agent-slack message replies general 1234567890.123456
agent-slack message replies general 1234567890.123456 --limit 50
agent-slack message replies general 1234567890.123456 --oldest 1234567890.000000
agent-slack message replies general 1234567890.123456 --cursor <next_cursor>

# Edit a message
agent-slack message edit <channel> <ts> <new-text>

# Delete a message
agent-slack message delete <channel> <ts> --force

# Schedule a message (post_at is a Unix timestamp)
agent-slack message schedule <channel> <text> <post-at>
agent-slack message schedule general "Friday update" 1700000000
agent-slack message schedule general "Thread reply" 1700000000 --thread 1234567890.123456

# List scheduled messages
agent-slack message scheduled-list
agent-slack message scheduled-list --channel general

# Delete a scheduled message
agent-slack message scheduled-delete <channel> <scheduled-message-id>

# Post ephemeral message (visible only to a specific user)
agent-slack message ephemeral <channel> <user-id> <text>

# Get a permanent link to a message
agent-slack message permalink <channel> <ts>

Channel Commands

# List channels (excludes archived by default)
agent-slack channel list
agent-slack channel list --type public
agent-slack channel list --type private
agent-slack channel list --type dm
agent-slack channel list --include-archived

# Get channel info
agent-slack channel info <channel>
agent-slack channel info general

# Get channel history (alias for message list)
agent-slack channel history <channel> --limit 100

# Open a DM channel with a user (returns channel ID)
agent-slack channel open <user_id>
agent-slack channel open U0ABC123

# Open a group DM with multiple users
agent-slack channel open U0ABC123,U0DEF456

# List users in a channel
agent-slack channel users <channel>
agent-slack channel users general --include-bots

# Create a new channel
agent-slack channel create <name>
agent-slack channel create my-new-channel --private

# Archive a channel
agent-slack channel archive <channel>

# Set channel topic
agent-slack channel set-topic <channel> <topic>

# Set channel purpose
agent-slack channel set-purpose <channel> <purpose>

# Invite users to a channel (comma-separated user IDs)
agent-slack channel invite <channel> <users>
agent-slack channel invite general U0ABC123,U0DEF456

# Join a channel
agent-slack channel join <channel>

# Leave a channel
agent-slack channel leave <channel>

User Commands

# List users
agent-slack user list
agent-slack user list --include-bots

# Get user info
agent-slack user info <user>

# Get current user
agent-slack user me

# Look up user by email
agent-slack user lookup <email>
agent-slack user lookup alice@example.com --pretty

# Get detailed user profile
agent-slack user profile <user-id>

# Set your status (emoji name without colons)
agent-slack user set-status <status-text>
agent-slack user set-status "In a meeting" --emoji calendar
agent-slack user set-status "On vacation" --emoji palm_tree --expiration 1700100000

Reaction Commands

# Add reaction
agent-slack reaction add <channel> <ts> <emoji>
agent-slack reaction add general 1234567890.123456 thumbsup

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

# List reactions on a message
agent-slack reaction list <channel> <ts>

File Commands

# Upload file
agent-slack file upload <channel> <path>
agent-slack file upload general ./report.pdf

# List files
agent-slack file list
agent-slack file list --channel general

# Get file info
agent-slack file info <file-id>

# Download file
agent-slack file download <file-id>
agent-slack file download <file-id> [output-path]
agent-slack file download F0ABC123 ./downloads/

# Delete a file
agent-slack file delete <file-id>

Unread Commands

# Get unread counts for all channels
agent-slack unread counts

# Get thread subscription details
agent-slack unread threads <channel> <thread_ts>

# Mark channel as read up to timestamp
agent-slack unread mark <channel> <ts>

Activity Commands

# List activity feed (mentions, reactions, replies)
agent-slack activity list
agent-slack activity list --limit 50
agent-slack activity list --unread
agent-slack activity list --types thread_reply,message_reaction

Saved Items Commands

# List saved items
agent-slack saved list
agent-slack saved list --limit 10
agent-slack saved list --cursor <next_cursor>

Drafts Commands

# List all drafts
agent-slack drafts list
agent-slack drafts list --limit 10
agent-slack drafts list --cursor <next_cursor>

Channel Sections Commands

# List channel sections (sidebar organization)
agent-slack sections list
agent-slack sections list --pretty

Pin Commands

# Pin a message
agent-slack pin add <channel> <ts>

# Unpin a message
agent-slack pin remove <channel> <ts>

# List pinned messages in a channel
agent-slack pin list <channel>
agent-slack pin list general --pretty

Bookmark Commands

# Add a bookmark to a channel
agent-slack bookmark add <channel> <title> <link>
agent-slack bookmark add general "Our Docs" https://docs.example.com --emoji books --type link

# Edit a bookmark
agent-slack bookmark edit <channel> <bookmark-id> --title "New Title"
agent-slack bookmark edit <channel> <bookmark-id> --link https://new.example.com

# Remove a bookmark
agent-slack bookmark remove <channel> <bookmark-id>

# List bookmarks in a channel
agent-slack bookmark list <channel>
agent-slack bookmark list general --pretty

Reminder Commands

# Add a reminder (time is a Unix timestamp)
agent-slack reminder add "Review PR" 1700000000
agent-slack reminder add "Team standup" 1700000000 --user U0ABC123

# List all reminders
agent-slack reminder list
agent-slack reminder list --pretty

# Complete a reminder
agent-slack reminder complete <reminder-id>

# Delete a reminder
agent-slack reminder delete <reminder-id>

Usergroup Commands

# List all user groups
agent-slack usergroup list
agent-slack usergroup list --include-disabled
agent-slack usergroup list --include-users --pretty

# Create a user group
agent-slack usergroup create "Marketing Team"
agent-slack usergroup create "Marketing Team" --handle marketing-team --description "Marketing gurus"
agent-slack usergroup create "Engineering" --channels C012ABC,C034DEF

# Update a user group (name, handle, description, channels)
agent-slack usergroup update <usergroup-id> --name "New Name"
agent-slack usergroup update S0616NG6M --handle new-handle --description "Updated description"
agent-slack usergroup update S0616NG6M --channels C012ABC,C034DEF

# Enable a disabled user group
agent-slack usergroup enable <usergroup-id>

# Disable a user group
agent-slack usergroup disable <usergroup-id>

# List members of a user group
agent-slack usergroup members <usergroup-id>
agent-slack usergroup members S0616NG6M --include-disabled --pretty

# Update members of a user group (replaces all members)
agent-slack usergroup members-update <usergroup-id> <comma-separated-user-ids>
agent-slack usergroup members-update S0616NG6M U060R4BJ4,U060RNRCZ

Emoji Commands

# List all custom emoji in the workspace
agent-slack emoji list
agent-slack emoji list --pretty

Snapshot Command

Get workspace overview for AI agents (brief by default):

# Brief snapshot (default) — fast, minimal API calls
agent-slack snapshot

# Full snapshot — includes messages, users, user groups (slow, large output)
agent-slack snapshot --full

# Filtered full snapshots
agent-slack snapshot --full --channels-only
agent-slack snapshot --full --users-only

# Limit messages per channel (only with --full)
agent-slack snapshot --full --limit 10

Default returns brief JSON with:

• Workspace metadata
• Channels (id, name) — non-archived only
• Hint for next commands

With --full, returns comprehensive JSON with:

• Workspace metadata
• Channels (id, name, topic, purpose, is_private, is_archived)
• Recent messages (ts, text, user, channel)
• Users (id, name, profile)
• User groups (id, name, handle, description, user_count, users)

Output Format

JSON (Default)

All commands output JSON by default for AI consumption:

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

Pretty (Human-Readable)

Use --pretty flag for formatted output:

agent-slack channel list --pretty

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 workspace authenticated. Run: agent-slack auth extract"
}

Common errors:

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

Configuration

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

SDK: QR Code Login

loginWithQr turns a Slack "Sign in on mobile" QR image into a usable session (token + cookie) over plain HTTP — no browser, no desktop app.

import { loginWithQr, SlackClient, SlackCredentialManager } from 'agent-messenger/slack'

// dataUrl is the QR image as a "data:image/png;base64,..." string
const session = await loginWithQr(dataUrl)

const client = await new SlackClient().login({ token: session.token, cookie: session.cookie })
const { team_id, team } = await client.testAuth()

// Persist for later, like the CLI does
await new SlackCredentialManager().setWorkspace({
  workspace_id: team_id,
  workspace_name: team ?? session.workspace,
  token: session.token,
  cookie: session.cookie,
})

loginWithQr(dataUrl, options) accepts an optional { debug, fetchImpl, maxRedirects, requestConfirmationCode }. It throws SlackError with codes qr_session_failed (link expired / no session) or qr_token_failed (token could not be retrieved). To decode the QR without logging in, use decodeSlackQr(dataUrl) which returns { url, workspace, teamId, userId }.

Handling Slack confirmation codes (workspace 2FA)

Some workspaces make a QR sign-in surface a confirmation-code page (email code, SMS, TOTP, etc.) before issuing the session cookie. Pass requestConfirmationCode to complete that step. The callback is only invoked when Slack actually shows a confirmation page — ordinary QR logins that receive the session cookie directly stay prompt-free.

import { loginWithQr, type SlackConfirmationChallenge } from 'agent-messenger/slack'

const session = await loginWithQr(dataUrl, {
  requestConfirmationCode: async (challenge: SlackConfirmationChallenge) => {
    // challenge.email is the address Slack sent the code to.
    // challenge.type is the mechanism ("email", "sms", "totp", ...) or null if unknown.
    return await promptUserForCode(challenge)
  },
})

Contract:

• Return the raw code as a string. Whitespace is trimmed before submission.
• Return an empty string (or all whitespace) to abort — loginWithQr throws qr_session_failed and no code is posted.
• The code is submitted to the exact https://<workspace>.slack.com/login/<qrSecret> endpoint bound to the QR payload. Redirects to a different workspace host or an unexpected pathname reject the flow before the callback is invoked.
• The callback and email/type fields never appear in debug output.

SDK: Real-Time Events

SlackListener connects to Slack's RTM WebSocket for instant event streaming. No polling — events arrive in real time.

Setup

import { SlackClient, SlackListener } from 'agent-messenger/slack'

const client = await new SlackClient().login()
const listener = new SlackListener(client)

Or with manual credentials:

import { SlackClient, SlackListener } from 'agent-messenger/slack'

const client = await new SlackClient().login({ token, cookie })
const listener = new SlackListener(client)

Listening for Events

listener.on('connected', (info) => {
  console.log(`Connected as ${info.self.id} on ${info.team.id}`)
})

listener.on('message', (event) => {
  // event.type, event.channel, event.user, event.text, event.ts
})

listener.on('reaction_added', (event) => {
  // event.user, event.reaction, event.item.channel, event.item.ts
})

listener.on('reaction_removed', (event) => {
  // same shape as reaction_added
})

listener.on('member_joined_channel', (event) => {
  // event.user, event.channel
})

listener.on('member_left_channel', (event) => {
  // event.user, event.channel
})

listener.on('user_typing', (event) => {
  // event.user, event.channel
})

listener.on('presence_change', (event) => {
  // event.user, event.presence ('active' | 'away')
})

// Catch-all for any RTM event type
listener.on('slack_event', (event) => {
  // event.type + all fields
})

listener.on('error', (err) => {
  console.error(err.message)
})

listener.on('disconnected', () => {
  // auto-reconnects with exponential backoff
})

Lifecycle

await listener.start()  // connects via RTM WebSocket
listener.stop()         // clean shutdown

Event Types

Notes

• Receives all workspace events for the authenticated user — no channel subscription needed
• Auto-reconnects with exponential backoff (1s → 30s max)
• Ping/pong keepalive every 30s
• Uses Slack's RTM API with xoxc user tokens

Limitations

• Plain text messages only (no blocks/formatting in v1)

Troubleshooting

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:

agent-slack message list general

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 slack message list general
bunx agent-messenger slack message list general
pnpm dlx agent-messenger slack message list general

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

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

Failed to read Slack cookies

If you see:

{"error":"Failed to read Slack cookies. The Slack app is currently running and locking the cookie database. Quit the Slack app completely and try again."}

Tell the user you need to quit the Slack app to extract credentials, and ask for confirmation. If the user agrees, quit Slack and retry the command.

For other troubleshooting (auth extraction, token issues, Keychain), see references/authentication.md.

References

• Authentication Guide
• Common Patterns