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.
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.
-
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".
-
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.
-
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
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.
.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
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 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 <rule_id>
Durations can be 30m
, 2h
, 1d
, today
, or forever
.
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.
- 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
, andconfidence
. - 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
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.
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.
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.
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 DISTRACCIONand itsdisciplinapage.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.
- 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.