agent-slack: a Slack automation CLI built for AI agents

The problem agent-slack solves: Slack output is too fat for an LLM context window

Slack's own APIs return verbose payloads. A single channel history fetch can carry user objects, bot profiles, block structures, reaction arrays and null fields an agent will never read. Every one of those tokens costs money and context. agent-slack is a command line wrapper that reshapes Slack responses before they reach the model: the README states that Slack data commands output aggressively pruned JSON with null and empty fields removed, and that attached files are auto-downloaded and returned as absolute local paths. That second point matters more than it looks. An agent that can read a local path can hand the file to another tool; an agent that receives a Slack file URL usually cannot fetch it without extra credentials.

The intended user is not a human at a terminal. It is an agent runtime, a script, or a developer building an agent skill. The repository ships a skill at skills/agent-slack/ that the README says is compatible with Claude Code, Codex and Cursor, and the README's own tip tells human readers to use the skill instead of reading the examples. That is an unusually direct statement of audience.

How agent-slack works: a Commander CLI over the Slack Web API

The package.json shows the shape of the thing. It is an ES module named agent-slack, version 0.10.2, with a bin entry pointing at ./bin/agent-slack.js. Dependencies are @slack/web-api, commander, zod, turndown, turndown-plugin-gfm, node-emoji and hysnappy. That list tells you the data flow: commander parses the subcommand tree, @slack/web-api makes the calls, zod validates, and turndown plus its GFM plugin convert HTML into Markdown, which is what the canvas commands return and what message compose renders. The build script bundles src/index.ts with Bun for the Bun target, while build:npm targets Node with --packages=external and marks bun:sqlite and node:sqlite as external. So there are two artifacts from one source tree.

The command map is wide. Reads cover message get, message list, search all, search messages and search files. Writes cover message send with scheduling, message edit, message delete and message react add or remove. There is a draft system that creates Slack-native drafts which appear in the user's own Slack client, a compose command that opens a browser editor, channel creation and invites, user listing, workflow listing and triggering, and canvas create, edit and get. The README notes that bullet lists in sent messages auto-render as native Slack rich text, which is the turndown pipeline working in reverse.

Authentication is the part worth scrutinising. On macOS and Windows the README says auth happens automatically by reading Slack Desktop local data, with fallbacks to Chrome, Brave and Firefox extraction on macOS. There is also a parse-curl path and a plain environment variable path for xoxc plus xoxd tokens, or a standard xoxb or xoxp token. The browser import commands read tokens from a logged-in Slack tab via AppleScript, and the README warns that both browsers ship with Allow JavaScript from Apple Events disabled, so you must enable it under View, Developer first.

Installing agent-slack and sending your first message

Three install routes are documented. The recommended one is the shell installer, which downloads a binary. The npm route requires Node >= 22.5, matching the engines field in package.json. The Nix flake route runs straight from the repository.

curl -fsSL https://raw.githubusercontent.com/stablyai/agent-slack/main/install.sh | sh

After installing, confirm which identity the CLI is using. On macOS this should succeed without any manual token work, because the default path reads Slack Desktop local data. The README notes you do not need to quit Slack for this.

agent-slack auth whoami
agent-slack auth test

If automatic import fails, the manual import commands are the documented fallback. For the browser paths, enable Allow JavaScript from Apple Events in the browser first, and expect a macOS password prompt the first time.

agent-slack auth import-desktop
agent-slack auth import-chrome

For CI or a headless box, set the environment variables instead. Both the browser-token pair and a standard bot token are accepted.

export SLACK_TOKEN="xoxc-..."
export SLACK_COOKIE_D="xoxd-..."
agent-slack auth test

Now a real read. Message targets accept either a Slack permalink or a channel reference with a timestamp flag.

agent-slack message get "#general" --ts "1770165109.628379"
agent-slack message list "#general" --limit 20

The first returns one message plus thread metadata if it is threaded. The second returns recent channel history, and the README shows a --with-reaction filter, for example --with-reaction eyes, to narrow the list to messages carrying a given emoji. If your workspace has more than one configured workspace and you address a channel by name rather than ID, you must pass --workspace with a full URL or a unique substring; the README uses "stablygroup" as an example of the substring form. Expect pruned JSON on stdout for data commands, and plain text for help and some auth setup commands.

