# How HN: Billy – a self-hosted AI assistant that lives in your Telegram > Source: > Published: 2026-07-04 00:02:23+00:00 *Your own AI assistant, right in your Telegram — runs local (Ollama) or cloud.* Billy is a personal AI assistant you talk to through Telegram. He runs on your own machine, answers to only you, and orchestrates a set of AI models (Anthropic Claude as the "brain") to actually get things done — read and write email, manage a lightweight CRM, research the web, generate documents and images, and learn reusable "skills" over time. Billy is built around one idea: **an orchestrator that dispatches specialist sub-agents and loads tools on demand**, so each turn stays cheap while every capability stays reachable. **Chat** on Telegram with memory that persists across sessions.**Local or cloud models**: runs on cloud AI by default (Anthropic Claude), or point it at[Ollama](https://ollama.com)to run on your own hardware with**no API keys**— or mix both (cloud brain, local for cheap background jobs).** Email**(optional): send and receive via Resend, with staged drafts you approve before anything goes out.** CRM**: contacts, pipeline, tasks, and interactions as simple spreadsheets, one folder per project. Ships with a demo project you can copy or delete.**Documents & media**: Word, Excel, PDF, diagrams, image generation and editing, video editing, text-to-speech.** Research**: web search with citations and fact-checking.** Skills**: markdown playbooks Billy applies and learns from over time.** Safety guards**: Billy can't edit his own source or spontaneously send email on an unprompted turn. Billy is a **dispatch-first orchestrator built on LangGraph**. Instead of cramming every capability into one giant prompt, he: - Runs a **reason → act loop**: a cheap model first decides what the turn needs, then a stronger model does the work. **Loads tools on demand.** A lean core is always available; ~80 specialist tools load only when a turn calls for them — so each model call stays fast and cheap instead of carrying the whole toolbox every time.**Dispatches to specialist sub-agents**(writer, researcher, social, image, triage) that own their own toolkits and run concurrently.** Routes across models by job**— a fast/cheap model for triage and compression, a strong model for deep reasoning — all configured in`config/models.yaml` .**Learns skills**: reusable markdown playbooks it writes and applies over time. Two safety guards are enforced by tests in the commit gate: Billy **cannot edit his own source code**, and he **cannot send email on an unprompted turn**. **Stack:** Python 3.12, LangGraph, and a provider-agnostic model layer. Anthropic Claude is the default brain, and any OpenAI-compatible endpoint — including **local models via Ollama** — plugs in through `config/models.yaml` . See `config/models.ollama.example.yaml` to go local.**Copy** and fill in your keys. At minimum you need an Anthropic API key and a Telegram bot token + your chat ID.`.env.example` to`.env` **Edit** with your name (and business, if any).`config/owner.yaml` **Install dependencies:**`pip install -r requirements.txt` .**Start Billy** and message your bot. Full step-by-step instructions — including where every key comes from and which features are optional — are in ** SETUP_GUIDE.md**. **Python 3.12+.****API keys** for the cloud models it routes to (Anthropic is required; a few cheaper models are used for background work — see the setup guide). These are pay-as-you-go: every message spends a small amount of real money, which you control through each provider's dashboard.**Single user.** Billy answers to exactly one Telegram account (the chat ID you configure). That one-user boundary is his security model — he is a*personal*assistant, not a multi-tenant service.**Platform.** Billy was built and run on Windows (there are helper scripts for running it as a Windows service). It is plain Python and the core runs anywhere Python does, but the service/installer helpers are Windows-specific.- Some features need free helper programs (ffmpeg, Tesseract, Graphviz). They're optional; see `docs/bootstrap-native-deps.md` . MIT — see [LICENSE](/surfgolfski-dev/billy/blob/main/LICENSE). Third-party materials are acknowledged in [THIRD_PARTY_NOTICES.md](/surfgolfski-dev/billy/blob/main/THIRD_PARTY_NOTICES.md). Billy is built and maintained by ** Tumbleweed Consulting** — practical AI and automation for small businesses.