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

bash

# Extract credentials from Slack desktop app (zero-config)
agent-slack auth extract

# Get workspace snapshot
agent-slack snapshot

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

# List channels
agent-slack channel list

Authentication

Seamless Token Extraction

agent-slack automatically extracts your Slack credentials from the desktop app:

bash

# Just run this - no manual token copying needed
agent-slack auth extract

# Use --debug for troubleshooting
agent-slack auth extract --debug

This command:

Auto-detects your platform (macOS/Linux/Windows)
Supports both direct download and App Store versions of Slack on macOS
Extracts xoxc token and xoxd cookie (with v10 decryption for sandboxed apps)
Validates tokens against Slack API before saving
Discovers ALL logged-in workspaces
Stores credentials securely in
```
~/.config/agent-messenger/
```

Multi-Workspace Support

bash

# 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

# Check auth status
agent-slack auth status

Commands

Message Commands

bash

# 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>

# Update a message
agent-slack message update <channel> <ts> <new-text>

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

Channel Commands

bash

# 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 --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

User Commands

bash

# 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

Reaction Commands

bash

# 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

bash

# 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>

Unread Commands

bash

# List unread channels
agent-slack unread list
agent-slack unread list --pretty

# Get unread counts summary
agent-slack unread count

# Mark channel as read
agent-slack mark read <channel>
agent-slack mark read general

Activity Commands

bash

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

Saved Items Commands

bash

# List saved items
agent-slack saved list

# Add item to saved
agent-slack saved add <channel> <ts>
agent-slack saved add general 1234567890.123456

# Remove item from saved
agent-slack saved remove <channel> <ts>

Drafts Commands

bash

# List all drafts
agent-slack drafts list
agent-slack drafts list --pretty

Channel Sections Commands

bash

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

Snapshot Command

Get comprehensive workspace state for AI agents:

bash

# Full snapshot
agent-slack snapshot

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

# Limit messages per channel
agent-slack snapshot --limit 10

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:

json

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

Pretty (Human-Readable)

Use

--pretty

flag for formatted output:

bash

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:

json

{
  "error": "No workspace authenticated. Run: agent-slack auth extract"
}

Common errors:

```
NO_WORKSPACE
```
: No authenticated workspace
```
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

Format:

json

{
  "current_workspace": "T123456",
  "workspaces": {
    "T123456": {
      "workspace_id": "T123456",
      "workspace_name": "My Workspace",
      "token": "xoxc-...",
      "cookie": "xoxd-..."
    }
  }
}

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

agent-slack: command not found

The

agent-messenger

package is not installed. Run it directly using a package runner. Ask the user which one to use:

bash

npx -p agent-messenger agent-slack ...
bunx -p agent-messenger agent-slack ...
pnpm dlx --package agent-messenger agent-slack ...

If you already know the user's preferred package runner, use it directly instead of asking.

References

Authentication Guide
Common Patterns

agent-slack

NPX Install

Tags

SKILL.md Content

Agent Slack

Quick Start

Authentication

Seamless Token Extraction

Multi-Workspace Support

Commands

Message Commands

Channel Commands

User Commands

Reaction Commands

File Commands

Unread Commands

Activity Commands

Saved Items Commands

Drafts Commands

Channel Sections Commands

Snapshot Command

Output Format

JSON (Default)

Pretty (Human-Readable)

Common Patterns

Templates

Error Handling

Configuration

Limitations

Troubleshooting

`agent-slack: command not found`

References