BubbleBuddy

BubbleBuddy is a fun Discord companion that lives in your servers. It gives Discord communities a shared AI buddy that remembers conversations separately for each channel and thread. It is powered by Pi, built with Effect v4, and can optionally use agentic coding abilities through Incus containers.

Features

• Separate Pi-backed assistant sessions for each channel and thread. Use any model or provider supported by Pi.
• Mention-based and ping-reply interaction support, with an optional automatic reply mode.
• Slash commands for managing sessions.
• MCP server support.
• Alarms and cron schedules with saved instructions.
• Sandboxed agentic workspace. When enabled, the assistant can use tools to interact with an Incus container, giving it access to project files and coding capabilities without exposing host credentials or environment variables.

Setup

Requirements

• Node.js
• pnpm
• A Discord account
• Access to whichever Pi model provider you configure

Discord bot setup

Create a Discord application and bot in the Discord Developer Portal.

BubbleBuddy's Discord client uses these gateway intents:

• Guilds
• GuildMessages
• MessageContent

Enable the privileged Message Content Intent for the bot, then invite it to your server:

https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&scope=bot+applications.commands&permissions=563364418276416

Replace YOUR_CLIENT_ID with the application ID from your Discord application. The permissions value includes message/reply basics such as viewing channels, sending messages in channels and threads, reading message history, embeds, attachments, reactions, external emoji/stickers, polls, mentions, and application commands.

BubbleBuddy currently supports guild text channels and threads. Direct messages and group DMs are not supported.

Local setup

BubbleBuddy is intended to be run from source for now.

pnpm install
cp packages/bubblebuddy/.env.example packages/bubblebuddy/.env

Edit packages/bubblebuddy/.env and set:

DISCORD_TOKEN=your-discord-bot-token

Configuration

App home directory

Configuration and state, including the database, sessions, and workspaces, is stored under the directory set by the BUBBLEBUDDY_HOME environment variable.

If BUBBLEBUDDY_HOME is unset, BubbleBuddy uses the platform-standard application data path:

• Linux: $XDG_DATA_HOME/bubblebuddy, falling back to ~/.local/share/bubblebuddy
• macOS: ~/Library/Application Support/BubbleBuddy
• Windows: %APPDATA%/BubbleBuddy, falling back to ~/AppData/Roaming/BubbleBuddy

First-run configuration

The $BUBBLEBUDDY_HOME/bubblebuddy.json configuration file will be generated on the first run. Edit the file with your Pi modelProvider and modelId to get started. Provider authentication comes from your system Pi configuration.

bubblebuddy.json reference

MCP server definitions

mcpServers is an object keyed by server name. Each value is either an HTTP/SSE server definition or a local command server definition.

HTTP/SSE server definition:

Local command server definition:

Running BubbleBuddy

Start BubbleBuddy in development mode:

pnpm run dev

Or run without watch mode:

pnpm run start

For checks, tests, formatting, linting, and typechecking scripts, see package.json.

Slash command reference

These commands apply to the current channel or thread:

• /abort — abort the current run, compaction, or retry.
• /compact — manually compact the current session.
• /new — discard the current session; the next interaction starts fresh.
• /reply-mode — set reply mode: mention-only (default) or automatic.
• /status — show current session status.
• /thinking — toggle thinking messages.

Scheduled wakeups

Ask BubbleBuddy to remind you about something or carry out a task later, once or on a recurring schedule.

• “Remind me to check the oven in 20 minutes.”
• “Post a weekday morning briefing at 9 AM, New York time.”
• “Remind us every Friday to submit timesheets, until the end of August.”

Schedules stay in the channel or thread where you create them and survive restarts and /new. You can ask what’s scheduled, change the timing or instructions, or cancel a schedule.

If the bot is offline, unexpired schedules catch up when it returns. Repeating tasks run once rather than replaying every missed occurrence. You can give repeating tasks an end date; once that time passes, no new work starts—including missed occurrences that weren’t picked up while the bot was offline. Work already started may still finish.

Delivery is best effort, and failed tasks aren’t automatically retried. Don’t rely on BubbleBuddy for critical reminders.

Project status and safety notes

BubbleBuddy is a personal project and still evolving.

Agentic workspace isolation relies on Incus and its container configuration. Built-in workspace tools and Discord file transfers access the container through the Incus API. A shared workspace mount on the same host is still required for loading workspace AGENTS.md and skills; it is not used to enforce tool isolation.