Where agent-slack breaks: browser tokens, multi-workspace ambiguity and CI

The zero-config auth story is the project's most attractive feature and its most fragile one. Reading tokens out of Slack Desktop local data is not a documented Slack integration path. It works until Slack changes its storage format, and when it breaks the failure will look like an auth error with no upstream changelog to consult. The browser fallbacks are worse in operational terms: they depend on AppleScript, on a logged-in tab, and on a browser setting that is off by default. On Linux the README documents no automatic path at all, so you are on environment variables.

Multi-workspace use is a genuine papercut. Channel names are not globally unique, and the README is explicit that a channel name requires --workspace when more than one workspace is configured. An agent that constructs commands from natural language will get this wrong, and the resulting failure is not a permission error but a message delivered to the wrong workspace. Channel IDs avoid the ambiguity but are harder for a model to produce reliably.

The human-in-the-loop principle is a design position, not a bug, but it cuts against automation. The README says the CLI loops humans in when appropriate and not in CI environments, and message compose opens a browser editor. That is fine for an interactive assistant and wrong for an unattended pipeline. If your goal is a cron job that posts a nightly digest, the compose and draft paths are irrelevant and the auth path is the risky part.

Finally, there is no documented rollback or dry-run mode. message send supports scheduling, and scheduled messages can be listed and cancelled with message scheduled list and message scheduled cancel <id>, which gives you a window to undo a scheduled send. Nothing in the README describes previewing an immediate send before it leaves.

agent-slack compared with a Slack app built on the official SDK

The obvious alternative is writing your own integration directly against @slack/web-api, which agent-slack itself depends on. The difference is the authentication model and who owns the output shape. A conventional Slack app registers with Slack, receives xoxb scopes through OAuth, and posts as a bot identity. That path is supported, auditable, and works from any host including Linux containers. It also requires an app manifest, scope review, and a distribution decision if other workspaces will install it.

agent-slack inverts this. It acts as you, reusing a session token so no app registration is needed, and it prunes responses to save tokens. You get a working agent in minutes instead of an afternoon of OAuth plumbing. You give up the bot identity, the scope boundary, and any guarantee that the token acquisition will keep working. The project does accept a standard xoxb or xoxp token through SLACK_TOKEN, so the two models can meet in the middle: use the desktop import for local development and a real bot token in production. The README presents both without ranking them.

For teams already running an MCP server for Slack, agent-slack is a different bet. MCP exposes tools over a protocol; agent-slack exposes a CLI with a command tree. A CLI is easier to call from a shell-capable agent and easier to debug by hand, but it has no schema negotiation and relies on the model reading --help output. The README leans into this, telling readers to treat agent-slack --help and agent-slack <command> --help as authoritative for supported commands and flags, which is a sensible hedge for a fast-moving 0.x tool.

Maintenance, licensing and what upgrading costs you

The project is not archived, and the last push was on 2026-09-07. Releases are frequent: v0.10.0 and v0.10.1 landed on 2026-09-02, and v0.10.2 on 2026-09-04. That cadence is the main reason to pin a version. A 0.x series with three releases in a week can rename a flag between your agent's prompt and its next run. There is a self-update command, agent-slack update, which the README says detects npm, bun or binary installs, so the tool can move under you unless you disable or avoid that command in automated environments.

The licence is MIT, declared in both package.json and the repository root. MIT is permissive: you can vendor it, modify it and ship it inside a closed product, provided you keep the copyright notice and licence text. That is a statement about the licence file, not legal advice; if you are redistributing a modified binary, have counsel read the actual LICENSE file rather than this paragraph.

One operational note on the licence and the auth model together: MIT covers the code, not your Slack workspace. Reusing a session token to act as a human user may conflict with your organisation's Slack terms regardless of what the repository licence permits. Those are separate questions and the README does not address the second one.

Editorial conclusion

Adopt agent-slack when you are wiring an agent into an existing Slack workspace and want the smallest possible output payload, ideally on macOS where desktop token import is automatic. Skip it if you need a supported Slack app with xoxb scopes and an audit trail, because the browser-token path depends on undocumented Slack internals. Before committing, run agent-slack auth test on every machine that will run it, and read agent-slack message send --help to confirm the flags your workflow needs actually exist in v0.10.2.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. stablyai/agent-slack on GitHub