Claude Code Slack

Let your team talk to Claude Code directly from Slack. Claude runs locally on your machine using your existing Claude plan — no API keys, no per-token costs. Your codebase, your CLAUDE.md, your MCP tools — all accessible through a Slack message.

You (Slack):  @Claude What files are in the src directory?
Bot (Slack):  Found 12 files in src/: index.ts, app.ts, config.ts...

Mention @YourBot in any channel, DM it directly, or use the optional /claude slash command. Reply in threads and it remembers the full conversation.

How It Works

                        ┌──────────────────────────┐
                        │   Slack (your workspace)  │
                        │                          │
                        │  /claude <prompt>        │
                        │  @bot <message>          │
                        └──────────┬───────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────────┐
                    │  Worker (Railway / any host)  │
                    │                              │
                    │  FastAPI webhook receiver     │
                    │  Slack signature verification │
                    │  Quick commands (help, status)│
                    │                              │
                    │  AI tasks → writes JSON to    │
                    │  GitHub tasks/ directory      │
                    └──────────────┬───────────────┘
                                   │
                          GitHub repo (tasks/)
                                   │
                                   ▼
                    ┌──────────────────────────────┐
                    │  Daemon (your Mac, always on) │
                    │                              │
                    │  Polls GitHub every 5s        │
                    │  Picks up task JSON files     │
                    │  Runs: claude -p "prompt"     │
                    │  Posts result to Slack        │
                    │  Deletes task file            │
                    │  Auto-commits workspace       │
                    └──────────────────────────────┘

Why this architecture?

• Claude Code CLI runs locally with your subscription (no API key costs)
• Claude has full access to your codebase, CLAUDE.md, and MCP tools
• Your workspace stays on your machine — the worker only routes messages
• Thread context is preserved (the daemon fetches Slack thread history)

Your repos stay separate

The daemon and your project don't need to live in the same folder. The daemon installs to its own directory (~/claude-code-slack/ by default), and WORKSPACE_DIR in its .env file points to wherever your repo clone lives. They're completely independent.

Claude Code runs inside WORKSPACE_DIR, so it automatically picks up any CLAUDE.md file in that repo. This means you can give Claude project-specific instructions that apply to every Slack command:

# CLAUDE.md (in your project repo root)

This is a Next.js 14 app with App Router.
- Tests are in __tests__/ — run with `npm test`
- Never modify .env or .env.local
- API routes are in app/api/
- We use Tailwind CSS and shadcn/ui

When someone asks @Bot how do I add a new API route?, Claude already knows your project structure and conventions.

Features

• Slash commands — /claude <anything> from any channel
• @mentions — @YourBot summarize the README in channels
• DMs — Message the bot directly for private conversations
• Thread context — Reply in threads and the bot sees prior messages
• Markdown conversion — Claude's markdown output is converted to Slack's mrkdwn format
• Auto-sync — Workspace changes are committed and pushed after each task
• Menu bar status — Green/red circle shows daemon health at a glance (macOS)
• Workspace isolation — Claude runs in a separate clone, not your working directory

Prerequisites

Install prerequisites

# Node.js (via nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts

# Claude Code CLI
npm install -g @anthropic-ai/claude-code

# GitHub CLI
brew install gh   # or download from https://github.com/cli/cli/releases
gh auth login

# Python dependencies (daemon)
pip3 install httpx python-dotenv rumps

Setup

1. Create a GitHub repo for your workspace

This is the repo Claude Code will operate on. It can be an existing project or a new one.

# Option A: Use an existing repo
# Just note the owner/name, e.g. "youruser/my-project"

# Option B: Create a dedicated workspace repo
gh repo create my-claude-workspace --private

Create a tasks/ directory with a .gitkeep:

cd my-claude-workspace
mkdir tasks
touch tasks/.gitkeep
git add tasks/.gitkeep && git commit -m "Add tasks directory" && git push

2. Clone the workspace (for the daemon)

The daemon needs a separate clone — not your working directory. This prevents Claude from accessing personal files.

gh repo clone youruser/my-project ~/claude-workspace

3. Create a GitHub Personal Access Token

