English | 日本語

Note

This README is a quick overview. For the full, up-to-date documentation (setup guides, feature walkthroughs, provider info, and more) visit docs.tomoribot.app.

TomoriBot

A self-hosted and customizable personal AI assistant/role-playing system for Discord with memory, multiple personas, tool calling, multimodality, and API/local model support.

Official Website · Invite TomoriBot · Discord Server
Latest Releases · Report Bug · Request Feature

About the Project

TomoriBot is a free and open-source self-hosted personal AI assistant and role-playing system for Discord, inspired by SillyTavern and Discord's discontinued Clyde. It can be used as a practical assistant, customizable companion, and role-play partner for yourself in DMs, or for everyone in your Discord server.

TomoriBot supports long-term memory, multi-persona behavior, web and MCP tools, in-chat media generation, 200+ Discord slash commands, and multiple providers including custom proxies and self-hosting your own models for everything from text generation to video generation.

Getting Started

You can invite the public TomoriBot to your Discord server, or self-host your own instance if you prefer full control over your privacy and API keys. TomoriBot uses best security practices and encryption that keeps data safe, but self-hosting ensures that all data remain entirely on your device.

After adding her to your server through either method above, run the /config setup command for instructions. Then you can simply say her name (or @ mention her) in order to get a response.

Feature Showcase

Agentic AI-Powered Conversation

TomoriBot has LOTS of tools that allows her to go beyond just chatting, such as searching the web, setting recurrent tasks/reminders, utilizing your server's emotes/stickers, and memory options such as RAG and STM that allow her to remember context across channels and servers.

Complete Multimodal Input/Output

TomoriBot can process images, audio, and video sent directly in Discord and generate them in return using your own local model endpoints or through API keys, all of which are encrypted inside a persistent database. Ready-to-use ComfyUI workflows can be found in assets/comfyui-workflows/ and local audio inference servers in servers/!

Multi-Persona Support

TomoriBot's in-server personality, behavior, and avatar can be easily changed, created, as well as exported for others as Personas (akin to shareable AI Character Cards). Import and even transform your favorite SillyTavern cards through /persona generate. You can have an unlimited amount of different personas in a single server, each having their own memories and agendas. You can also orchestrate them to work with each other to do work in your server (or just mess around with each other).

200+ Native Commands for Configuration

Everything can be managed through Discord's native slash commands and interactive UI. Completely manage personas, prompts, tweak model parameters, set up MCP tool servers, adjust permissions, configure memory, set server member rate limits, and much more! You can also ask TomoriBot directly on what she can do and what her slash commands are. Currently, a Web Dashboard is in the works for even easier management.

SillyTavern Integration (Beta)

Use your favorite SillyTavern presets directly in Discord through TomoriBot which adjusts her prompt completely, just plop the .json right in through st-preset. Discord's new native checkbox groups for modals makes it easy to toggle nodes on and off like in SillyTavern. You can also import SillyTavern character cards directly through /persona import or you can modify them first with /persona generate.

Lots of More Features, and Counting!

A bunch of fun features that are easy to setup ranging from practical automatic greetings for new server members and cross-channel movement, to silly ones like user impersonations for some trolling. New ones are constantly in development, so please report through GitHub issues or the official Discord for any bugs (or to share any fun suggestions).

Useful Resources

Full List of Supported Providers

TomoriBot supports a wide range of LLM providers, image generation APIs, voice services, and search tools out of the box.

How to run Local Models

TomoriBot supports local LLMs (via KoboldCPP, LM Studio, vLLM, etc.), local image/video generation via ComfyUI, local TTS and STT endpoints, as well as local SearXNG and Browser web fetch Docker sidecars.

Security & Threat Models

TomoriBot employs encryption and security best practices to keep data and API keys completely safe, both for local setups as well as for those using the public deploy.

Tool Macros for Prompt Customization

TomoriBot comes with a variety of built-in tools (such as web search, memory management, image generation, cross-channel messaging, and more), which you can directly refer to in your prompts with macros, here are some silly examples:

1. Wellness Checker

Every few hours, do a mandatory wellness check on @Bredrumb. 
Ask them how they feel right now and if they've taken a break from coding recently. 
Track their emotional state over time with {memory_tool} and/or {memory_update_tool} to report back to them later.

2. Weekly Current Events Yuri News

Every Friday, compile the week's notable yuri manga chapters, anime episodes, and community fanart drops using {web_search_tool}. 
Present findings with {voice_message_tool} in a seductive ASMR voice.

3. Sleep Police

If you notice through {message_metadata_tool} that someone is chatting past 2 AM, use {voice_message_tool} to send them a threateningly calm ASMR lullaby telling them to go to bed. 
If they keep talking 10 minutes later, use {manage_message_tool} to delete their message for their own good and remind them that sleep deprivation is a leading cause of their issues.

Official TomoriBot Roadmap

Stay in the loop for TomoriBot's planned features as well as all known issues.

Self-Hosting

Choose one install path:

• A. Local Bun Setup (Recommended): requires Bun, Node.js v20+ for MCP tooling, and either PostgreSQL or Docker for the database.
• B. Docker Compose Setup: requires Docker only for running the bot/database, but host-side maintenance scripts still need host tooling.

