Herald

Lightweight, self-hosted AI assistant bot for Telegram.

Features

• Provider fallback — Claude CLI as primary, any OpenAI-compatible API as backup
• Conversation history — per-chat message history stored in bbolt (embedded, pure Go)
• Long-term memory — remembers facts and preferences across conversations
• User whitelist — only responds to authorized Telegram user IDs
• CLI mode — test locally with ./herald ask "question" without Telegram
• Telegram commands — /clear resets context, /model switches providers, /status shows bot info
• Image support — understands photos sent in Telegram chats
• Image generation — ask Herald to draw something; requires image_provider in config.json (see docs/features.md)
• PDF support — reads text-based PDFs sent in Telegram chats
• Single binary — no CGO, no Docker, no external dependencies at runtime

Quick Start

Build:

CGO_ENABLED=0 go build -o herald ./cmd/herald

Configure:

• Copy config.json.example to config.json and edit to taste
• Copy .env.example to .env and fill in your secrets

Run:

./herald

Configuration

Herald uses config.json for structure and environment variables (via .env) for secrets. The config file references env var names; the binary reads them at startup.

See docs/configuration.md for the full reference.

Deployment

Designed for single-node deployment as a systemd service. See docs/deployment.md for setup instructions.

Documentation

Document	Contents
docs/configuration.md	Config file reference, providers, system prompt
docs/deployment.md	User whitelist, systemd, credential management
docs/features.md	Memory, images, responses, personality, commands
docs/logging.md	Structured logging reference (slog levels, fields)
AGENTS.md	Architecture, conventions, development guide