butler
A family assistant in a Telegram group: expenses, budgets, to-dos, birthdays and a house wiki.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/mavrin-xv--butler)HTML
<a href="/listings/mavrin-xv--butler"><img src="/api/listings/mavrin-xv--butler/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
You need a Linux machine with systemd (Ubuntu or Debian on a small VPS is the tested path), a Telegram bot token from [@BotFather](https://t.me/BotFather) and a ChatGPT account.
1. `cp config.example.yaml config.yaml` and fill in names, timezone, currency, birthdays. 2. Get each person's numeric Telegram id from [@userinfobot](https://t.me/userinfobot) and the group id ([docs/telegram.md](docs/telegram.md)). 3. `./install.sh`. It installs Hermes and qmd if missing, creates the profile, the database and the wiki, asks for the bot token, prints a ChatGPT sign-in link, starts the service and adds the reminders. 4. Add the bot to your family group. Every person opens a private chat with the bot once and presses **Start**, otherwise private reminders cannot reach them.
Re-running `install.sh` is safe. It never overwrites the database or wiki pages.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 134 lines
- 
- <div align="center">
- # butler
- **A family assistant that lives in your Telegram group and runs on the ChatGPT plan you already pay for.**
- Expenses, budgets, to-dos, birthdays, recipes and the house wiki. One chat, one bot, no app to install.
- [](LICENSE)
- 
- 
- 
- </div>
- 
- ```bash
- git clone https://github.com/mavrin-xv/butler && cd butler
- cp config.example.yaml config.yaml && nano config.yaml
- ./install.sh
- ```
- ---
- ## What it solves
- You write to the bot the way you would write to a person. It answers in the same chat.
- ```
- Sam: coffee 4.20 and croissants 6
- butler: Logged: eating_out, 10.20 EUR (Sam).
- Alex: how much did we spend on food this month?
- butler: Groceries 412 EUR of 500, eating out 138 of 150.
- Eating out is at 92% with 9 days left.
- Sam: remind Alex on Friday at 6pm to call the plumber
- butler: Done. Friday 18:00, private message to Alex.
- ```
- More in [examples/conversation.md](examples/conversation.md).
- | Area | What you get |
- |---|---|
- | Money | Expenses and income in any currency, converted to your base currency at the day's rate. Monthly limits per category, a report on the 1st. |
- | Tasks | Shared and personal to-dos with due dates. "What's on this week?" works. |
- | Reminders | One-off and recurring, to the group or to one person. Birthdays from config with a heads-up a week before. |
- | Memory | A markdown wiki: house rules, the boiler model, who the plumber is, the recipes that worked. Searchable. |
- | Two people, two styles | One person gets one-line confirmations, the other gets headings and bullets. Set per member. |
- ## Why this one
- Most household bots are a web app with a database you have to host, or a wrapper that bills you per token. This is neither.
- **It runs on your ChatGPT plan.** The engine, [Hermes Agent](https://github.com/NousResearch/hermes-agent), can sign in with a ChatGPT account the same way the Codex CLI does. For two people writing a few dozen messages a day, Plus at $20 a month has stayed inside its normal limits in our use. No API key, no per-message bill. If you would rather not use that, there are free tiers that work too: see [docs/models.md](docs/models.md).
- **Everything else is free and on your own box.** SQLite for numbers, plain markdown for the wiki, a $5 VPS or an old laptop at home. Your family's data never goes to a third-party service except the model call itself.
- **A real family used it before it was published.** The skill file carries rules that came from real mistakes: reminders that fired an hour late because of a UTC offset, a reminder to one person that silently failed because they had never pressed Start, a Telegram connection that paused while the process looked healthy. Each of those is now a rule or a script.
- ## How it works
- ```
- Telegram group ──► Hermes gateway (systemd) ──► model (ChatGPT plan / free tier)
- │
- ├── SOUL.md who the butler is, tone, boundaries
- ├── skills/family-ops how to log, report, remind, file
- ├── family.db SQLite: tasks, expenses, income, budgets
- ├── wiki/ + qmd markdown memory with local search
- └── cron birthdays and recurring reminders
- watchdog.sh (every 5 min) restarts the gateway if Telegram goes quiet
- ```
- All the household details sit in one file, `config.yaml`. `scripts/render.py` turns it into the persona, the skill, the database schema and the reminder jobs, so nothing personal is hard-coded anywhere. Details: [docs/how-it-works.md](docs/how-it-works.md).
- ## Install
- You need a Linux machine with systemd (Ubuntu or Debian on a small VPS is the tested path), a Telegram bot token from [@BotFather](https://t.me/BotFather) and a ChatGPT account.
- 1. `cp config.example.yaml config.yaml` and fill in names, timezone, currency, birthdays.
- 2. Get each person's numeric Telegram id from [@userinfobot](https://t.me/userinfobot) and the group id ([docs/telegram.md](docs/telegram.md)).
- 3. `./install.sh`. It installs Hermes and qmd if missing, creates the profile, the database and the wiki, asks for the bot token, prints a ChatGPT sign-in link, starts the service and adds the reminders.
- 4. Add the bot to your family group. Every person opens a private chat with the bot once and presses **Start**, otherwise private reminders cannot reach them.
- Re-running `install.sh` is safe. It never overwrites the database or wiki pages.
- ## Configure
- | You want to | Do this |
- |---|---|
- | Change the name or tone | `butler.name`, `butler.tone` in config, re-run `install.sh` |
- | Add a birthday or a weekly reminder | add it to `birthdays` / `reminders`, then `python3 scripts/render.py && bash build/cron-jobs.sh` |
- | Use a free model instead of ChatGPT | [docs/models.md](docs/models.md) |
- | Change categories | `expense_categories`, re-render, see the migration note in [docs/how-it-works.md](docs/how-it-works.md) |
- | Add a third person | add a member, re-run `install.sh` |
- Reminders in detail: [docs/reminders.md](docs/reminders.md).
- ## Honest limits
- - The ChatGPT sign-in path uses your subscription's Codex limits (they reset every few hours and weekly). A family will not hit them in normal use; a heavy coding week on the same account might. Whether OpenAI's terms allow third-party agents on that sign-in is your call to check. If that matters to you, use a free tier or an API key.
- - The installer was written against Hermes Agent v0.14 and tested piece by piece, not yet end to end on a fresh server. Open an issue if a step fails.
- - It is a family tool. Access is limited to the Telegram ids you list, and it does not try to be multi-tenant.
- - Exchange rates come from free public sources (ECB via Frankfurter, or the National Bank of Ukraine). Good for a household budget, not for accounting.
- ## Repository
- ```
- config.example.yaml every personal setting, copy to config.yaml
- install.sh one-shot installer, safe to re-run
- scripts/render.py config + templates -> build/
- scripts/watchdog.sh restarts a paused gateway, optional alert
- scripts/scrub-check.py checks a tree for tokens, ids and names before you share it
- templates/ SOUL.md, the family-ops skill, schema.sql, wiki schema
- docs/ models, telegram, reminders, how it works
- examples/ a sample conversation
- ```
- ## Contributing
- Bug reports with the failing command and Hermes version help most. See [CONTRIBUTING.md](CONTRIBUTING.md). Agents working on this repo: start with [AGENTS.md](AGENTS.md).
- <!-- author:start -->
- ## Author
- Built and maintained by [Artem Mavrin](https://github.com/mavrin-xv). This repo is one of a set of agent skill packs for marketing and operations work. Each one installs on its own; the full list is in [agent-skill-packs](https://github.com/mavrin-xv/agent-skill-packs). If a pack saved you an afternoon, a star helps other people find it.
- <!-- author:end -->
- ## License
- MIT. Hermes Agent is MIT and maintained by Nous Research; this project is not affiliated with Nous Research or OpenAI.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.