1. Go to https://github.com/settings/tokens
2. Generate new token (classic) with repo scope
3. Copy the token — you'll need it for both daemon and worker

4. Create a Slack App

1. Go to https://api.slack.com/apps
2. Click Create New App → From scratch
3. Name it (e.g., "Claude Code") and select your workspace

Bot Token Scopes

Navigate to OAuth & Permissions and add these Bot Token Scopes:

Event Subscriptions

Navigate to Event Subscriptions:

1. Toggle Enable Events to On
2. Set Request URL to: https://your-railway-url.up.railway.app/slack/events
   (You'll get this URL after deploying the worker — come back to this step)
3. Under Subscribe to bot events, add:
   • app_mention
   • message.im

Slash Commands

Navigate to Slash Commands and create one:

Install the App

1. Navigate to Install App
2. Click Install to Workspace
3. Copy the Bot User OAuth Token (xoxb-...)
4. Go to Basic Information and copy the Signing Secret

5. Deploy the Worker (Railway)

Railway is the easiest option, but any container host works (Fly.io, Render, etc.).

Option A: Railway (recommended)

1. Fork or push this repo to GitHub
2. Go to https://railway.app and create a new project
3. Select Deploy from GitHub repo
4. Set the Root Directory to worker/
5. Add environment variables:

1. Deploy. Copy the public URL (e.g., https://your-app.up.railway.app)
2. Go back to your Slack app settings and update the Request URL for both Events and Slash Commands to: https://your-app.up.railway.app/slack/events

Option B: Docker (self-hosted)

cd worker
docker build -t claude-code-slack-worker .
docker run -p 8080:8080 --env-file .env claude-code-slack-worker

6. Set Up the Local Daemon

cd daemon

# Create .env from template
cp .env.example .env

# Edit with your values
# IMPORTANT: Set WORKSPACE_DIR to the CLONED repo path, not your working directory
nano .env

Install as macOS LaunchAgent (recommended)

pip3 install -r requirements.txt
chmod +x install.sh start-daemon.sh
./install.sh

This will:

• Copy daemon files to ~/claude-code-slack/
• Auto-detect Claude CLI and Node.js paths
• Generate LaunchAgent plists
• Start the daemon and status bar

Manual start (alternative)

# Must set PATH to include node
PATH="$(dirname $(which node)):$PATH" python3 main.py

7. Test It

1. Check the menu bar for a green circle (daemon running)
2. In Slack, type: /claude what files do you see?
3. You should get a response within 10-30 seconds

Configuration Reference

Daemon (.env)

Worker (.env)

Troubleshooting

Daemon won't start

Worker issues

Slack issues

GitHub issues

macOS-specific

Managing the Daemon

# View logs
tail -f ~/Library/Logs/claude-code-slack-daemon.log

# Restart daemon
launchctl kickstart -k gui/$(id -u)/com.claude-code-slack.daemon

# Stop daemon
launchctl unload ~/Library/LaunchAgents/com.claude-code-slack.daemon.plist

# Start daemon
launchctl load ~/Library/LaunchAgents/com.claude-code-slack.daemon.plist

# Full uninstall
cd daemon && ./install.sh uninstall

How Thread Context Works

When you reply in a Slack thread, the daemon fetches the full thread history and injects it as context for Claude. This means Claude "sees" the prior conversation:

User:  @Bot What does the auth module do?
Bot:   The auth module handles JWT token generation and validation...

User:  (in thread) Can you refactor it to use sessions instead?
Bot:   Based on our discussion about the auth module, here's how to
       refactor from JWT to sessions...

The context is reconstructed from Slack's API on each request — no local state needed.

Security Considerations

• Workspace isolation — Always point WORKSPACE_DIR at a separate clone, not your working directory. This prevents Claude from accessing personal files, credentials, or other repos.
• Slack signature verification — The worker validates every request using Slack's HMAC-SHA256 signature. Never disable this in production.
• GitHub token scope — Use a fine-grained PAT scoped to only the repos you need.
• No secrets in responses — Be mindful that Claude's output is posted to Slack. If your codebase contains secrets, Claude might reference them. Use .gitignore and .env files properly.

License

MIT

Built by Alcanah Partners — AI operations for growing businesses.