Show HN: AI Secretary – Stop checking your phone "just in case"

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

systemd

systemd

.env.example

.env.example

.gitignore

.gitignore

LICENSE

LICENSE

README.md

README.md

notification_agent.py

notification_agent.py

notification_rules.py

notification_rules.py

notification_state.py

notification_state.py

requirements.txt

requirements.txt

telegram_notification_listener.py

telegram_notification_listener.py

Repository files navigation

Keep Telegram muted without missing what matters.

Telegram AI Secretary is a self-hosted AI notification filter for Telegram. It listens to a Telegram user account with Telethon, filters noisy chats, asks an LLM when context matters, and sends only important alerts to your phone through ntfy.

It is designed for people who want notifications off by default without missing urgent messages, calls, same-day plans, or someone waiting at the door.

Why?

Mobile phones keep us connected, but they have become so noisy that many people cannot keep notifications turned on. Turning them off solves the interruption problem, but creates a different one: checking the phone every few minutes "just in case" someone wrote something important.

That loop is bad for focus and makes the phone more addictive, not less.

Secretaries have long helped busy people stay reachable without personally processing every interruption. They filter irrelevant messages, understand context, and notify immediately when something actually needs attention. LLMs make a lightweight personal version of that possible for everyone.

Telegram AI Secretary is an experiment in that direction: keep the phone quiet by default, but still let important messages break through.

Use Cases

Keep Telegram muted while still receiving urgent DMs.

Get notified when someone asks "are you home?" or "can we meet today?"

Let calls and same-day coordination bypass do-not-disturb.

Ignore group chatter unless you are mentioned.

Send critical ntfy alerts when someone is waiting outside.

Use recent private-chat context so "I organized myself, I will pass by at 13" can be understood as important after a previous "please let me know".

Features

Listens to incoming Telegram messages and call events from a user account.

Drops noisy group messages unless they mention you.

Sends calls and matching fast rules directly to ntfy.

Sends private human messages to Claude with recent conversation context.

Keeps up to 20 messages from the current private conversation segment, where a segment is cut when consecutive messages are more than 24 hours apart.

Treats same-day coordination as notify-worthy, even when it is not an emergency.

Marks immediate physical-presence messages as candidates for critical alerts.

Supports temporary fast rules and do-not-disturb state from the CLI.

Ignores voice/audio messages by default, with optional DND auto-replies.

Requirements

Python 3.10+

A Telegram API ID and hash from https://my.telegram.org/apps

The claude CLI installed and authenticated

An ntfy topic, for example on https://ntfy.sh

Install

git clone https://github.com/mathigatti/telegram-ai-secretary.git cd telegram-ai-secretary python3 -m venv .venv .venv/bin/pip install -r requirements.txt cp .env.example .env

Edit .env with your Telegram API credentials and ntfy topic.

Run the listener once interactively to create the Telethon session:

.venv/bin/python3 telegram_notification_listener.py

Telegram will ask for your phone login code the first time.

Run Manually

.venv/bin/python3 telegram_notification_listener.py

In another terminal you can test the decision agent:

echo '{"sender_name":"Alex","sender_is_bot":false,"is_private":true,"event_type":"message","text":"Are you home? I can stop by today"}' \ | .venv/bin/python3 notification_agent.py --dry-run

systemd

Copy the template and edit the paths/user:

sudo cp systemd/telegram-ai-secretary-listener.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now telegram-ai-secretary-listener.service systemctl status telegram-ai-secretary-listener.service --no-pager

The template assumes the app lives at /opt/telegram-ai-secretary; adjust it if you deploy elsewhere.

Fast Rules

Fast rules avoid model calls for obvious cases. They live in notification-agent/rules.json and can be managed with:

.venv/bin/python3 notification_rules.py list .venv/bin/python3 notification_rules.py dnd status .venv/bin/python3 notification_rules.py dnd on --duration 2h --reason "focus time" .venv/bin/python3 notification_rules.py dnd off .venv/bin/python3 notification_rules.py add --description "Notify on calls" --action notify --call --duration forever --urgency high --notification-text "{sender}: {event_label}" .venv/bin/python3 notification_rules.py add --description "Ignore group chatter for 2h" --action discard --condition-json '{"private": false}' --duration 2h .venv/bin/python3 notification_rules.py remove

Durations can be 30m, 2h, 1d, today, or forever.

Runtime Files

The app creates a local notification-agent/ directory containing:

rules.json: deterministic fast rules and DND state.

preferences.json: natural-language notification preferences.

preferences.events.jsonl: append-only preference/rule history.

decisions.jsonl: append-only decisions and model metadata.

conversations.jsonl: lightweight private-message history used for context.

audio_auto_replies.json: DND audio auto-reply cooldowns.

These files may contain private messages, names, Telegram IDs, and ntfy details. They are ignored by git.

How Decisions Work

The listener receives a Telegram event and builds a trigger.

The agent applies fast rules.

If the trigger is a private human DM and no fast rule decides it, the agent includes recent conversation context in the Claude prompt.

Claude returns JSON with notify, urgency, reason, notification_text, and confidence.

If notify=true, the agent sends the text to ntfy.

flowchart LR A[Telegram user account] --> B[Telethon listener] B --> C[Fast rules] C -->|discard| D[No notification] C -->|notify| E[ntfy push] C -->|needs judgment| F[Claude with recent context] F -->|notify=true| E F -->|notify=false| D

Loading

Urgency maps to ntfy priority:

low -> low

normal -> default

high -> high

critical -> urgent

The actual phone sound is controlled by the ntfy app and your operating system's notification channel settings.

How Is This Different From A Telegram Forwarder?

Telegram AI Secretary is not a forwarding tool. It is an interruption filter. It does not try to copy every message somewhere else; it decides whether a message deserves to interrupt you.

Most Telegram forwarders are optimized for routing messages based on channels, keywords, or regular expressions. This project is optimized for personal attention management: direct messages, context, urgency, same-day coordination, and phone notification priority.

Privacy Notes

This app processes private Telegram messages locally and may send selected message contents to Claude and ntfy. Review the prompt in notification_agent.py and the data files in notification-agent/ before running it on sensitive accounts.

Related Ideas

Telegram AI Secretary sits near a few broader ideas and tools:

Secretary, the human role this tool is borrowing from.

Attention economy, the economic incentive behind many distracting interfaces.

Cognitive warfare, a more extreme framing of competition over perception and attention.

YIHAD CONTRA LAS CORPORACIONES DE LA DISTRACCION and its disciplina page.

Guia cyberciruja para la autodeterminacion digital.

News Feed Eradicator, a browser extension that removes automatic feeds from social networks so they behave more like tools you intentionally open and search.

Next Steps

Extend beyond Telegram.

Add email as another input.

Support multiple LLM providers.

Add a small web UI for reviewing decisions and tuning rules.

Improve critical notification channels for phone sounds that feel closer to a ringtone than a normal push notification.

About

Self-hosted AI notification filter for Telegram that sends only important alerts via ntfy

Topics

notifications

python

productivity

telegram

self-hosted

claude

telethon

ntfy

digital-wellbeing

ai-assistant

llm

notification-filter

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

No releases published

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 100.0%