Telegram Agents for Herdr

One Telegram forum topic per live Herdr agent: status in the topic icon, messages both ways.

A Herdr plugin that mirrors the Herdr Agents panel into a Telegram forum supergroup, so you can watch and drive your coding agents (Claude Code, Codex, Gemini, ...) from a phone. Every agent gets its own topic, the topic icon follows the agent's status, its questions land in the topic with a notification, and what you write there goes back to the agent. One command installs it; no Go, no Node, nothing else on your machine.

The Herdr agents panel: three agents, one working, one idle, one waiting.

The same agents in Telegram: one topic each, the icon is the status, and the open topic shows a Claude Code question you can answer from the phone.

What you get

• A topic per agent, named like the Agents panel row (V3Jobs · claude), created when the agent appears and reused after a restart.
• Status at a glance: the topic icon is ⚡ working, ✅ idle, ❓ blocked, 🏆 done, 👀 unknown, 🏁 exited.
• Questions come to you: when an agent gets blocked on a question or an approval, the screen is posted into its topic and, for a numbered dialog, with one button per option; the bot also sends you the question in its private chat with a sound and a link, so you can mute the group and still hear the one thing that matters. When the agent finishes, the tail is posted silently.
• Answers go back: plain text becomes a prompt, y / n / 1..9 / enter / esc answer dialogs, /keys sends raw keys.
• Look at the screen with /screen, or /screen all for everything the agent printed since your last message.
• Claude Code commands /clear, /compact, /usage, /model are typed into the agent and the result is posted back.
• Rename or close a topic in Telegram to rename or mute the agent in Herdr.
• A control panel in the General topic: a pinned dashboard with every agent, its status and how long it has been in it, edited in place; /status with the same lines, /options, /away, /here, /help, daemon notices.
• Quiet while you are at the machine (opt-in): topic edits wait and screen posts go silent while your keyboard or mouse is active; when you leave, everything catches up and a question still waiting rings once. Off by default, one tick in /options; macOS and Windows, Linux has no idle source yet.
• Settings from the phone: /options opens a panel with buttons to pause the mirror, tune quiet mode, pick the status icons, mask secrets in posts and delete the topics of exited agents after a while.
• A daemon that looks after itself: starts with Herdr, exits when Herdr is gone, heals topic drift on start and on resync.

Version 0.10.0. macOS and Linux are verified end to end; Windows is built and unit-tested on every change but has not been run against a real Herdr yet.

Requirements

• Herdr 0.7.5 or newer
• A Telegram bot token from @BotFather
• A Telegram supergroup with Topics enabled, where you can promote the bot
• sh and curl (macOS, Linux) or PowerShell 5.1+ (Windows) for the install step

Install

herdr plugin install permgps/herdr-telegram-agents

Herdr clones the repository and runs the plugin's build step, which downloads the release binary for your OS and architecture into bin/, verifies its SHA-256 against the release checksums and makes it executable. Supported targets: darwin/amd64, darwin/arm64, linux/amd64, linux/arm64, windows/amd64. The plugin is listed on the Herdr marketplace; the command above is the one the card shows.

Then run the setup below. Herdr shows the Telegram Agents actions listed further down and runs bin/herdr-tg startup after every session restore.

If you download a binary with a browser instead, macOS marks it quarantined; xattr -d com.apple.quarantine bin/herdr-tg clears that. Binaries fetched by the install script carry no quarantine attribute.

Setup

1. Create a bot with @BotFather and copy its token.
2. Create a supergroup and enable Topics in its settings (this makes it a forum). You must be its owner or an administrator who can add admins.
3. In Herdr run the action Telegram Agents: setup (from a Herdr pane: herdr plugin action invoke permgps.telegram-agents.setup). A popup asks for the token (typed visibly; the popup closes when setup ends) and prints a https://t.me/<bot>?start=setup link.
4. Open the link, press Start and tap Choose group. Telegram lists your forum groups and adds the bot to the one you pick as an administrator with Manage topics, Delete messages and Pin messages. The person who picks the group becomes the operator. Adding the bot to a forum group by hand with those rights works as well. Pressing Start also opens the private chat the bot uses to ring you about questions.
5. Mute the group in Telegram (group name → Mute → Forever). Every status change is a topic edit that would ring; muted, the icons and the dashboard stay current in silence and a question still rings from the bot's private chat. See Silence the group.
6. Back in the popup confirm the group. The wizard saves config.json and starts the daemon. From now on the daemon starts automatically with Herdr while a configuration exists.

Run the setup action again to reconfigure; it asks before overwriting. The token, the mapping, the options and the logs live in Herdr's plugin config and state directories; the files are listed under Files, logs and state.

Talking to agents

A blocked agent posts its screen with a notification, a finished one posts its tail silently. Anything you write in the agent's topic goes back:

Prompts are delivered silently; tick React to prompts in the settings and a prompt gets 👀 once the agent took it and 👌 when that turn ends. A question with Type something. carries a ✏️ button: press it and your next message is typed as the answer. A multi-select question keeps its buttons as toggles, redraws the post with the ticks and adds ✔ Submit.

The General topic is the control panel: a pinned dashboard lists every agent with its status and how long it has been in it, /status prints the same lines with a link to each topic, /new <workspace> [kind] starts an agent in a new tab of that workspace, /options opens the settings panel, /away [2h] and /here override the presence check, /observers [add|remove <id>] manages who may watch, /help lists the commands, and the daemon posts its notices there. Only the configured group is accepted; in it, the operators from setup drive the agents, observers added with /observers may read the group and use /status and /help in General, and anyone else is ignored and logged with their id (see Operators and observers).

Timings, buttons, how the Claude Code commands are forwarded, how /screen all collects its history and what /status shows in General are in docs/commands.md.

Too many notifications?

A group with sound on rings for every topic edit, every screen post and every daemon notice, and a few agents produce dozens of those an hour. Mute the group in Telegram (group name → Mute → Forever) and keep it muted: the topic icons, the pinned dashboard, the done posts and /screen replies all keep arriving, silently, ready when you open the app. Nothing important gets lost, because the one thing that needs you, a question from an agent, is relayed by the bot: it posts the question into the topic and sends it to you in your private chat with the bot, with a sound and a link that opens the topic at that post. Answer there as always. That relay is Questions in the bot's chat in the settings, on by default; the details and the one-time Start it needs are under Silence the group.

Settings

/options in General opens a panel of buttons, one message edited in place. Its groups: