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 atOllamato run on your own hardware withno 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 apersonalassistant, 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.