Claude Code Slack Bot

A Slack bot that integrates with Claude Code SDK to provide AI-powered coding assistance directly in your Slack workspace.

Features

• 🤖 Direct message support - chat with the bot privately
• 💬 Thread support - maintains conversation context within threads
• 🔄 Streaming responses - see Claude's responses as they're generated
• 📝 Markdown formatting - code blocks and formatting are preserved
• 🔧 Session management - maintains conversation context across messages
• ⚡ Real-time updates - messages update as Claude thinks

Prerequisites

• Node.js 18+ installed
• A Slack workspace where you can install apps
• Claude Code

Setup

1. Clone and Install

git clone <your-repo>
cd claude-code-slack
npm install

2. Create Slack App

Option A: Using App Manifest (Recommended)

1. Go to api.slack.com/apps and click "Create New App"
2. Choose "From an app manifest"
3. Select your workspace
4. Paste the contents of slack-app-manifest.json (or slack-app-manifest.yaml)
5. Review and create the app

Option B: Manual Configuration

1. Go to api.slack.com/apps and create a new app
2. Choose "From scratch" and give your app a name
3. Select the workspace where you want to install it

3. Configure Slack App

After creating the app (either method), you need to:

Generate Tokens

1. Go to "OAuth & Permissions" and install the app to your workspace
2. Copy the "Bot User OAuth Token" (starts with xoxb-)
3. Go to "Basic Information" → "App-Level Tokens"
4. Generate a token with connections:write scope
5. Copy the token (starts with xapp-)

Get Signing Secret

1. Go to "Basic Information"
2. Copy the "Signing Secret"

4. Configure Environment

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Edit .env:

# Slack App Configuration
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_SIGNING_SECRET=your-signing-secret

# Claude Code Configuration
# This is only needed if you don't use a Claude subscription

# ANTHROPIC_API_KEY=your-anthropic-api-key
# CLAUDE_CODE_USE_BEDROCK=1
# CLAUDE_CODE_USE_VERTEX=1

5. Run the Bot

# Development mode (with auto-reload)
npm run dev

# Production mode
npm run build
npm run prod

Usage

Setting Working Directory

Before using Claude Code, you must set a working directory. This tells Claude where your project files are located.

Set working directory:

Relative paths (if BASE_DIRECTORY is configured):

cwd project-name

Absolute paths:

cwd /path/to/your/project

or

set directory /path/to/your/project

Check current working directory:

cwd

or

get directory

When you set or check the working directory, the bot will display:

• Directory path
• Process ID (PID)
• Hostname

Working Directory Scope

• Direct Messages: Working directory is set for the entire conversation
• Channels: Working directory is set for the entire channel (prompted when bot joins)
• Threads: Can override the channel/DM directory for a specific thread by mentioning the bot

Base Directory Configuration

You can configure a base directory in your .env file to use relative paths:

BASE_DIRECTORY=/Users/username/Code/

With this set, you can use:

• cwd herd-website → resolves to /Users/username/Code/herd-website
• cwd /absolute/path → uses absolute path directly

Permission Modes

The bot supports 3 permission modes for tool execution:

Mode	Command	Description
🔐 approval	approval on	All tool executions require user approval (default)
🔓 bypass	bypass on	All tools execute without approval
🤖 auto	auto on	Tools execute automatically, only dangerous operations are blocked

Check current mode:

mode

Auto Mode Safety

In auto mode, the following dangerous operations are automatically blocked:

• File deletion: rm -rf *, rm -rf /, rm ~, etc.
• Git destructive operations: git push --force, git reset --hard, git clean -fd
• Permission changes: sudo, chmod 777, chown -R
• Remote code execution: curl ... | sh, wget ... | bash
• Environment variable exposure: env, printenv, cat .env
• Process operations: kill -9, pkill, killall
• Package publishing: npm publish, yarn publish
• Writing outside working directory

Session Management

Share sessions between your PC terminal and Slack.

View session info:

session

This displays:

• Session ID
• Working directory
• Process ID
• Hostname
• Resume command for your PC

Attach external session:

session <session-id>

Share session between PC and Slack:

From Slack to PC:

1. Run session in Slack
2. Copy the displayed resume command
3. Run it in your PC terminal: cd /path/to/project && claude --resume <session-id>

