slack-acp

module
v0.20.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: MIT

README

slack-acp

CI Go Reference Go Report Card

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:

  1. Go to https://api.slack.com/apps → Create New App → From a manifest.
  2. Pick your workspace, paste docs/slack-app-manifest.json, tweak the name if you want, Create.
  3. Basic Information → App-Level Tokens → Generate a token with scope connections:write. Save the xapp-… token.
  4. 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 &lt;&lt;DRIVE-TEST&gt;&gt; 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.

Directories

Path Synopsis
cmd
slack-acp command
slack-acp is a standalone Slack bot that runs an ACP-compatible agent (e.g.
slack-acp is a standalone Slack bot that runs an ACP-compatible agent (e.g.
internal
catchup
Package catchup reads the Slack messages that arrived while the relay was not connected.
Package catchup reads the Slack messages that arrived while the relay was not connected.
config
Package config loads the slack-acp JSON config file.
Package config loads the slack-acp JSON config file.
dist
Package dist holds the one definition of how slack-acp is distributed: which GitHub repo its releases come from, how its assets are named, and how a host recycles the service after a binary swap.
Package dist holds the one definition of how slack-acp is distributed: which GitHub repo its releases come from, how its assets are named, and how a host recycles the service after a binary swap.
handler
Attachments in and out of a Slack thread.
Attachments in and out of a Slack thread.
initcmd
Package initcmd implements the `slack-acp init` first-run wizard.
Package initcmd implements the `slack-acp init` first-run wizard.
installsvc
Package installsvc generates a supervisor unit (systemd user unit on Linux, launchd LaunchAgent plist on macOS) that runs slack-acp under a long-lived process supervisor, pointing at the config + env file that `slack-acp init` already wrote.
Package installsvc generates a supervisor unit (systemd user unit on Linux, launchd LaunchAgent plist on macOS) that runs slack-acp under a long-lived process supervisor, pointing at the config + env file that `slack-acp init` already wrote.
journal
Package journal emits the relay's ingest decisions as a stable, machine-readable stream — one JSONL line per inbound Slack event, recording whether it was delivered onward or dropped, and why.
Package journal emits the relay's ingest decisions as a stable, machine-readable stream — one JSONL line per inbound Slack event, recording whether it was delivered onward or dropped, and why.
probe
Package probe makes the agent's startup model probe survive a slow agent.
Package probe makes the agent's startup model probe survive a slow agent.
ratelimit
Package ratelimit provides the token bucket the relay uses as a loop backstop wherever it deliberately reopens a boundary that normally keeps it from acting on machine-authored input.
Package ratelimit provides the token bucket the relay uses as a loop backstop wherever it deliberately reopens a boundary that normally keeps it from acting on machine-authored input.
router
Package router maps a Slack thread (channel + thread_ts) to an ACP session inside a shared agent process.
Package router maps a Slack thread (channel + thread_ts) to an ACP session inside a shared agent process.
skills
Package skills embeds the slack-acp curated bundle and delegates loading, merging, and catalog formatting to acp-kit/skills.
Package skills embeds the slack-acp curated bundle and delegates loading, merging, and catalog formatting to acp-kit/skills.
slackfiles
Package slackfiles implements acp-kit's optional MCP files capabilities for Slack, following acp-kit docs/files-oob.md:
Package slackfiles implements acp-kit's optional MCP files capabilities for Slack, following acp-kit docs/files-oob.md:
slackmcp
This file holds the two conversation-scoped tools: `history` and `branch`.
This file holds the two conversation-scoped tools: `history` and `branch`.
slackproto
Package slackproto adapts slack-go's Socket Mode client to a small handler-shaped surface used by the relay.
Package slackproto adapts slack-go's Socket Mode client to a small handler-shaped surface used by the relay.
statusline
Package statusline is the Slack-mrkdwn renderer for the dev.acp-kit.status-line/v1 ACP extension.
Package statusline is the Slack-mrkdwn renderer for the dev.acp-kit.status-line/v1 ACP extension.
sysprompt
Package sysprompt builds the durable system-prompt text the relay injects into every ACP session so the agent knows its replies land in Slack and must use Slack's mrkdwn dialect rather than standard CommonMark.
Package sysprompt builds the durable system-prompt text the relay injects into every ACP session so the agent knows its replies land in Slack and must use Slack's mrkdwn dialect rather than standard CommonMark.
verify
Package verify is the relay's self-verification harness: it drives real messages through real Slack and asserts that each inbound path behaved as designed.
Package verify is the relay's self-verification harness: it drives real messages through real Slack and asserts that each inbound path behaved as designed.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL