Agent Slack

Interact with Slack workspaces - send messages, read channels, manage reactions

Security Scan

The skill's behavior (automatic extraction and local storage of Slack tokens, mandatory reading/writing of a persistent memory file, and lack of a traced upstream source) is coherent with a Slack CLI but raises security and provenance concerns that are not fully declared in the registry metadata.

Purpose & Capability

The name/description (Slack integration) match the code and instructions: the CLI extracts Slack tokens, lists channels, sends messages, etc. Extracting tokens from the Slack desktop app is a legitimate way for a CLI to authenticate. However the registry metadata does not declare the config paths or files the skill will read/write (it lists none), while the implementation accesses Slack app directories and writes ~/.config/agent-messenger/slack-credentials.json and MEMORY.md — this mismatch should be disclosed to users.

Instruction Scope

SKILL.md instructs the agent to always read ~/.config/agent-messenger/MEMORY.md at the start of every task and to write the complete file when updating memory. That grants the agent routine access to persistent local state. The tool itself also performs automatic token extraction by reading Slack desktop app storage and (on macOS) decrypting cookies via Keychain. The instructions assert 'do not store tokens' but the reference docs show tokens are stored in plaintext under ~/.config/agent-messenger/slack-credentials.json — a direct contradiction and a clear scope/privacy concern.

Install Mechanism

Install uses a Node package (kind: node, package: agent-messenger) which provides the agent-slack binary. This is a typical install mechanism (moderate risk compared to direct downloads). However the package source is 'unknown' and there is no homepage listed in the registry metadata — you cannot verify the upstream project or review the published package before installing without additional effort.

Credentials

The skill declares no required env vars or config paths, yet the implementation reads Slack desktop app data directories and writes credentials to ~/.config/agent-messenger/slack-credentials.json (tokens stored plaintext with 0600 permissions). That local file contains full workspace tokens/cookies granting the same access as the desktop app — this is sensitive but not reflected in the declared requirements. The memory file policy (what to store / not store) in SKILL.md conflicts with actual credential storage described in references.

Persistence & Privilege

The skill persists credentials and snapshots under ~/.config/agent-messenger and instructs the agent to read/write a persistent MEMORY.md on every task. It does not set always:true and does not modify other skills. Persistent storage of tokens combined with autonomous invocation (default platform behavior) increases risk in practice — consider that an LLM with this skill could be able to use stored tokens if the skill is invoked.

What to consider before installing

This skill will automatically extract Slack session tokens from your local Slack desktop app and store them at ~/.config/agent-messenger/slack-credentials.json (plaintext, owner-only permissions). It also instructs the agent to read and overwrite a persistent memory file (~/.config/agent-messenger/MEMORY.md) at the start of every task. Before installing: - Verify provenance: the registry lists 'Source: unknown' and no homepage — review the npm package (agent-messenger) source code and publisher before installing. If you can't find a trusted upstream, don't install. - Understand credential risk: extracted tokens grant the same access you have in Slack. If you run this on a machine with workspaces you care about, consider using a least-privilege approach (e.g., bot tokens scoped to a single workspace/channel) instead of your personal session tokens. - Inspect local file effects: expect ~/.config/agent-messenger/slack-credentials.json and MEMORY.md to be created. Back up any important data and review these files after first run. Consider restricting file permissions and removing stored credentials when not needed. - Review runtime behavior: the agent is instructed to read MEMORY.md at every task start. That means the model will routinely receive persistent local context — be cautious about what you allow it to store there. - Audit the package: run 'npm view agent-messenger' and inspect the package contents or clone the repository before installing. If you cannot validate the publisher and code, treat this as high-risk and avoid installing. Because of the mismatches (undisclosed filesystem access and stored tokens, missing upstream provenance, and contradictory guidance about storing tokens), treat this skill as suspicious and verify code and publisher trustworthiness before use.

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

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

# 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 (usually automatic)
agent-slack auth extract
agent-slack auth extract --debug

# Check auth status
agent-slack auth status

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

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>

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

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

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

# 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

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

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

Drafts Commands

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

Channel Sections Commands

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

Snapshot Command

Get comprehensive workspace state for AI agents:

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

{
  "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

Format:

{
  "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

Authentication fails or no workspace found

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

agent-slack auth extract --debug

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:

agent-slack message list general

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

bunx agent-messenger slack message list general

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