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.

https://github.com/user-attachments/assets/28a16e19-8359-4bf8-b110-f6f69c886d06

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):

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

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