Slack Knowledge Assistant

An open-source Slack bot that answers your team's questions by searching across all of your company's tools using Airweave.

airweave-slack-assistant.mp4

Connect sources like GitHub, Notion, Linear, Google Drive, Jira, Confluence, Slack, and 50+ others. Ask a question in Slack, and the assistant searches across everything and responds with a well-formatted answer and source citations.

How it works

@assistant How does our authentication system work?

The assistant:

1. Reacts with a thinking emoji while it works
2. Contextualizes follow-up questions using thread history (so "what about the API?" works in context)
3. Searches across all your connected sources via Airweave (hybrid semantic + keyword search with reranking)
4. Generates an AI answer from search results
5. Polishes the answer for Slack, confidence-graded based on source quality
6. Posts a rich reply with source citations linking back to the original documents
7. Adapts if teammates reply while it's thinking, so it won't repeat what humans already said

What it responds to

• @mentions in any channel the bot is in
• Direct messages to the bot
• Thread follow-ups when you @mention it again in a thread

Conversational threads

In threads, the assistant acts as a full chatbot backed by Airweave search. It remembers the entire conversation and rewrites your follow-up questions into standalone search queries, so you can ask things like "what about the API?" or "who built that?" and it understands the context.

Source-aware answers

The assistant adapts its language based on where information comes from:

• Notion → "This is documented in..."
• GitHub → "This is implemented in..."
• Linear / Jira → "This is tracked in..."
• Slack → "This was discussed in..."

Prerequisites

1. Airweave account with a collection that has your tools connected
2. Anthropic API key for Claude
3. Slack workspace where you can create apps

Setup

1. Create a Slack App

1. Go to api.slack.com/apps and click Create New App → From scratch
2. Name it (e.g. "Knowledge Assistant") and select your workspace

Bot Token Scopes (under OAuth & Permissions):

Scope	Why
app_mentions:read	Detect @mentions
channels:history	Read channel messages for thread context
chat:write	Post answers
groups:history	Read private channel messages
im:history	Read DMs
im:read	View DM metadata
im:write	Send DMs
mpim:history	Read group DMs
reactions:read	Read reactions
reactions:write	Add/remove thinking and done reactions

Event Subscriptions:

1. Enable Events and set the Request URL to https://your-domain.com/slack/events

2. Subscribe to these bot events:

   • app_mention
   • message.im

3. Install the app to your workspace and copy the Bot User OAuth Token (xoxb-...) and the Signing Secret from the Basic Information page.

2. Configure Environment

cp .env.example .env

Fill in your .env:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
AIRWEAVE_API_KEY=your-airweave-api-key
AIRWEAVE_COLLECTION_ID=your-collection-id
ANTHROPIC_API_KEY=your-anthropic-api-key

3. Install and Run

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000

4. Set the Slack Events URL

Once your server is publicly accessible, go back to your Slack app's Event Subscriptions and set the Request URL:

https://your-domain.com/slack/events

Slack sends a verification challenge that the app handles automatically.

Deployment

This is a standard FastAPI app. Deploy it anywhere that runs Python.

Railway / Render / Fly.io

Set the start command:

uvicorn app.main:app --host 0.0.0.0 --port $PORT

Add your environment variables in the platform's dashboard.

Docker

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Local development (ngrok)

# Terminal 1
uvicorn app.main:app --host 0.0.0.0 --port 8000

# Terminal 2
ngrok http 8000

Use the ngrok URL as your Slack Events URL: https://abc123.ngrok.io/slack/events

Configuration

Variable	Required	Default	Description
SLACK_BOT_TOKEN	Yes	-	Slack bot token (xoxb-...)
SLACK_SIGNING_SECRET	Yes	-	Slack app signing secret
AIRWEAVE_API_KEY	Yes	-	Airweave API key
AIRWEAVE_COLLECTION_ID	Yes	-	Airweave collection readable ID
ANTHROPIC_API_KEY	Yes	-	Anthropic API key
AIRWEAVE_API_URL	No	https://api.airweave.ai	Airweave API URL
SLACK_BOT_USER_ID	No	Auto-detected	Bot's Slack user ID
SLACK_ACTIVITY_CHANNEL	No	-	Channel to log assistant activity
LLM_POLISH_MODEL	No	claude-sonnet-4-5	Model for answer polishing
LLM_FAST_MODEL	No	claude-3-5-haiku-latest	Model for query contextualization
LOG_LEVEL	No	INFO	Logging level

Architecture

Slack Event (@mention / DM / thread reply)
    │
    ▼
┌─────────────────────────────┐
│  FastAPI Event Handler      │  ← Verifies Slack signature, returns 200 in <3s
│  (app/main.py)              │    Dispatches to background thread
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│  KnowledgeAssistant         │  ← Main pipeline orchestrator
│  (app/assistant.py)         │
│                             │
│  1. Thread context          │  ← Fetches conversation history
│  2. Query contextualization │  ← Claude Haiku rewrites follow-ups
│  3. Airweave search         │  ← Hybrid search + AI answer generation
│  4. Human reply detection   │  ← Checks if teammates answered meanwhile
│  5. Answer polishing        │  ← Claude Sonnet formats for Slack
│  6. Post reply              │  ← Rich Block Kit message with sources
└──────────┬──────────────────┘
           │
     ┌─────┴─────┐
     ▼           ▼
┌─────────┐ ┌──────────┐
│ Airweave│ │ Anthropic│
│   API   │ │   API    │
└─────────┘ └──────────┘

Project Structure

slack-knowledge-assistant/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI app + Slack event handler
│   ├── assistant.py          # Knowledge assistant pipeline
│   ├── context.py            # Thread context builder
│   ├── formatter.py          # Slack Block Kit message formatting
│   └── airweave_client.py    # Airweave search client
├── .env.example
├── .gitignore
├── requirements.txt
├── LICENSE
└── README.md

License

MIT