Starter kit for a Telegram news digest bot

What you get

Left to you, because no check can do it: Create the bot with @BotFather, put the token into .env, start the bot and send /start to it once: only then can it write to you. To post into a channel, add the bot to the channel as an administrator. Choose where it runs: your own computer while it is on, or any small server; the bot uses long polling, so no public address is needed.

Bot

Installed along with them: HTTPX 0.28.1, python-dotenv 1.2.4, tzdata 2026.5, pytest 9.1.1.

For your agent

The plan your agent follows

The agent works one step at a time and does not start a step until the previous one meets its "Done when" lines. The full instructions, with code, are in AGENTS.md.

1. Scaffold · done when:
   • python -m newsbot --help lists the commands and python -m pytest runs.
   • The kit files listed under "Before you start" are still there.
2. Feeds · done when:
   • Tests parse the three fixtures, find the broken one, and return each item once across two runs.
3. Digest text · done when:
   • Unit tests cover escaping, tag stripping, the 4096 limit with a digest of 60 items, and the "and N more" line.
4. Bot commands · done when:
   • Every command has a test through feed_update with the fake session, including a refused change by a non-admin in a group.
5. Schedule and storage · done when:
   • A test computes the next digest time for 09:00 Europe/Berlin on the day of a daylight-saving change and gets 09:00 local time.
6. Verify · done when:
   • Every line under Definition of done is true, and anything that could not be verified is named in PROGRESS.md.

Known traps

What test builds and the official docs showed going wrong with these parts. Each one is in the brief, so the agent reads it before it gets there.

• aiogram 3 is not aiogram 2: executor is gone, Dispatcher() takes no bot, handlers sit on a Router without the _handler suffix, and keyword filters became explicit filters. aiogram migration guide
• A message may hold 1 to 4096 characters after entities are parsed. aiogram does not check that before sending: a 5,000-character text leaves the client and fails at Telegram. measured with aiogram 3.31.0 and feedparser 6.0.14, Oct 12, 2026
• In HTML mode every <, > and & that is not part of a tag must be escaped, and only Telegram's short list of tags is accepted. feedparser hands descriptions over as HTML (<p>, <div>, <img>), which Telegram rejects. Bot API, and measured with aiogram 3.31.0 and feedparser 6.0.14, Oct 12, 2026
• feedparser does not raise on malformed feeds: it sets bozo and stores the error. Code that only catches exceptions never notices a broken feed. feedparser docs
• getUpdates (long polling) does not work while a webhook is set for the bot; delete the webhook before polling. Bot API
• Telegram's limits: about one message a second per chat, 20 a minute per group, about 30 a second in total. Above that the API answers 429 with a wait time. Telegram bot FAQ
• feedparser.parse() treats a str or bytes argument as a file name or URL first and reads it if it exists; only a file-like object such as io.BytesIO(content) is always parsed as the feed itself. feedparser 6.0.14 docstring, and measured with aiogram 3.31.0 and feedparser 6.0.14, Oct 12, 2026
• APScheduler 3's AsyncIOScheduler awaits a job only when the job function is a coroutine function. A lambda that returns a coroutine runs in a thread pool; Python then warns "coroutine ... was never awaited" and nothing is sent. measured with APScheduler 3.11.3, Oct 12, 2026
• There is no module aiogram.html: import aiogram.html fails with ModuleNotFoundError. Use from aiogram import html. Its quote() escapes <, > and & but not ". measured with aiogram 3.31.0 and feedparser 6.0.14, Oct 12, 2026
• In APScheduler 3, jobs added before start() are pending. A second add_job with the same id and replace_existing=True queues a duplicate, and get_job returns the first one until the scheduler starts. measured with APScheduler 3.11.3, Oct 12, 2026
• APScheduler's 4.0 series is a pre-release with a different API (data stores, event brokers); the Stack pins 3.x, which needs none of that. AgentGid rules for APScheduler

What happened when an agent built from it

The recipe was given to a fresh coding agent in a clean sandbox, twice. The agent got only the kit files. It had to build the project and write down everything in the brief that was wrong, missing or unclear.

Result of the last build. A Telegram digest bot with /add, /remove, /list, /time and /digest, per-chat time zones and SQLite; 44 tests pass against a fake Telegram session and fixture feeds, offline, in a fresh clone set up from the README alone. Its findings went back into the recipe, which is now at v0.3. That version has not been built again as a whole.

Checked again on Oct 19, 2026. AgentGid checks every recipe each week, without a model: 6 pinned packages all still exist on their registries; the pip lines resolve together; 14 links in the brief: all open. npm lines are checked pin by pin, not installed.

Not checked by anyone yet

• A live run with a real bot token: Telegram's API was not reachable from the test machine
• Fetching real feeds over the internet
• The summary-model variant, the Russian texts, macOS and Windows

The kit files

Put them in an empty project folder, open your coding agent there and paste the first prompt (Claude Code first asks you to approve the MCP servers in .mcp.json). These are the files for Claude Code with the default answers; the kit builder writes them for Cursor, Codex, Copilot or another agent, and for other choices. Full guide: how to use a kit.

Download all (.zip)

Read AGENTS.md from top to bottom before you do anything else. The kit files it lists are already in this folder.

Then do step 1 of the plan and stop. Report back with:
1. the commands you ran,
2. what each "Done when" check showed (a screenshot or the output),
3. anything in AGENTS.md that turned out to be wrong, missing or out of date.

Do not start step 2 until I reply.

Read AGENTS.md from top to bottom before you do anything else. The kit files it lists are already in this folder.

Then work through the plan in order. After each step, run its "Done when" checks yourself and write one line in PROGRESS.md: the step, what you checked, and the result.
You may install the packages and download the files that AGENTS.md lists without asking. Stop and ask me only for what its "Before you start" section says needs a person.
When a check fails, fix the cause and run it again. If it still fails after two real fixes, stop and tell me what you tried.
Keep a list in PROGRESS.md of anything in AGENTS.md that turned out to be wrong, missing or out of date.
When every line of the Definition of done is true, stop and show me how to run it.

uv venv --seed --python 3.12 .venv && source .venv/bin/activate   # uv fetches Python 3.12 if it is missing; --seed puts pip into the venv, so the pip line below installs there and not into the system Python
# without uv: python3.12 -m venv .venv && source .venv/bin/activate
python --version   # must print 3.12.x
pip install aiogram==3.31.0 feedparser==6.0.14 "apscheduler>=3.11.3,<4" httpx==0.28.1 python-dotenv==1.2.4 tzdata==2026.5 pytest==9.1.1

Other versions of this kit

Other versions were not test-built as a whole: the kit says which parts differ from the tested one.

Ask for this kit from your agent

Agents connected to the AgentGid MCP server get the same kit without this page: list_recipes(), then plan_project({"recipe": "news-bot", "answers": {"agent": "cursor"}, "files": true}). Every brief also tells the agent to ask AgentGid before it adds a part that is not listed.

Recipe news-bot v0.3. Data snapshot Oct 12, 2026: versions, licenses and prices change, so check the linked pages before you ship.

Comments

Other kits