Slack AI Agent

A Slack app powered by Claude Code SDK. Responds in DMs, channels, and @-mentions with streaming responses, thread context, file uploads, and extensible MCP tool integrations.

Architecture

  • src/slack-handler.ts - Message routing and event handling
  • src/claude-handler.ts - Session management and Claude Code SDK integration
  • src/mcp-manager.ts - MCP server configuration and tool management
  • src/message-processor.ts - Stream processing and response formatting
  • src/tracking.ts - Analytics tracking for message processing and feedback
  • src/channel-config.ts - Channel-specific context and configuration management
  • src/user-utils.ts - User information and role-based access control

Setup

1. Install

git clone https://github.com/duolingo/slack-ai-agent.git
npm install

2. Create Slack App

  1. Go to api.slack.com/apps → "Create New App" → "From an app manifest"
  2. Paste the contents of slack-app-manifest.yaml
  3. Install the app to your workspace
  4. Copy the Bot User OAuth Token (xoxb-...) from "OAuth & Permissions"
  5. Generate an App-Level Token with connections:write scope (xapp-...) from "Basic Information"
  6. Copy the Signing Secret from "Basic Information"

3. Configure Environment

cp .env.example .env

Fill in your tokens. See .env.example for all available variables.

4. Configure the Bot

Copy the example configs and customize for your workspace:

Required

Example file Copy to Purpose
config/example-emojis.yaml config/emojis.yaml Emoji reactions for thinking, completion, errors
config/example-tool-allowlist.yaml config/tool-allowlist.yaml Role-based tool access control (key order = role hierarchy)
config/example-tool-denylist.yaml config/tool-denylist.yaml Tools the bot must never use
config/instructions/example-general-context.txt config/instructions/general-context.txt Base system prompt injected into every response

Optional

Example file Copy to Purpose
config/example-channels.yaml config/channels.yaml Channel auto-reply routing, keyword triggers, ephemeral summaries
config/instructions/example-channel.txt config/instructions/<name>.txt Channel-specific system prompt context (referenced by channels.yaml)
config/subagents/example-subagents.yaml config/subagents/<name>.yaml Sub-agents for validation or post-processing
config/approvable-actions/example-approvable-action.ts config/approvable-actions/<name>.ts Human-in-the-loop actions (auto-discovered)
data/example-employees.yaml data/employees.yaml Employee directory for role assignment and people lookups
mcp-servers.example.json mcp-servers.json MCP server connections (GitHub, Slack, Jenkins, etc.)

Quick start:

cp .env.example .env
cp config/example-emojis.yaml config/emojis.yaml
cp config/example-tool-allowlist.yaml config/tool-allowlist.yaml
cp config/example-tool-denylist.yaml config/tool-denylist.yaml
cp config/instructions/example-general-context.txt config/instructions/general-context.txt

5. Run

npm run dev    # development (auto-reload)
npm run build && npm run prod  # production

Usage

  • DMs: responds to all messages
  • Configured channels: auto-replies based on channels.yaml rules
  • All other channels: responds only when @-mentioned
  • File uploads: supports images, code files, PDFs, and documents

Testing

npm test              # run all tests
npx jest --watch      # re-run on file changes
npx jest src/logger   # run tests matching a pattern

Tests use Jest with ts-jest. Test files live next to their source files as *.test.ts.

License

Apache 2.0 — see LICENSE.

Duolingo is hiring! Apply at https://www.duolingo.com/careers