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.8.1. 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:

A prompt gets 👀 once the agent took it and 👌 when that turn ends (React to prompts in the settings). 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, /help lists the commands, and the
daemon posts its notices there. Only the configured group and the operators
from setup are accepted.

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.

Settings

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

The choices are saved in options.json and survive restarts. Every option,
its default and what it does: Options; how
presence is measured and what happens when you leave:
Quiet while at the desk; which
secrets are masked: Secrets in posts;
when topics are deleted: Topic cleanup;
where files land and when they go: Inbox.

Actions

Every action reports its outcome as a Herdr notification. stop, resync
and status talk to the daemon through a local control channel; see
Files, logs and state.

Upgrade

Herdr has no plugin update: reinstall to move to a newer version.

herdr plugin uninstall permgps.telegram-agents
herdr plugin install permgps/herdr-telegram-agents

The two commands name the same plugin in the two forms Herdr uses: uninstall
takes the plugin id, as printed by herdr plugin list, and install takes the
GitHub repository.

Your config.json, mapping.json, options.json and the Telegram topics
survive: Herdr keeps the plugin's config and state directories and never
deletes their contents, so the daemon picks up the same group and the same
topics after the upgrade. The manifest version always equals the release
tag, so a checkout runs the binary that tag was built from.

Documentation

License

MIT.