Matrix BibleBot

A Matrix bot that fetches Bible verses and shares them in chat rooms. Simply send a Bible reference like "John 3:16" as a message and the bot will respond with the verse text.

What it does

Input: John 3:16 esv Output:

For God so loved the world, that he gave his only Son, that whoever believes in him should not perish but have eternal life. - John 3:16 🕊️✝️

The bot supports both KJV (default) and ESV translations, works in encrypted rooms, and can split long passages into multiple messages.

Quick Start

1. Install the bot

   pipx install matrix-biblebot
   

2. Authenticate with Matrix

   biblebot auth login
   

3. Generate and edit config

   biblebot config generate
   

   Then edit ~/.config/matrix-biblebot/config.yaml to add your room IDs.

4. Run the bot

   biblebot
   

5. Invite the bot to your Matrix rooms and start sending Bible references!

Features

• 📖 Bible Translations: KJV (default) and ESV support
• 🔒 End-to-End Encryption: Works in encrypted Matrix rooms
• ✂️ Smart Message Splitting: Long passages split intelligently
• 🚀 Production Ready: Rate limiting, error handling, systemd service
• 🎯 Direct-Only Triggers: Responds only when the entire message is a scripture reference

Installation

Recommended: pipx

# Basic installation
pipx install matrix-biblebot

# With end-to-end encryption support
pipx install 'matrix-biblebot[e2e]'
# Windows PowerShell: pipx install "matrix-biblebot[e2e]"

Alternative: pip

pip install matrix-biblebot
# or with E2EE support
pip install 'matrix-biblebot[e2e]'
# Windows PowerShell: pip install "matrix-biblebot[e2e]"

From Source

git clone https://github.com/jeremiah-k/matrix-biblebot.git
cd matrix-biblebot
pip install '.[e2e]'  # Includes E2EE support

Usage

Supported Reference Formats

The bot understands various Bible reference formats:

Supported Translations

• KJV (King James Version) - Default, no setup required
• ESV (English Standard Version) - Requires free API key from api.esv.org

Book Abbreviations

The bot recognizes many abbreviations: gen (Genesis), exo (Exodus), matt (Matthew), jn (John), 1co (1 Corinthians), rev (Revelation), and many more. See full list.

Reference Detection

The bot responds only when a message is entirely a scripture reference.

Bot Response

When you send a Bible reference, the bot will:

1. Add a ✅ reaction to your message
2. Reply with the verse text formatted like: "Verse text - Reference 🕊️✝️"

Configuration

Basic Setup

1. Authenticate with Matrix

   biblebot auth login
   

2. Generate configuration file

   biblebot config generate
   

3. Edit the config file at ~/.config/matrix-biblebot/config.yaml:

   matrix:
     room_ids:
       - "!your_room_id:your_homeserver_domain"
       - "#room_alias:your_homeserver_domain" # Aliases work too
   

4. Run the bot

   biblebot
   

Advanced Configuration

For detailed configuration options including:

• End-to-end encryption setup
• Message splitting configuration
• API key configuration for ESV
• Poetry formatting options
• Custom file locations

See the Configuration Guide.

Docker

The published image runs as a non-root user on amd64 and arm64 and keeps configuration, credentials, and E2EE state under /data.

make setup
# Edit ~/.config/matrix-biblebot/config.yaml, then:
make auth-login
make run

Use make use-source && make build to build locally instead of pulling the published image. See the Docker guide for Compose, custom runtime paths, and direct Docker commands.

Running as a Service

For production use on Linux, install as a systemd user service:

biblebot service install

This creates a user service that starts automatically. Manage it with:

systemctl --user start biblebot.service     # Start
systemctl --user stop biblebot.service      # Stop
systemctl --user status biblebot.service    # Check status

CLI Commands

# Configuration
biblebot config generate    # Create sample config
biblebot config check       # Validate config

# Authentication
biblebot auth login         # Login to Matrix
biblebot auth logout        # Clear credentials
biblebot auth status        # Show auth status
biblebot auth cross-sign    # Refresh an existing bot cross-signing identity

# Service management
biblebot service install    # Install systemd service

# Running
biblebot                    # Start the bot
biblebot --log-level debug  # Debug mode

Bot self-cross-signing

Cross-signing is never run during login or bot startup. Back up the E2EE store before using the explicit command. The default location is ~/.local/state/matrix-biblebot/e2ee-store. If you have set a non-default state directory, the store lives at $XDG_STATE_HOME/matrix-biblebot/e2ee-store (or, when XDG_STATE_HOME is unset, ~/.local/state/matrix-biblebot/e2ee-store). When BIBLEBOT_HOME is set, everything is under <BIBLEBOT_HOME>/e2ee-store instead. Use biblebot auth status to confirm the resolved path on your install before backing up. An existing BibleBot-managed identity can be refreshed with biblebot auth cross-sign; the Matrix password is prompted for and never saved.

The first run has no local _cross_signing.json sidecar and is refused by default. Only after confirming the account has no Element-managed cross-signing identity, run biblebot auth cross-sign --bootstrap. MindRoom nio cannot import or reconcile an existing server-side identity, so bootstrapping can replace it. Corrupt, unexpected, or multiple sidecars are refused rather than rotated.

The provider upgrade migrates the encrypted store schema from version 2 to 10 when first opened. Back up the complete store first. Recreate existing environments rather than upgrading in place: matrix-nio and mindroom-nio both own the nio import package and must not be co-installed.

Troubleshooting

Common issues:

• "No credentials found" → Run biblebot auth login first
• Bot doesn't respond → Check room IDs in config, ensure bot is invited
• E2EE issues → Install with [e2e]; if your Matrix client withholds keys from unverified devices, verify/cross-sign the bot device

For detailed troubleshooting, see Troubleshooting Guide.

Documentation

• Configuration Guide - Detailed setup, options, and E2EE setup
• Docker Guide - Prebuilt and source container deployment
• Development Guide - Contributing and development setup
• Troubleshooting - Common issues and solutions

Contributing

Contributions welcome! Please see Development Guide for setup instructions, project structure, and the Testing Guide for test conventions.

License

MIT License - see LICENSE file for details.