telegram-checklist

hermes-agent-telegram-checklist

English · 简体中文

Native Telegram checklists (To-Do lists) for Hermes Agent - create, read, append and toggle real interactive checklist messages in chats and forum topics through a Telethon user session.

What it is

A single-file Python CLI that manages native Telegram To-Do lists - the real interactive objects with tappable checkboxes and a progress counter, not markdown bullets. An agent (or you, from a shell) can:

• create a checklist in Saved Messages, an allowlisted group, or a specific forum topic
• get it back as structured JSON (task ids, done flags, sharing flags)
• append tasks and toggle tasks done / not done
• rebuild a list through a documented roll-over workflow
• validate an agent-researched plan (plan.json) offline before anything is written

It ships as a skill for Hermes Agent by Nous Research, with a SKILL.md that drives the agent, but the script has no framework dependencies: one file, stdlib + Telethon, strict JSON in/out - any agent harness or plain shell can use it.

Why it exists: the Bot API can't do this

The Telegram Bot API does have sendChecklist and editMessageChecklist, but they work only on behalf of a connected business account - that is, inside a Telegram Business account's private chats with its customers. A regular bot cannot post a checklist into a group or a forum topic at all. The only way to create a native To-Do list in an arbitrary chat or topic is MTProto under a user session, which is exactly what this skill does via Telethon. Note the server-side rule: creating a checklist requires Telegram Premium on the acting account; reading and completing do not.

Features

• create - direct (--title / --task ...) or from a validated plan.json (--from-plan)
• get - read any checklist message as JSON: tasks with ids, done state, sharing flags
• append - add tasks to an existing list (with server-cap and id-overflow guards)
• toggle - mark tasks done / not done in one call (--done 2 --undone 1)
• list-topics - enumerate forum topics so the agent can pick the right thread (only the allowed ones when the chat is allowlisted per-topic)
• plan - fully offline validation of an agent-researched plan: allowlisted target, evidence links required inside task texts, duplicate detection, Telegram limits
• roll-over workflow for "rebuild the list" requests (documented in SKILL.md)
• on-demand CLI only: no daemon, no background listener, no message scraping
• every write is re-read from the server and reported under verified - the output tells you what actually happened, not what was intended

Demo

Recorded from a live run against Saved Messages (message_id sanitized):

$ python3 telethon_checklist.py create --from-plan plan.json
{"ok": true, "kind": "checklist-create", "chat": "me", "thread": null, "message_id": 12345,
 "title": "OSS smoke", "tasks_created": 2,
 "verified": {"title": "OSS smoke", "total": 2, "done": 0,
              "others_can_append": false, "others_can_complete": false,
              "tasks": [{"id": 1, "text": "step one", "done": false},
                        {"id": 2, "text": "step two", "done": false}]},
 "warnings": []}

$ python3 telethon_checklist.py toggle --chat me --message-id 12345 --done 2
{"ok": true, "kind": "checklist-toggle", "chat": "me", "message_id": 12345,
 "marked_done": [2], "marked_undone": [],
 "verified": {"title": "OSS smoke", "total": 2, "done": 1, ...},
 "warnings": []}

The checklist appears in Telegram as a real interactive card: checkboxes tick on tap and the progress counter updates for everyone in the chat.

Requirements

• Python 3.9+
• Telethon >= 1.44 (first release that ships the MTProto To-Do types)
• a Telegram account and API credentials (api_id / api_hash) from my.telegram.org
• Telegram Premium on the acting account for creating checklists (server-side restriction; get / toggle work without it)

Install / setup

1. Install Telethon:

   pip install "telethon>=1.44"
   

2. Get api_id / api_hash at my.telegram.org -> "API development tools".

3. Configure environment (or put the same lines into ~/.hermes/.env - the script reads both, environment wins):

   Variable	Required	Meaning
   TELETHON_API_ID	yes	numeric API id
   TELETHON_API_HASH	yes	API hash
   TELETHON_SESSION	no	path to the session file; default ~/.hermes/telethon/user.session
   TELETHON_CHECKLIST_CHATS	no	chat / topic allowlist beyond Saved Messages, enforced on every command (see below)
   HERMES_HOME	no	overrides ~/.hermes

4. One-time interactive login to create the session file (the skill itself is strictly non-interactive and will refuse cleanly if the session is not authorized):

   import asyncio, os
   from telethon import TelegramClient
   
   API_ID = int(os.environ["TELETHON_API_ID"])
   API_HASH = os.environ["TELETHON_API_HASH"]
   PATH = os.path.expanduser("~/.hermes/telethon/user")  # becomes user.session
   
   async def main():
       os.makedirs(os.path.dirname(PATH), exist_ok=True)
       client = TelegramClient(PATH, API_ID, API_HASH)
       await client.start()          # asks for phone + login code once
       me = await client.get_me()
       print("authorized as", me.username or me.id)
       await client.disconnect()
   
   asyncio.run(main())
   

5. Allowlist the chats the skill may touch - reads and writes alike. Saved Messages (me) is always allowed; everything else must be listed explicitly:

   # whole chat -1001234567890, plus chat -1009876543210 restricted to forum topic 33 only
   TELETHON_CHECKLIST_CHATS="-1001234567890,-1009876543210:33"
   

   Only negative ids (groups / channels) are accepted - user peers are out of scope by design. Topic ids start at 2; the General topic cannot be topic-restricted (allow the whole chat and omit --thread to post to General).

Usage

Every command prints exactly one JSON object to stdout and exits 0 ("ok": true) or 1 ("ok": false, "error": ...). stderr stays empty; there is never a traceback. The one human-facing exception is -h / --help.

Create directly (the user dictated the tasks):

$ python3 telethon_checklist.py create --title "Groceries" --task "milk" --task "bread" --chat me
{"ok": true, "kind": "checklist-create", "chat": "me", "thread": null, "message_id": 12345,
 "title": "Groceries", "tasks_created": 2, "verified": {...}, "warnings": []}

Read it back:

$ python3 telethon_checklist.py get --chat me --message-id 12345
{"ok": true, "kind": "checklist-get", "chat": "me", "message_id": 12345, "title": "Groceries",
 "done": 0, "total": 2,
 "tasks": [{"id": 1, "text": "milk", "done": false}, {"id": 2, "text": "bread", "done": false}],
 "others_can_append": false, "others_can_complete": false, "warnings": []}

Toggle and append:

$ python3 telethon_checklist.py toggle --chat me --message-id 12345 --done 2
$ python3 telethon_checklist.py ap