From PC to Slack:

1. Start claude in your terminal
2. Copy the session ID from ~/.claude/projects/<project-dir>/
3. In Slack: session <session-id>

Note: Sessions are stored per working directory. You must run claude --resume from the same directory where the session was created.

Direct Messages

Simply send a direct message to the bot with your request:

@ClaudeBot Can you help me write a Python function to calculate fibonacci numbers?

In Channels

When you first add the bot to a channel, it will ask for a default working directory for that channel.

Mention the bot in any channel where it's been added:

@ClaudeBot Please review this code and suggest improvements

Thread-Specific Working Directories

You can override the channel's default working directory for a specific thread:

@ClaudeBot cwd different-project
@ClaudeBot Now help me with this specific project

Threads

Reply in a thread to maintain conversation context. The bot will remember previous messages in the thread.

File Uploads

You can upload files and images directly to any conversation:

Supported File Types:

• Images: JPG, PNG, GIF, WebP, SVG
• Text Files: TXT, MD, JSON, JS, TS, PY, Java, etc.
• Documents: PDF, DOCX (limited support)
• Code Files: Most programming languages

Usage:

1. Upload a file by dragging and dropping or using the attachment button
2. Add optional text to describe what you want Claude to do with the file
3. Claude will analyze the file content and provide assistance

Note: Files are temporarily downloaded for processing and automatically cleaned up after analysis.

MCP (Model Context Protocol) Servers

The bot supports MCP servers to extend Claude's capabilities with additional tools and resources.

Setup MCP Servers

1. Create MCP configuration file:

   cp mcp-servers.example.json mcp-servers.json

2. Configure your servers in mcp-servers.json:

   {
     "mcpServers": {
       "filesystem": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
       },
       "github": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-github"],
         "env": {
           "GITHUB_TOKEN": "your-token"
         }
       }
     }
   }

MCP Commands

• View configured servers: mcp or servers
• Reload configuration: mcp reload

Available MCP Servers

• Filesystem: File system access (@modelcontextprotocol/server-filesystem)
• GitHub: GitHub API integration (@modelcontextprotocol/server-github)
• PostgreSQL: Database access (@modelcontextprotocol/server-postgres)
• Web Search: Search capabilities (custom servers)

All MCP tools are automatically allowed and follow the pattern: mcp__serverName__toolName

Command Reference

Command	Description
cwd /path	Set working directory
cwd	Show current working directory
approval on	Enable approval mode (default)
bypass on	Enable bypass mode
auto on	Enable auto mode
mode	Show current permission mode
session	Show session info
session <id>	Attach external session
mcp	Show MCP servers
mcp reload	Reload MCP configuration

Advanced Configuration

Using AWS Bedrock

Set these environment variables:

CLAUDE_CODE_USE_BEDROCK=1
# AWS credentials should be configured via AWS CLI or IAM roles

Using Google Vertex AI

Set these environment variables:

CLAUDE_CODE_USE_VERTEX=1
# Google Cloud credentials should be configured

Development

Debug Mode

Enable debug logging by setting DEBUG=true in your .env file:

DEBUG=true

This will show detailed logs including:

• Incoming Slack messages
• Claude SDK request/response details
• Session management operations
• Message streaming updates

Project Structure

src/
├── index.ts          # Application entry point
├── config.ts         # Configuration management
├── types.ts                      # TypeScript type definitions
├── claude-handler.ts             # Claude Code SDK integration
├── slack-handler.ts              # Slack event handling
├── working-directory-manager.ts  # Working directory management
└── logger.ts                     # Logging utility

Available Scripts

• npm run dev - Start in development mode with hot reload
• npm run build - Build TypeScript to JavaScript
• npm start - Run the compiled JavaScript
• npm run prod - Run production build

Troubleshooting

Bot not responding

1. Check that the bot is running (npm run dev)
2. Verify all environment variables are set correctly
3. Ensure the bot has been invited to the channel
4. Check Slack app permissions are configured correctly

Authentication errors

1. Verify your Anthropic API key is valid
2. Check Slack tokens haven't expired
3. Ensure Socket Mode is enabled

Message formatting issues

The bot converts Claude's markdown to Slack's formatting. Some complex formatting may not translate perfectly.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT