hermes-telegram-miniapp: Hermes Telegram Mini App: The Pocket Terminal That Turns a Self-Hosted Agent into an Operations Console
A fast, hardened Telegram Mini App for the Hermes agent. It does more than chat: it manages sessions, system status, cron jobs, and fork maintenance without losing the terminal feel.
- Hermes Telegram Mini App turns Telegram into a secure mobile control surface for a persistent self-hosted agent.
- The repo's core trick is process thinking: it watches a living terminal session, not a stateless chat response.
- Security is part of the product here, with Telegram identity checks and session-scoped destructive actions.
- The fork survives upstream churn by automating rebuilds and keeping local Telegram-specific changes isolated.
Most Telegram bots answer messages. This one behaves like a console. The clawvader-tech/hermes-telegram-miniapp project turns Hermes into a mobile control plane with system gauges, cron management, session continuity, and a terminal-first interface that feels closer to operations software than chat.
That shift matters because it changes the unit of interaction. You are not sending isolated prompts into a black box. You are attaching to a long-running agent, watching its output buffer, and deciding when the turn is actually over.
Telegram as a Terminal, Not a Chat App
The product's first move is aesthetic, but not cosmetic. It borrows the visual language of a terminal, then places it inside Telegram Mini Apps so the interface stays mobile-native without becoming messenger-shaped. The result is a pocket shell for Hermes: quick status, command-driven interaction, and enough system visibility to make the agent feel present.
The key idea is simple once you see it. The app does not ask, “what is the agent's reply?” It asks, “what is the current state of the terminal session, and has the prompt returned yet?”
The Agent Is Treated Like a Process
That process model is the technical center of gravity. In the frontend, the chat view keeps track of output length and slices new text from a persistent buffer. In the backend, Hermes is attached to a tmux session, which means the interface is observing a living shell, not spinning up a fresh request each time.
const hasPrompt = /\n[^|\n]*[>$#]\s*$/.test(outputTail)
if (!agentRunning) {
await ensureAgent()
}
const delta = buffer.slice(lastOutputLen.current)
lastOutputLen.current = buffer.length
if (hasPrompt) {
setTurnState('complete')
}That prompt detection step is the subtle win. A regex looking for a terminal prompt is a blunt instrument, but it is the right kind of blunt here. It lets the UI infer that Hermes has finished speaking without demanding a brittle response wrapper from the agent itself.
The HMAC-SHA256 method (which uses the bot token as a secret key) has subtle encoding edge cases that cause validation failures in practice. Ed25519 uses Telegram's published public key — no bot token needed, no encoding ambiguities, and it just works.
Security Is Layered, Not Bolted On
This is a mobile interface into something sensitive, so the repo treats auth as a product feature. Telegram init data is validated, ephemeral session tokens gate destructive actions, and sensitive endpoints get targeted rate limiting. The point is not just to keep strangers out. It is to keep the control surface trustworthy enough to expose real operations.
| Layer | What it protects | Why it matters |
|---|---|---|
| Telegram init-data validation | Who opened the Mini App | Prevents forged clients from reaching the backend |
| Ephemeral session token | Destructive actions | Keeps deletes and env changes scoped to the active session |
| Targeted rate limiting | Sensitive endpoints | Reduces brute-force pressure on secrets and admin paths |
Why the Fork Survives Upstream Change
The second differentiator is less visible and more important than it looks. This repo is not just an app. It is a maintenance system for a fork that has to coexist with upstream Hermes changes. The deploy script and post-merge hook let the project rebuild its Mini App after syncs, while preserving local Telegram-specific behavior that upstream does not know about.
| Problem | Naive fork | This repo | |
|---|---|---|---|
| Upstream changes land often | Merge conflict drift | Automated sync and rebuild flow | |
| Local Telegram features | Easy to overwrite | Kept isolated and re-applied | ],[ |
That is a real product problem, not just an ops detail. A great interface collapses if the maintenance path is fragile. Here, the maintenance path is part of the interface's credibility.
