Buddy AI

Buddy AI is a self-hosted Slack bot powered by the Claude Agent SDK. It runs in Socket Mode and acts as a warm, memory-aware AI assistant for your whole family — no technical background needed. Buddy remembers each person across conversations, can run scheduled tasks, and is extensible via plugins and skills.

Features

• Conversational AI — DMs and @mentions via Slack Socket Mode, powered by Claude
• Long-term memory — per-person personal memory and family-shared memory that persists across sessions
• Cron scheduler — schedule recurring AI-driven tasks and digests
• Interactive UI — Slack Block Kit components, buttons, and forms
• Security guardrails — allowlist-based tool control and PreToolUse safety hooks
• Multiple LLM backends — Anthropic API, a Claude subscription, local LM Studio, or the OpenCode CLI
• Extensible — add capabilities via marketplace plugins and custom skills

Screenshots

Conversation — Chat with Buddy via DM or @mention in any channel.

Memory — Buddy remembers each person and your family across sessions.

Scheduled Digest — Cron-triggered AI summaries posted automatically to Slack.

Dashboard — Web UI for managing Buddy, secured with Sign in with Slack.

Quick Start

Prerequisites

• Python 3.12+
• uv
• A Slack app with Socket Mode enabled (create one here)
• An Anthropic API key — or see BACKENDS.md for free alternatives

Slack App Setup

Create a new Slack app and follow these steps:

1. OAuth Scopes (Bot Token)

Go to OAuth & Permissions → Scopes → Bot Token Scopes and add:

app_mentions:read, assistant:write, channels:history, channels:read, chat:write, files:read, files:write, groups:history, groups:read, im:history, im:read, mpim:read, reactions:read, reactions:write, users:read

assistant:write is required for Buddy to act as an AI agent within Slack.

Then click Install to Workspace — this generates your SLACK_BOT_TOKEN (xoxb-...).

2. Event Subscriptions

Go to Event Subscriptions, enable it, and subscribe to these bot events:

app_mention, message.im

3. Socket Mode

Go to Socket Mode and toggle it on. Then go to Basic Information → App-Level Tokens, click Generate Token, give it a name (e.g. socket-token), and add the connections:write scope. This generates your SLACK_APP_TOKEN (xapp-...).

Socket Mode lets Buddy receive events over a persistent WebSocket without exposing a public HTTP endpoint — no need to set up a request URL.

4. Dashboard Login (optional)

The Dashboard supports "Sign in with Slack" so only your family can log in. To enable it:

1. Go to OAuth & Permissions → Redirect URLs and add: https://your-buddy-domain.com/auth/callback
2. Go to Basic Information → App Credentials and copy your Client ID and Client Secret → set as SLACK_CLIENT_ID and SLACK_CLIENT_SECRET in .env
3. Set DASHBOARD_URL to your public deployment URL (e.g. https://buddy.yourdomain.com)

Installation

git clone https://github.com/your-org/buddy-ai.git
cd buddy-ai
uv sync
npm install --prefix .claude/mcp/slack

Configuration

cp .env.example .env

Variable	Required	Where to get it
SLACK_BOT_TOKEN	Yes	Slack app → OAuth & Permissions → Bot User OAuth Token (xoxb-...)
SLACK_APP_TOKEN	Yes	Slack app → Basic Information → App-Level Tokens → create one with connections:write scope (xapp-...)
SLACK_CLIENT_ID	For dashboard	Slack app → Basic Information → App Credentials
SLACK_CLIENT_SECRET	For dashboard	Slack app → Basic Information → App Credentials
ANTHROPIC_AUTH_TOKEN	Yes	Anthropic Console → API Keys — or see BACKENDS.md for free alternatives
ANTHROPIC_MODEL	No	Defaults to claude-sonnet-5-5
MODEL_BACKEND	No	anthropicapi (default) | claudecode | llmstudio | opencode
DASHBOARD_URL	No	Public URL of your deployment (e.g. https://buddy.yourdomain.com)
CONTACT_EMAIL	No	Shown to unauthorized users attempting to access Buddy

Each deployment is its own independent bot — create a dedicated Slack app per family and use your own tokens.

Copy whitelist.example.json to whitelist.json and add your family members' Slack user IDs:

{
  "allowed_users": [{ "id": "UXXXXXXXXX", "name": "Your Name", "role": 0 }]
}

Roles: 0 = admin, 1 = user, 2 = guest (blocked).

Run

uv run python app.py

Deployment (Docker)

cp .env.example .env              # fill in tokens
cp whitelist.example.json whitelist.json
docker-compose up -d

Includes an nginx reverse proxy with SSL. Place your certs in certs/cert.pem and certs/key.pem.

LLM Backends

Buddy AI supports multiple backends — see BACKENDS.md for setup.

Backend	MODEL_BACKEND	Cost
Anthropic API	anthropicapi	Paid
LM Studio (local)	llmstudio	Free
Claude subscription	claudecode	Subscription
OpenCode CLI	opencode	Free models available

Contributing

See .claude/CLAUDE.md for architecture details, code conventions, and how to add new backends or skills. The project is designed to work well with Claude Code — open it and the AI context loads automatically.

License

MIT