MiniBot 🤖

Your personal AI assistant for Telegram - self-hosted, auditable, extensible, and intentionally opinionated.

Top features

🤖 Personal assistant, not SaaS: your chats, memory, and scheduled prompts stay in your instance.
🎯 Opinionated by design: Telegram-centric flow, small tool surface, and explicit config over hidden magic.
🏠 Self-hostable: Dockerfile + docker-compose provided for easy local deployment.
🧩 Python extensions: add your own tools, event subscribers, and background services from any importable module — plus channels.
💻 Local console channel for development/testing without Telegram.
💬 Telegram channel with chat/user allowlists, long-polling or webhook modes, and multimodal inputs.
🧠 Provider support via llm-async: openai, openai_responses, openrouter, and more.
🧰 Configurable tools: chat memory, KV notes, HTTP fetch, calculator, datetime, Python execution, Bash, patch-based editing (apply_patch), file storage, grep, speech-to-text, and MCP server bridges.
🔎 RAG (optional): index local documents into SQLite (or Qdrant) and retrieve semantically relevant chunks.
🕸️ Relation graph (optional): store and traverse typed relationships between entities.
⏳ Async task workers: offload long-running jobs to a background queue (SQLite by default, optional RabbitMQ).
⏰ Scheduled prompts (one-shot, fixed-interval, and cron recurrence) persisted in SQLite.
🤝 Multi-agent orchestration with specialist agent definitions and skill packs.
⚙️ minibot configure: interactive terminal wizard to create or update config.toml.
📊 Structured logfmt logs and a focused async test suite.

Make it yours

MiniBot is built to be extended, and most changes need no Python:

Level	What you get	Where
Config	toggle tools, providers, models, limits	`config.toml`
No code	rewrite the system prompt, add skills and prompt packs, add specialist agents	`prompts/`, `skills/`, `agents/*.md`
External tools	connect any MCP server	`[[tools.mcp.servers]]`
Python	your own tools, event subscribers, services, channels	a module + `[extensions].modules`

Start at the least powerful layer that does the job. The most common asks — a new capability — usually stop at an MCP server or a ~10-line extension:

# my_tool.py — add "my_tool" to [extensions].modules
from pydantic import BaseModel, Field
from minibot.app.extensions import ExtensionContext
from minibot.llm.tools.base import ToolContext

class WordCountArgs(BaseModel):
    text: str = Field(description="Text to count words in.")

def register(mb: ExtensionContext) -> None:
    @mb.tool
    async def word_count(args: WordCountArgs, context: ToolContext) -> dict[str, int]:
        """Count the words in a piece of text."""
        return {"words": len(args.text.split())}

See the Extending MiniBot guide for the full customization ladder. The pluggable surfaces — tools, event subscriptions, services, channels — are covered in extensions and events; external tools arrive via MCP.

Quick start

pip install minibot
# add extras as needed, e.g.: pip install "minibot[telegram,stt,rag,rabbitmq]"

minibot configure   # interactive wizard, writes config.toml
minibot              # start the daemon

Extras: telegram (aiogram + Telegram markdown rendering — the daemon needs it only when [channels.telegram] is enabled), rag (pypdf, PDF ingestion for the RAG tool), stt (speech-to-text via faster-whisper), rabbitmq (RabbitMQ task queue backend — not needed with the default sqlite backend), graph (networkx, the optional relation-graph tool). Compact HTML rendering in http_request uses selectolax, which ships with the base install.

MCP needs no extra: the MCP client is a JSON-RPC implementation with no third-party SDK dependency.

No Telegram bot yet? Run minibot console instead of minibot to chat with it in your terminal.

Docker

pipx run minibot configure   # writes config.toml — must run on the host, docker-compose.yml mounts it read-only
# no pipx? `pip install minibot` into a throwaway venv and run `minibot configure` there instead.

docker compose up -d

docker-compose.yml builds and starts the minibot image. The Qdrant and RabbitMQ services are commented out — [tools.rag].backend and [tasks].backend both default to "sqlite" — and are only needed if you switch either to "qdrant" or "rabbitmq".

Demo

Screenshots of Minibot understanding images, summarizing web pages, generating charts, and transcribing voice messages — see the demo gallery.

Metadata

Release files for minibot 0.20.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for minibot 0.20.0
File	Size	Uploaded
minibot-0.20.0.tar.gz	453.4 kB	Sep 22, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for minibot 0.20.0
File	Interpreter	ABI	Platform	Reset
minibot-0.20.0-py3-none-any.whl 561.9 kB Sep 22, 2026	Python 3	none	any	Details

Total release size: 1.0 MB

Release files / minibot-0.20.0.tar.gz

Download URL	minibot-0.20.0.tar.gz
Size	453.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`1ded78622cf5aa3fe305ed592fe3be6bcc57d31eedfdf561263463addb078a33`
BLAKE2b-256 checksum How to use checksums	`22b9af2b21958f7d6e14a1a13b376e3994da3ba9684687d2e8ff644d758243c9`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.13`

Release files / minibot-0.20.0-py3-none-any.whl

Download URL	minibot-0.20.0-py3-none-any.whl
Size	561.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4d04a31670f7e71c5404ff179ce9283ea5b97e447f1879ce5d71d52bbbfbbb94`
BLAKE2b-256 checksum How to use checksums	`cd3d08c29ce8b9a4c55e9cf9c2e8a907c673b5eb1be7da3466a865fab21b7af1`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.13`