How HN: Billy – a self-hosted AI assistant that lives in your Telegram

Notifications You must be signed in to change notification settings

Fork 0

Star 0

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

3 Commits

3 Commits

assets

assets

browser_extension

browser_extension

config

config

docs

docs

projects/acme_co

projects/acme_co

scripts

scripts

skills

skills

src

src

tests

tests

.env.example

.env.example

.gitattributes

.gitattributes

.gitignore

.gitignore

.pre-commit-config.yaml

.pre-commit-config.yaml

.secrets.baseline

.secrets.baseline

CONVENTIONS.md

CONVENTIONS.md

LICENSE

LICENSE

README.md

README.md

SETUP_GUIDE.md

SETUP_GUIDE.md

THIRD_PARTY_NOTICES.md

THIRD_PARTY_NOTICES.md

claude.md

claude.md

conftest.py

conftest.py

install_service.bat

install_service.bat

pyproject.toml

pyproject.toml

pytest.ini

pytest.ini

requirements-dev.txt

requirements-dev.txt

requirements.txt

requirements.txt

seed_memory.py

seed_memory.py

uninstall_service.bat

uninstall_service.bat

vulture_whitelist.py

vulture_whitelist.py

Repository files navigation

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.

What Billy can do

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 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.

How it works

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.

Quick start

Copy .env.example to .env and fill in your keys. At minimum you need an Anthropic API key and a Telegram bot token + your chat ID.

Edit config/owner.yaml with your name (and business, if any).

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.

Requirements & good-to-knows

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.

License

MIT — see LICENSE. Third-party materials are acknowledged in THIRD_PARTY_NOTICES.md.

Built by

Billy is built and maintained by Tumbleweed Consulting — practical AI and automation for small businesses.

About

A self-hosted personal AI assistant in your Telegram — runs on local models (Ollama) or cloud. Email, CRM, research, docs, and self-learned skills.

Topics

python

automation

telegram-bot

self-hosted

personal-assistant

claude

ai-agent

llm

anthropic

local-llm

ollama

langgraph

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks

Report repository

Releases 1

Billy 1.0 — your own AI assistant on Telegram

Latest

Jul 1, 2026

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Python 99.2%

Other 0.8%