# tg-signer automates Telegram check-ins by clicking reply keyboards with a vision model

> The interesting technical detail is that this is not a bot. It logs in as a user session, reads the reply keyboard a human would see, and picks a button, using a language model for the two cases a rule cannot handle: recognising which option matches an image, and solving an arithmetic question. Everything else is a task recorder with a scheduler.

**amchii/tg-signer** — 电报自动执行（签到、发送消息、点击键盘、AI回复等）；个人、群组、频道消息监控、转发与自动回复。Automated Telegram tasks (check-ins, sending messages, keyboard clicks, AI replies, etc.); monitoring, forwarding, and auto-replying to private, group, and channel messages.

- Repository: https://github.com/amchii/tg-signer
- Stars: 1,048 · Forks: 243
- Language: Python
- License: BSD-3-Clause
- Published: 2026-09-30 · Updated: 2026-09-30 · Language: en
- Canonical page: https://hysenlabs.com/projects/amchii-tg-signer

## It logs in as you, which is the design and the risk

Installation is one package install, with a compiled speed-up variant available separately:

```bash
pip install -U tg-signer
```

The first thing to understand is what kind of client this is. The readme's login instruction is to enter a phone number and a verification code, and the resulting session is stored in a file named after the account, in a directory you choose, or held in memory instead. The dependency on the Telegram client library is a user-mode library, not the bot API, and the project name in the manifest and the command name both say signer rather than bot. That choice explains everything else in the readme. A bot API integration receives events and can send messages, but it cannot read the inline reply keyboard a human sees in a chat and cannot press it. So to automate a check-in bot that expects a button press, you either find its API or you become the user. This tool takes the second route, which means the stored session is a full account credential: it can read your chats, and the readme's own command list includes listing folders, listing members of a channel, and listing topics. That is a lot of capability for a check-in tool, and the session directory and working directory defaults being a relative dot path is worth thinking about before you run it on a shared machine or in a directory under backup.

## Five action types, and the two that need a model

The task configuration is a recorded sequence of actions, and the readme's worked example walks through five of them in order. There is sending plain text. There is sending a dice-style emoji. There is clicking a reply-keyboard button by its label. There is choosing an option based on an image. And there is answering an arithmetic question. The first three are deterministic and need nothing but the session. The fourth sends an image to a language model and asks it which option to press, and the readme warns that you must ensure your model supports image recognition. The fifth sends a maths question to a model and takes its answer. So the model is not writing content, it is answering two perception-and-reasoning subproblems that a rule cannot express. That is a narrow and defensible use, and it is the honest limit of what an automated user can do: press the button a human would press, and work out the answer a human would work out. The configuration is stored per task, the run is idempotent in the sense that it will not repeat a check-in already done today unless you ask it to, and a record of recent runs is kept so you can check whether it worked.

## A rules engine that supersedes the monitoring feature, which is a good sign

The feature list ends with a rules engine described as having three trigger kinds, message, timer and startup, with a chain of handlers. And the command list contains a note that the automation command is recommended and that it covers the monitoring capability. That is an unusual and healthy thing to find in a readme: a feature explicitly deprecated in favour of a more general one, rather than quietly kept alongside. It suggests the author found the older design limiting and rebuilt it rather than maintaining two paths. The older capability is still substantial. It monitors personal chats, groups and channels, forwards messages, and auto-replies. Its existence explains the rest of the command surface, which is a lot of commands for a check-in tool: exporting and importing configuration, listing existing configuration, listing recent sign-in records, listing scheduled messages, listing group topics, listing channel members, listing dialog folders, sending a one-off text, sending a one-off dice roll, running a single task once, running several accounts at once with one configuration, configuring a scheduled-message feature of Telegram itself, logging in and out, and configuring a language model. This is a personal automation client for Telegram that happens to have check-in as its most documented use.

## Optional extras, two prebuilt images, and a web interface

The packaging is worth a paragraph because it shows the author's priorities. The base install is one package, and there are three extras, each corresponding to a real optional capability: a speed-up extra that adds a native crypto library, a YAML configuration support extra, and a web interface extra that adds a component library. The speed-up extra is the interesting one, because it is a compiled extension that makes the user session's encryption faster, which is exactly the bottleneck when you are polling a chat rather than sending one message. Two prebuilt images are published in a container registry, one for the command line and one adding the web interface, and a local build is documented in a separate directory with its own Dockerfile and readme, so the local path is not an afterthought. The web interface is launched by a subcommand that takes an authentication code argument, which is a crude but effective gate: the interface is meant to be bound locally or behind your own authentication, and the readme is honest that you pass a code to start it. The readme does not describe what the interface exposes beyond a screenshot, so for a tool holding account sessions, that is the first thing to look at before running it anywhere reachable.

