# Minibot

> Minibot is an open-source, self-hosted AI assistant for Telegram, built in Python.
> It provides persistent memory, tools, skills, scheduled automations, MCP integration,
> and multi-agent orchestration. Telegram-first, SQLite-first, async-first, auditable.

Minibot is a lightweight personal AI assistant you run on your own infrastructure. It is
built for people who want reliable automation and chat assistance without a giant platform
footprint. Your chats, memory, and scheduled prompts stay in your instance (SQLite files),
not a third-party service.

## Getting started

- Install: `pip install minibot` (extras: `telegram`, `rag`, `stt`, `rabbitmq`, `graph`, `codex`,
  `vault`, `http`).
- Configure: `minibot configure` writes `config.toml`.
- Providers: see [Providers](https://sonic182.github.io/minibot/providers.html) for OpenAI, Anthropic,
  Google, OpenRouter, ChatGPT Codex, and compatible endpoints.
- Run: `minibot` starts the daemon; `minibot console` runs a local terminal channel.
- Docker: `docker compose up -d` (Qdrant and RabbitMQ are commented out; `[tools.rag]` and
  `[tasks]` both default to SQLite).

## Configuration

`config.toml` (selected by `MINIBOT_CONFIG`, or an explicit `--config` where accepted) covers
runtime, channels, `[llm]` and `[providers.<name>]`, `[orchestration]`, `[memory]`, `[tasks]`,
`[scheduler.prompts]`, `[tools.*]`, `[logging]`, `[extensions]`, and the optional `[vault]` and
`[http]` servers. String values expand `${ENV_VAR}` (single pass, unset fails, `$$` escapes) and,
once the vault is unlocked, `${secret:NAME}`. `config.example.toml` is the reference;
`config.yolo.toml` is a full-capability profile.

## CLI

`minibot` starts the daemon, `minibot console` runs the local terminal channel, and
`minibot configure` is the interactive setup wizard. `minibot vault init|edit|list` manages the
encrypted credential store, and `minibot codex login` signs in to the ChatGPT Codex provider.

## Extending Minibot

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

- Level 0 — config: toggle tools, providers, models, limits in `config.toml`.
- Level 1 — content: prompt packs (`prompts/`), skills (`skills/`), agent definitions (`agents/*.md`).
- Level 2 — external tools: any MCP server via `[[tools.mcp.servers]]`.
- Level 3 — Python extensions: `register(mb)` modules enabled via `[extensions].modules`.

A Python extension can contribute tools (`@mb.tool`), subscribe to events (`@mb.on`),
register services (`mb.add_service`), serve web pages (`mb.add_route`, or `mb.add_page` for one
with a menu entry and Lucide icon), or implement a channel. The tool name comes from the
function name, the description from its docstring, and the schema from its first argument's
pydantic model.

## Events

The in-process asyncio event bus publishes `MessageEvent`, `TurnStartedEvent`,
`TurnCompletedEvent`, `TurnFailedEvent`, `ToolCallEvent`, `OutboundEvent`,
`OutboundFileEvent`, and `OutboundFormatRepairEvent`. Extensions subscribe with `@mb.on`.
Handlers are async and lossy: slow handlers drop events rather than blocking the pipeline.

## Agent skills

A skill is a directory holding a `SKILL.md` file: flat `key: value` frontmatter (`name`,
`description`, `compatibility`) plus Markdown instructions, following the agentskills.io format.
Only names and descriptions reach the prompt; `activate_skill` loads the body on demand.
Discovery runs project (`./.minibot/skills`, `./.agents/skills`, or `tools.skills.paths`),
then user (the same names under `$HOME`), then native — skills bundled in the package, toggled
with `native` / `native_disabled`. Higher priority shadows lower, which is how a bundled skill
is overridden. `tools.skills.write_path` (default `~/.minibot/skills`) is where the agent writes
new skills and is the top-priority discovery path; files are re-read on an mtime/size
fingerprint, so no restart. `tools.skills.install = true` adds `install_skill`, a Python
`npx skills add` that previews and installs skills from GitHub or archive URLs.

## Multi-agent orchestration

Specialist agents are Markdown files in `./agents` with YAML frontmatter (name, description,
model provider, temperature, `tools_allow`/`tools_deny`, `mcp_servers`). The main agent
delegates with `spawn_task`, which is asynchronous: it returns a `task_id`, the turn ends, and the
specialist's answer arrives later as its own message. A call can override `model_provider`,
`model` and `reasoning_effort` for that one task, limited to providers with credentials.
`fetch_agent_info` returns an agent's definition and defaults plus those providers. Delegation
needs `[tasks]`, which is on by default. Tool ownership is controlled by
`[orchestration].tool_ownership_mode` (`shared`, `exclusive`, `exclusive_mcp`).

## Agent tools

Tools are LLM-callable functions assembled at startup: chat history, KV memory, calculator,
datetime, wait, HTTP client, Python execution, Bash, patch editing (`apply_patch`), file
storage, grep, audio transcription, scheduler, delegation, skills, async tasks, MCP bridges,
and RAG. Each is enabled via its `[tools.*]` section (or `[tasks]`, `[scheduler.prompts]`).

## MCP integration

`[tools.mcp]` + `[[tools.mcp.servers]]` connect stdio or HTTP MCP servers. Remote tools are
exposed as `mcp_<server>__<remote_tool>`, with per-server `enabled_tools`/`disabled_tools`
allowlists and a configurable `name_prefix`.

## Scheduling

`[scheduler.prompts]` persists one-shot, fixed-interval, and cron prompts in SQLite. Schedule
by chatting naturally; recurrence is floored by `min_recurrence_interval_seconds`.

## RAG

`[tools.rag]` indexes text documents into a local SQLite vector store by default and retrieves
semantically relevant chunks (`search_limit`, `max_result_tokens`), with optional cross-encoder
reranking. Set `backend = "qdrant"` to use a Qdrant instance instead.

## Async tasks

`[tasks]` queues long-running work to a background worker and exposes `spawn_task`, `get_task`,
`list_tasks`, and `cancel_task`. `backend = "sqlite"` (default) needs no broker; `"rabbitmq"`
requires the `rabbitmq` extra. Worker limits and retention live under `[tasks]` and
`[tasks.sqlite]`.

## Prompt packs

The system prompt is composed from a base file (`prompts/main_agent_system.md`), policy
fragments (`prompts/policies/*.md`), a specialist roster, optional skill catalog, runtime
capability status, a channel fragment (`prompts/channels/<channel>.md`), and environment
context. Configure the root with `llm.prompts_dir`.

## Web UI

`[http]` (the `http` extra) runs an authenticated web UI on the daemon's event loop: a status
dashboard at `/`, a browser chat at `/chat` (the `web:1` session, with image and audio uploads, and a stop button in place of send while a reply runs),
conversation history at `/history`, and review pages from extensions (`/memory`, `/scheduled`,
`/graph`, `/mcp`, `/tasks`, which also cancels a running task). History, memory and scheduled pages have search, with SQLite FTS5 over message
text, and load more as you scroll. Credentials are a bearer token or HTTP Basic, and are
mandatory unless bound to loopback.

## Relation graph

The optional `graph_*` tools (the `minibot.extensions.tools.graph` extension plus the `graph`
extra) store typed, owner-scoped relationships between entities in SQLite. Use it for
connections; keep single-entity facts in the `memory_*` tools.

## Audio transcription

`[tools.audio_transcription]` (the `stt` extra) transcribes Telegram voice/audio and uploaded
files with faster-whisper. Short incoming messages are transcribed automatically by default.

## Architecture

MiniBot is a lightweight hexagonal app: `core` (domain contracts), `app` (orchestration),
`adapters` (infrastructure), `llm` (provider/tool wiring), plus optional `rag` and `extensions`.
Dependency direction points inward, and both the daemon and console entrypoints publish to an
in-process asyncio event bus.

## Credential vault

`[vault]` (the `vault` extra) keeps secrets encrypted at rest in `secrets.vault.yml`
(AES-256-GCM, scrypt-derived key) and out of the LLM's reach. Reference a secret from config with
`${secret:NAME}`; each secret resolves only at the destination named in config, and the model's
only vault capability is `list_secrets` (names, never values). Write secrets with
`minibot vault edit`.

## Security

Minibot exposes a minimal tool surface by default. `python_execute` and `bash` support
sandbox modes (`none`, `basic`, `rlimit`, `cgroup`, `jail`); `apply_patch` and `file_storage`
are restricted to the workspace/managed root unless explicitly widened.

## Links

- [Documentation](https://sonic182.github.io/minibot/)
- [GitHub](https://github.com/sonic182/minibot)
- [PyPI](https://pypi.org/project/minibot/)