The recommended path for most self-hosters is the local Bun setup wizard. Its default Full Install path creates .env, generates a safe CRYPTO_SECRET, asks for your Discord bot token, configures PostgreSQL, runs bun install --frozen-lockfile, then attempts the lightweight database and AI helper extras.

A. Local Bun Setup

1. Clone the repository

   git clone https://github.com/Bredrumb/TomoriBot.git
   cd TomoriBot

2. Run the setup wizard (more info at Setup Wizard guide)

   bun run setup

3. Start TomoriBot

   bun run dev

Once you see TomoriBot up and running!, run /config setup in Discord.

B. Docker Compose Setup

Docker Compose builds and runs TomoriBot plus PostgreSQL. It does not use the setup wizard.

Required .env variables for Docker Compose:

• DISCORD_TOKEN - Your Discord bot token
• CRYPTO_SECRET - 32-character encryption key
• POSTGRES_PASSWORD - Database password (other DB settings are auto-configured)

For Docker Compose, start from .env.example, then add POSTGRES_PASSWORD if you have not already set it. Optional Docker or runtime tuning values can still be copied from .env.optional.example.

# Build and start TomoriBot and her database
docker compose up --build

For later starts, docker compose up is enough unless you changed code or dependencies.

C. Optional Sidecars & Servers

TomoriBot supports opt-in sidecar/server services alongside either setup path to enhance her tools and add local monitoring: SearXNG for web search, Crawl4AI for browser-rendered page fetches, and local TTS/STT voice servers.

With the local Bun setup (A), use bun run launch instead of bun run dev, example runs:

# With SearXNG and Crawl4AI Docker sidecars
bun run launch --searxng --crawl4ai

# With a local TTS server after following the voice setup docs
bun run launch --qwen3tts

# See all available flags
bun run launch --help

Available flags: --searxng, --crawl4ai, --qwen3tts, --chatterbox, --irodoritts, --whisperx, --help

Ctrl+C stops the bot and any Python sidecar processes. Docker containers (--searxng, --crawl4ai) are intentionally left running, stop them manually with docker stop searxng / docker stop crawl4ai when you're done.

With Docker Compose (B), sidecars are opt-in via Compose profiles instead:

# + SearXNG web search (self-hosted metasearch)
docker compose --profile searxng up

# + Crawl4AI browser-rendered page fetching
docker compose --profile fetch-crawl4ai up

# + Both at once
docker compose --profile searxng --profile fetch-crawl4ai up

See the guides below for full setup details:

• SearXNG Web Search Sidecar - A self-hosted metasearch instance to bypass single-engine API limits for the web_search tool.
• Crawl4AI Sidecar - A browser-rendering sidecar to fetch and process JavaScript-heavy webpages for the fetch_url tool.
• Text-to-Speech / Speech-to-Text - Python voice servers for TomoriBot's voice messages; their venv must be set up once beforehand.

Updating TomoriBot

To update your self-hosted instance to the latest version, stop the bot first (so the backup and any migrations run against a quiet database), then run the backup-first updater:

bun run update

The command runs this sequence, stopping immediately if any step fails:

1. bun run backup - takes a full database backup into /backups/ before touching any code. If the backup fails, the update aborts with your deployment completely unchanged.
2. git pull --rebase --autostash
3. bun install --frozen-lockfile

Then restart TomoriBot with bun run dev or bun run launch

Useful flags:

Flag	Effect
--build	Also runs bun run build after installing dependencies
--docker	Docker Compose path: replaces step 3 with docker compose build + docker compose up -d
--skip-backup	Skips the pre-update backup (not recommended)
--yes	Skips the confirmation prompt before starting

See the full Maintenance Documentation for more details on all host-side scripts.

After Inviting / Setup

Basic Commands

• /config setup - Initial bot setup for your server
• /config - Multiple ways to tweak TomoriBot
• /memory personal add / /memory personal remove - Add / remove your personal memories
• /memory server add / /memory server remove - Add / remove server-wide memories
• /server whitelist / /server user-blacklist - Add / remove permissions from TomoriBot

See the full Command Reference for every slash command.

Chat Interaction

Simply mention the bot in a server or use the configured trigger words to start a conversation:

@TomoriBot yo wassup

Or slide into TomoriBot's DMs and say hi!

Contributing

Contributions to TomoriBot are greatly appreciated! Please review the following resources before opening a pull request:

• Contributing Documentation: Comprehensive step-by-step guides for adding slash commands, tools, event handlers, new AI providers, and locales.
• Contributing Guidelines: Repository rules covering branching, quality gate checks, and the scope of contributions welcomed without prior discussion.

Legal & License

For users of the official hosted TomoriBot instance

• Terms of Service - Rules and guidelines for using the bot
• Privacy Policy - How we handle your data

These documents are also accessible within Discord using /legal terms and /legal privacy commands.

For users self-hosting or using forks

You control your own data and are responsible for your deployment's compliance under the GNU Affero General Public License v3.0.

Contact & Links

Official Website: https://docs.tomoribot.app

Project Link: https://github.com/Bredrumb/TomoriBot

Email: bredrumb@gmail.com

Discord: Official Support Server

Support the Project

If you find TomoriBot helpful and want to support its ongoing development, consider leaving a ⭐ on GitHub or supporting via Ko-fi!