## A command surface that documents its own sharp edges

The readme's example list is unusually careful about the ways its own commands can confuse you, and that is worth reading as documentation quality rather than as a feature. Several commands are documented as requiring that the target chat has already seen the account, with a note about a specific identifier, which is a protocol requirement rather than a bug. Sending to a group topic needs a thread identifier, and there is a separate command to list the topics of a forum group so you can find it. Negative identifiers need a double-dash separator before them, and the readme explains why in a parenthesis about POSIX argument parsing. A message can be sent and then deleted after a delay, which is how you avoid leaving a check-in receipt in a chat. The proxy configuration is explicit that the tool does not read system proxy settings and that you set an environment variable or pass a flag. And the time zone resolution is documented as a three-step order ending in a hard-coded fallback zone, with a note that setting the environment variable before running is how you override it. A tool that automates a daily task for a year is only reliable if these details are right, and the author has written them down.

## Conclusion

Use tg-signer if you need a repeatable interaction with a Telegram chat that has no API, because the tool works as a user session and replays a recorded action sequence, which is the only approach that reaches a bot that expects a human. Do not adopt it as a general bot framework, since its feature list is built around one workflow, and note that a user session is a credential with your full account attached. Four things to verify. How your session is stored, because the readme offers both a file and an in-memory option, and a session file plus a database of check-in records sitting in a working directory is a full account compromise if that directory is synced or shared. Which chat identifiers you target, because several commands are documented as requiring that the chat has already seen the account, which is a protocol constraint you have to satisfy by sending something by hand first. Whether the language model calls leave your machine, since two of the five action types call an external model and the readme tells you to set the key and base URL through environment variables, which means you can point it at a local endpoint if that matters. And what the time zone resolution does to your schedule, because the documented order falls back to a hard-coded default zone when nothing else is set, and a check-in that fires at the wrong hour is a silent failure. The licence is BSD-3-Clause, version 0.9.1 was released on 2026-09-01, and the last push was the same day.

## FAQ

### How does tg-signer automate a Telegram check-in?

It logs in as a user session rather than through the bot interface, and replays a recorded sequence of actions: sending text, sending a dice emoji, clicking a reply-keyboard button by label, choosing an option from an image using a language model, and answering an arithmetic question using a model. Tasks are recorded once and then run on a schedule.

### How is the Telegram session stored?

As a file named after the account in a session directory you choose, with a working directory holding configuration and check-in records, or optionally in memory. The readme documents an in-memory option, a log-in command that stores the session, and a log-out command that deletes the session file.

### What optional features does tg-signer have?

Three extras: a speed-up extra adding a native crypto library, an extra enabling YAML configuration support, and an extra adding a web interface. Two prebuilt container images are published, one for the command line and one including the interface, and a local build with its own Dockerfile is documented in a separate directory.

### How does tg-signer handle time zones for scheduled runs?

In a documented order: an environment variable, then the local time zone the interpreter detects, then a hard-coded fallback. The readme says to set the environment variable before running if you need the next execution time calculated for a specific zone, since a wrong zone makes a daily task fire at the wrong hour.

### Which language model does tg-signer use?

The readme tells you to set the API key and base URL through environment variables, that the default model is one from a well-known vendor, and that the model can be changed with another environment variable. Two of the five action types use it, for image recognition and for answering arithmetic questions, and the base URL setting means you can point it at a local endpoint.

### What licence is tg-signer released under?

BSD-3-Clause. It requires Python 3.10 or later, and version 0.9.1 was released on 2026-09-01, the same day as the last push to the default branch. The readme also links an English version and a wiki-equivalent document directory with a detailed automation guide.

## Sources

- [amchii/tg-signer on GitHub](https://github.com/amchii/tg-signer)
- [Issues](https://github.com/amchii/tg-signer/issues)
- [License: BSD-3-Clause](https://github.com/amchii/tg-signer/blob/main/LICENSE)
- [README](https://github.com/amchii/tg-signer/blob/main/README.md)
- [Releases](https://github.com/amchii/tg-signer/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/amchii-tg-signer