drumsergio/superchangedetection repository overview

⁠SuperChangeDetection

SuperChangeDetection is a Telegram bot for a self-hosted changedetection.io⁠ instance. Say in the chat what you want watched, in your own words, and the bot reads the page, picks the part that matters, creates the watch and shows you what it sees. From then on changedetection tells the chat directly when the page changes; the bot only comes back when you mention it or reply to it, for example to say a watch fires too often or missed something.

⁠Features

• Create a watch from one chat message: the page's HTML is read and a CSS or XPath filter is chosen for you
• Fix a noisy or blind watch by talking to it: ignore lines, require a trigger text, keep only some lines, change the interval
• In a group the bot speaks only when mentioned or replied to; a delete needs a yes from whoever asked; a slow first check is followed up when it lands
• Every action is validated against an allow-list before it reaches changedetection; notifications are set by the app, never by the AI
• After each create or change the bot shows the text the watch sees now, so a wrong selector is visible at once
• Change notifications go from changedetection straight to the chat, in your language: what changed and a link to see it, with a reply hint to adjust the watch
• Voice notes are always answered when a transcription provider is set, in the group too
• A plugin can carry out proposals, so the bot can change how it works when someone asks; /presentacion tells the chat what it can do here
• English base with a Spanish translation; every string lives in a locale file
• AI provider of your choice: any OpenAI-compatible endpoint, Anthropic, or a plugin file
• The AI reads the shared assistant principles first, in English or Spanish (superchangedetection/principles/): twelve rules on whom it answers, buttons, offers, privacy and honest results. The app's own rules follow them and only add what is specific to watching pages. The files are copied unchanged from the shared text, and a test pins their hashes
• The instance is the source of truth: the bot keeps no copy of the watches

⁠Quick start

mkdir -p data && cp docs/settings.example.yaml data/settings.yaml   # edit it: changedetection URL, locale, chat
export CD_API_KEY=... TELEGRAM_BOT_TOKEN=... SCD_DATA=data
uvx --from superchangedetection scd check

scd check prints the instance version and the watch count when the connection works; scd run is the bot. The Docker image, the settings and the bot setup are in Getting started⁠.

⁠Documentation

• Getting started⁠: prerequisites, Docker, settings, the Telegram side
• Configuration⁠: every setting and its default
• Usage⁠: what to say to the bot, the command line
• How it works⁠: the action block, filters, notifications, what the AI sees

⁠License

GPL-3.0-or-later⁠