TomoriBot

A highly customizable chatbot/waifu for Discord featuring smart agentic AI features such as memory, personas, tool usage, and more!

English | 日本語

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

About the Project

TomoriBot is a free and open-source hobby project inspired by SillyTavern and Discord's discontinued Clyde. It was created to bring both practical AI assistants and custom AI companions into Discord, all with configurable settings and behaviors.

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 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 reminders, analyzing images, binge-watching YouTube, and utilizing your server's emotes/stickers

Each Server's TomoriBot is Unique

50+ slash commands are available for complete customization. TomoriBot's in-server personality, behavior, and avatar can be easily changed as well as exported for others as Personas (akin to shareable AI Character Cards). She also remembers interactions using Memories, which can only be accessed by you and your server (with complete options to delete or block for privacy)

Multilingual and Multi-Provider Support

Different AI providers and models are available (currently Google Gemini, OpenRouter, and NovelAI), ranging from practical coding AI to role-playing AI that would power your TomoriBot's "brain". TomoriBot is also multilingual based on your chosen AI provider/model

...and much MORE!

TomoriBot is currently in Beta, with new features such as Image Generation currently in testing (please report through GitHub issues or the official Discord for any bugs!)

Self-Hosting

This guide will help you set up TomoriBot locally for development or personal use.

Prerequisites

Before running TomoriBot, ensure you have the following installed:

• Node.js v20+ - Required for MCP servers (DuckDuckGo search requires the File API from Node 20+)

  # Check your current version
  node --version
  
  # If below v20, upgrade via:
  # Ubuntu/Debian
  curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
  sudo apt-get install -y nodejs
  
  # macOS (using Homebrew)
  brew install node@20
  
  # Windows (using Chocolatey)
  choco install nodejs-lts
  

• Bun - JavaScript runtime and package manager

  # Windows (PowerShell)
  powershell -c "irm bun.sh/install.ps1 | iex"
  
  # macOS/Linux
  curl -fsSL https://bun.sh/install | bash
  

• PostgreSQL - Database server

  # Windows (using Chocolatey)
  choco install postgresql
  
  # macOS (using Homebrew)
  brew install postgresql
  
  # Linux (Ubuntu/Debian)
  sudo apt-get install postgresql postgresql-contrib
  

  • After installing PostgreSQL, login:

  # Linux
   sudo -u postgres psql
  
   # macOS (Homebrew)
   psql postgres
  
   # Windows
   # Use "SQL Shell (psql)" from Start Menu or:
   psql -U postgres
  

  • Create the required database and user for TomoriBot. Replace your_ variables with your own and take note of them:

  CREATE USER your_username WITH PASSWORD 'your_password' SUPERUSER;
  CREATE DATABASE your_dbname OWNER your_username;
  \q
  

  Note: The database schema (including required extensions like pgcrypto) is automatically initialized when you first run TomoriBot.

• Python 3 (Optional but recommended) - Required for URL Fetching MCP server tool

  # Windows (using Chocolatey)
  choco install python
  
  # macOS (using Homebrew)
  brew install python
  
  # Linux (Ubuntu/Debian) - Usually pre-installed
  sudo apt-get install python3 python3-pip
  

  • Install MCP server packages:

  # Install URL fetcher for web content analysis
  pip install mcp-server-fetch
  
  # Linux users: If you get an "externally-managed-environment" error, use:
  pip install --break-system-packages mcp-server-fetch
  # OR create a virtual environment
  

Installation

1. Clone the repository

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

2. Install dependencies

   bun install
   

Configuration

Create environment file .env and then fill in the required variables:

 # Discord Bot Configuration (Required)
 DISCORD_TOKEN=your_discord_bot_token_here

 # Security (Required)
 CRYPTO_SECRET=your_32_character_crypto_secret_here

 # Database Configuration (Required)
 POSTGRES_HOST=localhost
 POSTGRES_PORT=5432
 POSTGRES_USER=your_username
 POSTGRES_PASSWORD=your_password
 POSTGRES_DB=your_dbname

 # Bot Configuration (Optional)
 DEFAULT_BOTNAME=Tomori
 DEFAULT_BOTNAME_JP=ともり
 BASE_TRIGGER_WORDS=tomori,tomo,トモリ,ともり

Required Variables:

