One command when attention is needed
A script or agent runs tmsg notify with a plain-text message. There is no daemon to manage and no separate application server in the middle.
Projects
Public projectTelegram Message
tmsg.
A small Telegram notification CLI for scripts and AI agents that need your attention.
Why I made it.
I wanted my scripts and AI agents to have a simple way to reach me when I was away from the computer.
Long-running work does not always finish while I am sitting at the terminal. Sometimes an agent completes a task, gets blocked, or needs a decision before it can continue. Checking the screen repeatedly defeats the point of letting that work run on its own.
tmsg gives that work one small escape hatch: send a Telegram message and stop. It is intentionally direct, with local configuration and behavior that a shell script can understand.
Engineering notes
Private local configuration
The bot token and numeric target ID stay in an XDG-compatible config file, protected by private permissions and replaced atomically when settings change.
Made to behave like a CLI
Success, runtime failure, and invalid usage have distinct exit codes. Diagnostics go to stderr, and the bot token is redacted from Telegram API errors.
What it does.
tmsg does one outbound notification job and stops. Features that would blur that boundary stay outside the project.
BUILT IN
- Plain-text notifications from 1–4096 Unicode characters
- One configured bot and numeric user or chat ID
- XDG-compatible local configuration
- Private 0700 directory and 0600 file permissions
- Atomic configuration writes
- Exit codes for success, runtime failure, and usage errors
LEFT OUT
- Retries or delivery guarantees
- Queues or notification history
- Rich text or media
- Multiple profiles or recipients
- Two-way conversations
- General Telegram client features
Predictable by design.
Automation needs a small, stable contract more than it needs a long feature list.
tmsg notify "Agent finished and needs review"- Exit codes
- 0 for success, 1 for configuration, network, or API failure, and 2 for invalid command usage. Errors are written to stderr.
- Timeout
- The Telegram request stops after ten seconds. tmsg does not retry or claim that a notification was ultimately delivered.
- Configuration
- Settings are written atomically to an XDG-compatible path, with 0700 permissions on the directory and 0600 on the file.
- Secret handling
- The configured bot token is not printed back and is redacted from Telegram API errors.
tmsg is public on GitHub.
Read the source, setup instructions, and command reference in the repository.