https://github.com/duolingo/slack-ai-agent
Slack AI Agent - a Slack app with MCP connections that can answer questions and perform agentic actions on Slack.
https://github.com/duolingo/slack-ai-agent
agent mcp slack slack-app typescript
Last synced: 3 months ago
JSON representation
Slack AI Agent - a Slack app with MCP connections that can answer questions and perform agentic actions on Slack.
- Host: GitHub
- URL: https://github.com/duolingo/slack-ai-agent
- Owner: duolingo
- License: apache-2.0
- Created: 2026-03-24T18:13:23.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2026-04-01T04:28:53.000Z (3 months ago)
- Last Synced: 2026-04-01T07:05:52.824Z (3 months ago)
- Topics: agent, mcp, slack, slack-app, typescript
- Language: TypeScript
- Homepage:
- Size: 106 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```bash
git clone https://github.com/duolingo/slack-ai-agent.git
npm install
```
### 2. Create Slack App
1. Go to [api.slack.com/apps](https://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
```bash
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-reactions.yaml` | `config/reactions.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/.txt` | Channel-specific system prompt context (referenced by `channels.yaml`) |
| `config/subagents/example-subagents.yaml` | `config/subagents/.yaml` | Sub-agents for validation or post-processing |
| `config/approvable-actions/example-approvable-action.ts` | `config/approvable-actions/.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:
```bash
cp .env.example .env
cp config/example-reactions.yaml config/reactions.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
```bash
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
```bash
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](https://jestjs.io/) with `ts-jest`. Test files live next to their source files as `*.test.ts`.
## License
Apache 2.0 — see [LICENSE](LICENSE).
Duolingo is hiring! Apply at https://www.duolingo.com/careers