Claude ↔ Slack Bridge
A two-way bridge between Claude Code and Slack:
- Claude → Slack: Claude pauses mid-task, asks a question via Slack, waits for your reply, and resumes.
- Slack → Claude: Tag the bot in a Slack channel and Claude runs with full project context — it knows which project to work on based on the channel.
Claude Code ──ask_on_slack──▶ Slack channel ──your reply──▶ Claude Code resumes
Slack @bot ──────────────────▶ claude -p (in project dir) ──▶ reply in thread
What It Does
ask_on_slackMCP tool — Claude pauses mid-task, posts a question to Slack, blocks until you reply in the thread, then resumes. Multiple concurrent sessions are routed correctly bythread_ts.- Project-aware Slack bot —
@claude-botin a Slack channel spawnsclaude -pin the matching project directory inside the container. Supports git worktrees via a[label]prefix. - Live progress, no timeout — a run has no wall-clock limit; it works until it finishes or you stop it. While it runs, the bot edits one status message in the thread: a todo checklist, recent actions (newest first, up to 99/update), a changed-files section with per-file
+/−churn, and a grey resource line (per-tool breakdown, subagents, skills used, MCP servers, compaction count, errors, tokens in/out/cache + estimated cost, context used/window + %, turns, model, elapsed) — all derived from the CLI's event stream with no extra model calls. Actions are numbered (newest = highest, on top). A quiet run shows an⏳ idlehint (IDLE_HINT_SECONDS); a genuinely stuck one (no activity forIDLE_TIMEOUT_SECONDS) is killed. When it finishes, the message keeps the full panel with a✅ Doneheadline on top (the whole greyed section stays — nothing is collapsed away). Per-model context windows and prices live inmodel_context.json. Turn the live message off withLIVE_PROGRESS=false(stop then falls back to the 🛑 reaction). Preview the layout locally withtools/preview_status.py. - Stop a running task — react with 🛑 to the live status message (the bot pre-adds the 🛑 there) or to the message that started the run. Either way the bot kills it (and everything it spawned), posts
⏹️ Stopped., and drops the partial reply. No Slack Interactivity setup needed — it's a plain reaction. - Full-process plugin — a turnkey feature-development workflow driven from Slack (
/process start→ pick a task → worktree → design → plan → run-plan → PR per step).
Quickstart — Claude → Slack
1. Create a Slack app and get tokens
Follow docs/slack-setup.md to create a Slack app, get your xoxb- and xapp- tokens, and invite the bot to a channel.
(Optional) If you plan to use the /process workflow — which opens GitHub PRs and reads review comments from inside the container — also follow docs/github-setup.md to create a fine-grained PAT and set GITHUB_TOKEN. Skip this if you don't need GitHub integration.
2. Clone, configure, and start the daemon
git clone https://github.com/your-username/claude-slack-bridge.git
cd claude-slack-bridge
cp .env.example .env # fill in SLACK_BOT_TOKEN and SLACK_APP_TOKEN
docker compose up -d --build
The container starts automatically on system boot (restart: unless-stopped) and uses Socket Mode — no public URL or inbound firewall rules needed.
You only do this once. The daemon stays running in the background and serves all your Claude Code projects.
3. Add .mcp.json to your Claude Code project
Create .mcp.json in the root of any project where you want Claude to be able to ask you questions:
{
"mcpServers": {
"claude-slack-bridge": {
"command": "docker",
"args": [
"exec", "-i",
"-e", "SLACK_CHANNEL",
"claude-slack-bridge",
"python", "session.py"
],
"env": {
"SLACK_CHANNEL": "#your-project-channel"
}
}
}
}
Important: Add
.mcp.jsonto your.gitignore— it contains your channel name and is project-specific.
4. Add the Slack communication rule to your CLAUDE.md
To make Claude automatically use Slack for all communication once it sends its first message, add the following to your project's CLAUDE.md:
Once you use `mcp__claude-slack-bridge__ask_on_slack` for the first time in a conversation, ALL further communication with the user must go through that tool. Do not use `AskUserQuestion`, and do not ask questions or request feedback as text in the terminal. Continue communicating exclusively via Slack until the user explicitly tells you to switch back to the terminal.
Open the project in Claude Code and Claude will have access to ask_on_slack. Reply in the Slack thread (not the channel directly) and Claude resumes from where it left off.
Quickstart — Slack → Claude
Tag the bot in a Slack channel and Claude runs inside the matching project directory.
1. Set PROJECTS_DIR in .env
PROJECTS_DIR=C:\Users\you\projects
This is the parent directory that contains all your projects. It's mounted into the container at /projects/.
2. Create projects.json
Map each Slack channel to a project folder:
{
"#my-project-channel": "/projects/my-project"
}
Apply mapping edits without a restart: projects.json is read once at startup. After editing it, reload it live — keeping the Slack connection and any in-flight runs alive — instead of restarting:
./reload-mapping.sh # → "reloaded N channel(s)"
kill -HUP <daemon-pid> # no CLI needed; same effect, no confirmation line
The reload affects only new threads; conversations already running stay in the directory they started in. See docs/reloading-projects.md.
3. Rebuild
docker compose up -d --build
Then in Slack:
@claude-bot fix the login redirect bug
The bot replies in a thread. Continue the conversation by replying in that thread.
Stopping a running task
Click the 🛑 reaction to stop a run — the bot kills the task (and any subprocesses it spawned), posts ⏹️ Stopped. in the thread, and discards the partial reply. The bot pre-adds a 🛑 you can click on:
- the live status message — once it appears (with
LIVE_PROGRESSon), the 🛑 lives there and is removed from the trigger message; - the message that triggered the run — used before the status message appears, or for the whole run when
LIVE_PROGRESS=false.
Requires the
reactions:read/reactions:writescopes and thereaction_addedevent from docs/slack-setup.md. No Slack Interactivity config is needed (stopping is a plain reaction, not a button). If you set up the app before this feature existed, add them and reinstall the app.
→ Full reference (channel formats, plugin_dir, worktrees, routing rules): docs/slack-to-claude-projects.md
The full-process plugin
A turnkey feature-development workflow driven entirely from Slack. After a one-time /process-setup in your repo, you can start a feature from Slack with:
@claude-bot /process start
The bot lists your open tasks (from Notion, Linear, Jira, …), creates a git worktree for the one you pick, walks the work through your configured steps (typically design → plan → run-plan), opens a GitHub PR after each step, and waits for your approval in Slack before moving on.
→ Full guide: docs/full-process-plugin.md
Next steps
Requirements
- Docker (with Docker Compose)
- A Slack workspace where you can create apps
- Claude Code (or any MCP-compatible client)
License
MIT
