slack-acp

A Slack bot that relays each Slack thread to a spawned ACP-compatible agent
(fir --mode acp, claude-code, gemini-cli, etc.) over stdio.
One binary, no MCP surface, runs over Slack Socket Mode (no public webhook
URL needed).
Status
Early — v0.1.x. DM and @mention work; threaded follow-ups reuse the same
ACP session; agent output streams back into a single Slack message that
updates as the agent thinks. Tested primarily against fir --mode acp;
other ACP agents (claude-code, gemini-cli) should work but have had less
shakeout. Built on the same patterns as poe-acp.
How it works
Slack ──ws (Socket Mode)──> slack-acp ──stdio (ACP)──> agent (fir --mode acp)
- Each Slack thread (
channel_id + thread_ts) maps 1:1 to one ACP session.
- Each session gets a stable working directory at
<StateDir>/threads/<channel_id>/<thread_ts> so per-agent state
(skills, MCP, auth, scratch files) stays isolated and persists
across restarts.
- A new message in the same thread reuses the existing session; a follow-up
before the previous response finishes cancels the in-flight prompt.
- Streaming output is throttled to ~1 update/sec to stay inside Slack's
chat.update rate limits.
- Permission requests from the agent are auto-approved (
acp-kit's
default permission policy). The bot is meant to run as a trusted,
private agent — gate access at the allowed_user_ids /
allowed_channel_ids boundary instead.
Setup
Install
macOS / Linux via Homebrew:
brew install kfet/ai/slack-acp
Anywhere else (Linux without Homebrew, CI, containers) — one-liner that
picks the right prebuilt binary for your OS/arch, verifies its checksum
against checksums.txt, and drops it in /usr/local/bin (or
$HOME/.local/bin if that's not writable):
curl -fsSL https://raw.githubusercontent.com/kfet/slack-acp/main/install.sh | sh
Pin a version or install elsewhere with env overrides:
curl -fsSL https://raw.githubusercontent.com/kfet/slack-acp/main/install.sh \
| VERSION=v0.1.0 BIN_DIR=$HOME/.local/bin sh
Or build from source: go install github.com/kfet/slack-acp/cmd/slack-acp@latest.
Updating
slack-acp update # fetch the latest release, verify sha256, swap the binary
slack-acp update -check # report only; exit 3 when a newer release exists
A Homebrew install is upgraded via brew instead of being overwritten. The
swap is an atomic rename, so the running process keeps the old binary mapped
until it re-execs — recycle the service afterwards:
systemctl --user restart slack-acp # macOS: launchctl kickstart -k gui/$UID/dev.<user>.slack-acp
Pin a release with -version v0.5.0. install.sh is generated from the
distkit template (make install.sh); edit
install.sh.json, never the script.
Slack app
The fastest path is the bundled app manifest:
- Go to https://api.slack.com/apps → Create New App → From a manifest.
- Pick your workspace, paste
docs/slack-app-manifest.json, tweak the name if you want, Create.
- Basic Information → App-Level Tokens → Generate a token with scope
connections:write. Save the xapp-… token.
- Install App → Install to Workspace. Save the
xoxb-… bot token.
The manifest already enables Socket Mode, the Messages tab (so DMs have a
compose box), bot scopes, and the app_mention, message.channels,
message.groups, message.im and reaction_added events.
reaction_added (with the reactions:read scope) is what makes a
🍴 reaction branch a conversation; apps created from a
manifest before it was added must be reinstalled.
files:read lets the relay download files people attach (into the
thread's inbox/, capped by max_attachment_bytes, default 20 MiB) and
files:write lets it upload whatever the agent leaves in the thread's
outbox/ at the end of a turn. Installs that predate them must
reinstall the app for attachments to work.
Changing subscriptions or scopes requires REINSTALLING the app
(Install App → Reinstall to Workspace). Editing the manifest of
an already-installed app does not grant the new scopes, and the symptom
is silent: missing events, or missing_scope errors at runtime.
In particular, ambient mode in private channels needs both
message.groups (the private-channel counterpart of
message.channels) and the groups:history scope. Without both,
the relay never sees un-mentioned messages there and ambient is inert
in private channels while appearing to work fine in public ones. Both
were missing from this manifest before v0.3.0 — if your app was created
from an older copy, reinstall it.
One-shot wizard
slack-acp init
Prompts for both tokens, verifies them with auth.test, and writes
$XDG_CONFIG_HOME/slack-acp/config.json and $XDG_CONFIG_HOME/slack-acp/env
(both mode 0600). The env file is in the shape systemd / launchd
units want (SLACK_BOT_TOKEN=…\nSLACK_APP_TOKEN=…). Flags:
--bot-token / --app-token for non-interactive, --skip-verify for
offline bootstrap, --force to overwrite an existing config.
Supervised service
slack-acp install-service --dry-run # preview the unit
slack-acp install-service # write it
Detects the platform and emits a tailored systemd-user unit
(~/.config/systemd/user/slack-acp.service) on Linux or a launchd
LaunchAgent plist (~/Library/LaunchAgents/dev.<user>.slack-acp.plist)
on macOS, pointing at the binary, config, and env file init wrote.
--force to overwrite, --goos linux|darwin to preview the other
platform's unit (for production installs, ssh to the target host and
run the command there so embedded paths match that host's layout).
The command prints the systemctl/launchctl lines you need to
enable and start the service; it deliberately doesn't run them
itself.
Run
SLACK_BOT_TOKEN=xoxb-… SLACK_APP_TOKEN=xapp-… \
slack-acp --agent-cmd "fir --mode acp"
Or with a config file:
{
"bot_token": "xoxb-…",
"app_token": "xapp-…",
"agent_cmd": ["fir", "--mode", "acp"],
"allowed_user_ids": ["U0123456"],
"owner_user_ids": ["U0123456"],
"state_dir": "/var/lib/slack-acp"
}
slack-acp --config /etc/slack-acp.json
See docs/config.example.json for a full
key reference. All keys are optional — tokens may be supplied via env
(SLACK_BOT_TOKEN / SLACK_APP_TOKEN) and the rest fall back to
built-in defaults.
slack-acp --print-paths resolves and prints the config file, state
directory, and agent command without starting the bot — handy
for verifying what a unit file or env will actually use.
Owner-only commands
owner_user_ids lists the Slack user ids allowed to run the relay's
operator commands: !fir, !run, !skills, !update, the login family
(!login, !logins, !cancel-login) and !logout. Anyone else gets a
one-line "owner-only" refusal and the message never reaches the agent
(journal reason owner_only). The gate fails closed: with
owner_user_ids unset, nobody may run them — set it before upgrading
past v0.15.0 if you use !login. Conversation commands (!model,
!branch, …) are not gated.
Catch-up after a disconnect
On every Socket Mode connect the relay reads the history it missed and
answers mentions, DMs and ambient thread replies once. Checkpoints live
in <state_dir>/catchup.json; the first run (and any channel joined
later) starts at "now", so nothing old replays — keep state_dir
persistent or every restart is a first run. Missed messages older than
catchup_max_age_seconds (default 86400, 0 disables catch-up) get a
one-line notice instead of an answer. Relay commands sent during the
outage are not run late.
Slack clamps conversations.history / .replies hard for commercially
distributed non-Marketplace apps; how the relay fares under that clamp
has not been measured. Each run logs its cost — watch the first
reconnect after a deploy for 429s:
journalctl --user -u slack-acp | grep 'catch-up:'
See docs/catch-up.md.
Sessions, identity and working directories
Every ACP session call — session/new, session/resume (and the
session/load acp-kit replays after an agent respawn), session/fork
and every session/prompt — carries the triggering Slack message in
_meta["dev.acp-kit.origin/v1"] (platform: "slack", team, user,
channel, thread, message ts, DM/mention flags). That is the only place
the sender's identity travels: prompt text never carries a [name]
prefix. (Catch-up and backfill turns, which replay several people's
missed messages at once, still label each replayed line with its
author.)
{
"session_scope": "thread",
"cwd_mode": "local"
}
| Key |
Value |
Effect |
session_scope |
thread (default) |
One agent session per Slack thread, shared by everyone in it. A new message supersedes the thread's running turn. |
|
thread_user |
One agent session per (thread, sender). Each message goes to its sender's session; replies in a shared thread start with an @-mention of the user they answer (DMs have one human and get none); a new message supersedes only that user's running turn. Per-user state lives in <state_dir>/threads/<channel>/<ts>/users/<user>. |
cwd_mode |
local (default) |
The agent is told the per-conversation directory under state_dir. |
|
agent |
The agent is told the fixed placeholder /slack-acp/agent-chooses-cwd — never a path on the relay host — and picks the real cwd itself (e.g. from the origin _meta). The relay records each conversation's session id under state_dir, so resume after idle GC or a restart still works without session/list. The login commands (!login, !logins, !cancel-login, !logout) stop being owner-only: each sender logs in for themselves, and a pending login only takes its sender's next message as the redirect. Other admin verbs stay owner-only. The relay's slack MCP server cannot bind a session to its thread from the placeholder, so it is not offered in this mode (no slack_*, history or branch tools), and the relay cannot see the agent's ./outbox/ (reply attachments are not uploaded). Inbound attachments are still saved under state_dir and named by absolute path, so the agent must share the relay's filesystem to read them. |
Agent Slack access
The spawned agent can reach Slack beyond the thread it is answering in —
read another thread or channel, list the bot's channels, and (opt-in)
post as the bot — through an MCP server the relay hosts. The agent
never receives a Slack token; every call is made by the relay, checked
against allowed_channel_ids, rate-capped, and logged.
{
"agent_slack_access": "read",
"agent_posts_per_minute": 10
}
| Value |
Effect |
off |
No MCP server registered; the agent gets no Slack tools. |
read (default) |
slack_read_thread, slack_read_channel, slack_list_channels, slack_search. Exposes nothing the bot cannot already see — but see the DM rule below. |
read_write |
Adds slack_post. Opt-in: ambient thread text can steer the agent into posting elsewhere. |
slack_search is a bounded local scan, not Slack search: the relay
fans out conversations.history over the allowed channels and matches
locally, within a day window, a per-channel page cap, and the shared read
budget — flagging every truncation. Slack's real search.messages
requires a user token (xoxp-), which the relay's Slack client must
never hold; see BACKLOG.md.
With no allowed_channel_ids configured the reach is "the channels the
bot is already in", excluding DMs: the bot holds a 1:1 DM with
everyone who has ever messaged it, and one person's prompt must not be
able to surface another person's private conversation. An operator who
names a DM in allowed_channel_ids explicitly overrides that.
This adds two bot scopes (channels:read, groups:read), so
existing installs must reinstall the app before slack_list_channels
works. See docs/agent-slack-access.md
for the threat model and the full mitigation list.
The same MCP server carries the files tools: send_file (into the
session's own thread; large files go straight from the agent's client to a
pre-signed Slack upload URL) and, with files_listen +
files_public_base_url configured, list_attachments /
fetch_attachment via a one-shot signed download proxy. See
docs/files.md.
Self-drive escape hatch (testing only)
⚠️ This deliberately reopens the bot-message boundary. Leave
self_drive_sentinel empty in production.
The relay normally drops every bot-authored message, because it posts
its own replies as that same bot — accepting them is a reply → trigger
→ reply loop. That also blocks an operator who can only post using the
bot token from testing the user → agent → reply round trip.
Setting self_drive_sentinel opts into a narrow exception: a
bot-authored channel message whose text begins with that exact
token is accepted, with the token stripped before the agent sees it.
{
"self_drive_sentinel": "drive-me-9f3a",
"self_drive_per_minute": 4
}
The token must be at least 8 characters, must differ from
silent_sentinel, and must not contain <, > or & — Slack
HTML-escapes those inbound, so <<DRIVE-TEST>> would arrive as
<<DRIVE-TEST>> and never match. Config validation rejects
such a token at load time rather than letting the hatch fail silently.
The hatch is prefix-anchored, never a substring match, because the
realistic loop is the agent quoting its trigger back mid-reply. A
bot-authored message containing the sentinel without starting with it
is logged visibly (SELF-DRIVE IGNORED … must be a PREFIX) and dropped.
@-mentions are not a hatch trigger: app_mention unconditionally
refuses bot-authored events, so the sentinel itself is the addressing
mechanism. See docs/ambient-threads.md for
the full loop-guard design.
Mid-turn quick replies (interject)
Opt-in. With it off (the default) a new message in a thread whose turn is
still running cancels that turn and re-prompts with the new message.
{ "interject": { "enabled": true, "min_conf": 7 } }
With it on, the relay forks the running session (session/fork), asks
the fork the new message, and posts its short answer tagged
(quick reply · …). The fork also decides what happens to the main
turn: just answer, inform it, or stop it. A verdict below min_conf
(0-9, default 7) means "just answer". With fir's _fir/session/steer
(fir ≥ 1.53) an answer-only exchange is recorded where the model never
sees it, and inform injects the Q&A (plus an optional note from the
fork) into the running turn. Other agents get the side Q&A prepended
to the next main prompt, and inform cancels and re-prompts. Commands (!…), messages with files, unaddressed ambient
replies, a fork error, and agents without session/fork keep the old
behaviour.
Verifying a deployment
slack-acp verify drives real messages through real Slack and reports
PASS/FAIL for every inbound path — DM, app_mention in public and
private channels, ambient replies in known and unknown threads, the
bot-echo drop, and the self-drive hatch. It asserts on both the relay's
ingest journal and the resulting thread state, and cleans up after
itself.
slack-acp verify --public-channel C… --private-channel C…
The human-authored checks post with a Slack user token (xoxp-),
because that is the only way to produce a message Slack considers human
— and therefore the only way to exercise the app_mention guard, which
refuses every bot-authored mention. One browser step is needed once to
add the user scope; see
docs/self-verification.md.
Independently of the harness, every inbound event is journalled:
journalctl --user -u slack-acp | grep SLACK-ACP-INGEST
Each line says which path the event arrived on, whether it was
delivered, run, or dropped, and why — so "the bot didn't reply" is a
one-command diagnosis with no debug mode and no re-provoking.
Deploying a fleet bot
Hosts with an entry in the private fleet registry (~/sync/shared/fleet/bots,
override with FLEET_BOTS_DIR; entries with "relay": "slack-acp") are
converged, never hand-deployed. This repo is public, so it holds only the
distro spec — distro.json, the defaults every slack-acp bot shares — and
dist.lock, the resolved release. scripts/converge.sh deep-merges
distro.json <- the bot file (the bot wins; objects merge, arrays replace,
null unsets a default) and makes the host match:
scripts/converge.sh --tot # resolve the newest release into dist.lock (commit it)
scripts/converge.sh <bot> # dry run
scripts/converge.sh <bot> --apply # converge, restart, verify Slack connected
It manages the slack-acp binary, config.json and the supervisor
definition (systemd user unit, or launchd plist on macOS — rendered exactly
as slack-acp install-service would). The binary is downloaded on the host,
checked against the release's checksums.txt, and renamed into place (no
ETXTBSY, no stop-before-copy); then the service is restarted, since
slack-acp has no graceful reload. make all runs scripts/check-no-leak.sh,
which fails if any identifier from the registry appears in the tree.
Repository layout
cmd/slack-acp/ entry point: flags + wiring
internal/config/ JSON config loader (DisallowUnknownFields)
internal/dist/ release repo, asset naming, restart hint (distkit + install.sh)
internal/handler/ Slack event → ACP prompt + streaming sink
internal/initcmd/ `slack-acp init` first-run wizard
internal/installsvc/ systemd / launchd supervisor unit generator
internal/ratelimit/ shared token bucket (self-drive hatch + agent posts)
internal/router/ (channel,thread_ts) → ACP session map + GC
internal/skills/ embedded skill bundle + fir-style catalog (wraps `acp-kit/skills`)
internal/slackfiles/ MCP files tools: send_file uploads, attachment download proxy
internal/slackmcp/ relay-hosted `slack` MCP server (agent-initiated Slack calls)
internal/slackproto/ Socket Mode client + throttled message streamer
internal/sysprompt/ Slack-mrkdwn sysprompt composer injected per session
internal/journal/ stable JSONL ingest-decision records
internal/verify/ `slack-acp verify` self-verification harness
docs/ design notes + Slack app manifest template
scripts/ converge.sh (fleet deploy) + check-no-leak.sh
distro.json, dist.lock fleet distro spec + resolved release (no bot instances)
test/ converge.sh tests on synthetic fixtures (test/fixtures/bots)
Shared ACP primitives live in github.com/kfet/acp-kit:
client (ACP stdio agent process + permission gates), log (debug
logger), skills (skill loader + catalog formatter), mcphost
(self-hosted MCP server + stdio redirector). The same primitives
back poe-acp, so wire-level fixes land once.
See docs/design.md for goals, non-goals, and the
session-lifecycle model.
Build & test
make test # go test ./...
make all # no-leak + vet + race + coverage + script tests + cross-builds + license check
License
MIT — see LICENSE.