• DISCORD_TOKEN: Your Discord bot authentication token from the Discord Developer Portal
• CRYPTO_SECRET: A 32-character secret key for encrypting API keys stored in the database
• POSTGRES_HOST: PostgreSQL server hostname (default: localhost)
• POSTGRES_PORT: PostgreSQL server port (default: 5432)
• POSTGRES_USER: PostgreSQL database username
• POSTGRES_PASSWORD: PostgreSQL database password
• POSTGRES_DB: PostgreSQL database name

To find all additional optional variables you can adjust, check out the .env.example file in the repository.

Running TomoriBot

Once you've completed the configuration, start the bot:

# Development mode with hot reload
bun run dev

The bot will automatically:

• Initialize the database schema and required extensions
• Load localization files
• Connect to Discord
• Register slash commands

Once you see TomoriBot up and running!, without errors in your logs, the bot is online and ready to use.

Basic Commands

• /config setup - Initial bot setup for your server
• /config - Multiple ways to tweak TomoriBot
• /teach - Add memories for TomoriBot
• /forget - Remove memories from TomoriBot
• /server - Add / Remove permissions from TomoriBot

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!

Updating TomoriBot

Before updating, consider backing up your database (bun run backup-db) and reviewing the release notes.

Manual (non-Docker) update:

# Stop your running bot process first (Ctrl+C / service stop / pm2 stop / etc.)
git pull
bun install

# If you run from dist/ (bun run start), rebuild:
bun run build

Docker Compose update:

git pull
docker compose build
docker compose up -d

Alternative: Docker Compose

If you prefer containerized deployment, you can use Docker Compose instead of manual setup:

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)

# Build TomoriBot's container (first time or after code changes)
docker compose build

# Start TomoriBot and her database (uses docker-compose.yaml)
docker compose up

Note: Docker Compose automatically configures the database connection. The PostgreSQL service runs in development mode (no SSL) and connects to the internal Docker network.

Monitoring with Grafana (Optional)

To monitor your TomoriBot instance with Grafana dashboards:

# Start both TomoriBot and Grafana together
docker compose -f docker-compose.yaml -f docker-compose.monitor.yaml up

This will:

• Launch TomoriBot with PostgreSQL (on ports 15432 for DB)
• Launch Grafana on port 3000 with auto-configured PostgreSQL datasource
• Connect both services on the same Docker network

Access Grafana at http://localhost:3000:

• Username: admin
• Password: Set via GRAFANA_PASSWORD in .env (defaults to admin)

The PostgreSQL datasource is automatically configured and ready to create dashboards for monitoring bot metrics, database queries, and performance.

Roadmap

• Core AI chat functionality
• Memory system implementation
• Slash command structure
• Multi-language Support (Locale system)
• Multiple Provider Support
• TomoriBot Wiki (for local set-up and locale contributions)
• Replace AI-generated placeholder assets
• Image Generation Capabilities
• Video Generation Capabilities
• KoboldCPP integration (local only)
• Voice channel integration
• Web dashboard for configuration
• Create "easy install" file for non-technical users wishing to host their own TomoriBot

See the open issues for a full list of proposed features and known issues.

Contributing

Since TomoriBot is still in Beta, any contributions made are greatly appreciated, especially for localization.

To contribute a new language translation:

1. Create a locale file in src/locales/ named after a Discord locale code (e.g., es-ES.ts for Spanish, fr.ts for French, ko.ts for Korean)

2. Mirror the structure of the gold standard file src/locales/en-US.ts:

   • Copy all keys and nested objects
   • Translate all user-facing text while preserving placeholders like {variable}

3. Add preset translations (optional but recommended) in src/db/seed.sql:

   • Translate the tomori_preset_desc field for each preset
   • Translate the preset_attribute_list, preset_sample_dialogues_in, and preset_sample_dialogues_out arrays
   • Add LLM descriptions by translating the llm_description field (following the existing pattern with ja_description)
   • Set preset_language to your locale code

4. Test your translations:

   # Verify all locale keys match across files
   bun run check-locales
   

5. Submit a pull request with your new locale file(s) and any src/db/seed.sql additions

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. If you're self-hosting TomoriBot, these documents serve as reference templates. You control your own data pipeline and are responsible for your deployment's compliance under the GNU Affero General Public License v3.0.

Contact

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

Email: bredrumb@gmail.com

Discord: Official Support Server