Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mavrin-xv--butler/badge.svg)](/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

i

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
  1. ![butler](assets/banner.png)
  2. <div align="center">
  3. # butler
  4. **A family assistant that lives in your Telegram group and runs on the ChatGPT plan you already pay for.**
  5. Expenses, budgets, to-dos, birthdays, recipes and the house wiki. One chat, one bot, no app to install.
  6. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  7. ![Runs on](https://img.shields.io/badge/runs%20on-Hermes%20Agent-black)
  8. ![Model](https://img.shields.io/badge/model-ChatGPT%20plan%20%7C%20free%20tiers-green)
  9. ![Cost](https://img.shields.io/badge/extra%20cost-%240%20%2B%20a%20%245%20VPS-lightgrey)
  10. </div>
  11. ![Example output](assets/example.png)
  12. ```bash
  13. git clone https://github.com/mavrin-xv/butler && cd butler
  14. cp config.example.yaml config.yaml && nano config.yaml
  15. ./install.sh
  16. ```
  17. ---
  18. ## What it solves
  19. You write to the bot the way you would write to a person. It answers in the same chat.
  20. ```
  21. Sam: coffee 4.20 and croissants 6
  22. butler: Logged: eating_out, 10.20 EUR (Sam).
  23. Alex: how much did we spend on food this month?
  24. butler: Groceries 412 EUR of 500, eating out 138 of 150.
  25. Eating out is at 92% with 9 days left.
  26. Sam: remind Alex on Friday at 6pm to call the plumber
  27. butler: Done. Friday 18:00, private message to Alex.
  28. ```
  29. More in [examples/conversation.md](examples/conversation.md).
  30. | Area | What you get |
  31. |---|---|
  32. | 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. |
  33. | Tasks | Shared and personal to-dos with due dates. "What's on this week?" works. |
  34. | Reminders | One-off and recurring, to the group or to one person. Birthdays from config with a heads-up a week before. |
  35. | Memory | A markdown wiki: house rules, the boiler model, who the plumber is, the recipes that worked. Searchable. |
  36. | Two people, two styles | One person gets one-line confirmations, the other gets headings and bullets. Set per member. |
  37. ## Why this one
  38. 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.
  39. **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).
  40. **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.
  41. **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.
  42. ## How it works
  43. ```
  44. Telegram group ──► Hermes gateway (systemd) ──► model (ChatGPT plan / free tier)
  45. │
  46. ├── SOUL.md who the butler is, tone, boundaries
  47. ├── skills/family-ops how to log, report, remind, file
  48. ├── family.db SQLite: tasks, expenses, income, budgets
  49. ├── wiki/ + qmd markdown memory with local search
  50. └── cron birthdays and recurring reminders
  51. watchdog.sh (every 5 min) restarts the gateway if Telegram goes quiet
  52. ```
  53. 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).
  54. ## Install
  55. 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.
  56. 1. `cp config.example.yaml config.yaml` and fill in names, timezone, currency, birthdays.
  57. 2. Get each person's numeric Telegram id from [@userinfobot](https://t.me/userinfobot) and the group id ([docs/telegram.md](docs/telegram.md)).
  58. 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.
  59. 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.
  60. Re-running `install.sh` is safe. It never overwrites the database or wiki pages.
  61. ## Configure
  62. | You want to | Do this |
  63. |---|---|
  64. | Change the name or tone | `butler.name`, `butler.tone` in config, re-run `install.sh` |
  65. | Add a birthday or a weekly reminder | add it to `birthdays` / `reminders`, then `python3 scripts/render.py && bash build/cron-jobs.sh` |
  66. | Use a free model instead of ChatGPT | [docs/models.md](docs/models.md) |
  67. | Change categories | `expense_categories`, re-render, see the migration note in [docs/how-it-works.md](docs/how-it-works.md) |
  68. | Add a third person | add a member, re-run `install.sh` |
  69. Reminders in detail: [docs/reminders.md](docs/reminders.md).
  70. ## Honest limits
  71. - 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.
  72. - 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.
  73. - It is a family tool. Access is limited to the Telegram ids you list, and it does not try to be multi-tenant.
  74. - Exchange rates come from free public sources (ECB via Frankfurter, or the National Bank of Ukraine). Good for a household budget, not for accounting.
  75. ## Repository
  76. ```
  77. config.example.yaml every personal setting, copy to config.yaml
  78. install.sh one-shot installer, safe to re-run
  79. scripts/render.py config + templates -> build/
  80. scripts/watchdog.sh restarts a paused gateway, optional alert
  81. scripts/scrub-check.py checks a tree for tokens, ids and names before you share it
  82. templates/ SOUL.md, the family-ops skill, schema.sql, wiki schema
  83. docs/ models, telegram, reminders, how it works
  84. examples/ a sample conversation
  85. ```
  86. ## Contributing
  87. 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).
  88. <!-- author:start -->
  89. ## Author
  90. 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.
  91. <!-- author:end -->
  92. ## License
  93. 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 in

Free to use. If it’s helped, pass it on.