harness-multitool

Telegram

The daemon carries a Telegram channel of its own: you write to your agents from the phone, they answer there with text, pictures and files, and you approve their plans and control the harness with buttons.

What it is

Telegram is the harness daemon's own channel, in crates/daemon/src/telegram.rs, independent of any other program (CON-156). One bot serves every session of the machine, whatever profile its window runs on (CON-87, CON-124).

Each chat, or each forum topic of a group, is bound to one session. A message from an allowed user reaches that session's agent as the user's own words, and the agent answers into the same chat or topic.

How it works

Who can reach an agent

Only users listed in allowed_users are delivered (CON-52):

The bot token is the harness's own. It appears in no log, status or error, and the settings page never shows a saved token (CON-52, CON-87).

How a message reaches an agent

A message from Telegram reaches the agent as [telegram_message]: <text> (CON-158). In the window it shows as a Telegram card.

The agent treats it as a message typed in its window: it counts as the user's words, for example for approving a plan. Callbacks and other agents' messages stay data, and a permission prompt is still answered in the window.

A message for a session that is not open waits for it and goes by itself when it opens, marked (sent <local time>, held until now). A message that waited more than 24 hours is dropped and said, never delivered as new (CON-168).

How an agent answers

The agent answers with telegram_send, which asks your permission first, naming the files (CON-52, CON-159):

A delegate (Claude Code, Codex) gets telegram_send over the harness's MCP server, as mcp__harness__telegram_send (tools.md).

Plan approval

A plan waiting for approval is asked in two places at once, for a delegate and the harness's own loop alike (CON-161, CON-163):

The first answer decides, and the other place follows. Answered in the window, the Telegram message loses its buttons and says where it was decided. Answered on Telegram, the window's card is withdrawn and a toast says so. A press from someone not allowed does nothing.

Using it

Setup

  1. Create a bot of its own for the harness. Another program polling the same bot competes for its messages, and the daemon's Telegram status names that as its error (CON-156).
  2. Give the token in MULTITOOL_TELEGRAM_TOKEN (it wins over the file), or on Settings > Telegram.
  3. Send /id to the bot, and put your user id in [telegram] allowed_users, on Settings > Telegram.
  4. Saving the page restarts the channel at once (CON-87).

Telegram's settings live in ~/.harness/shared.toml, the same for every profile (ADR 0026). With no token, nothing polls.

[telegram]
allowed_users = [123456789]
terminal = "gnome-terminal --"  # optional: the command /open and /new put multitool after

Commands

CommandDoes
/start, /agentslist the open sessions, with a button each (CON-87)
/switch <number or words>bind this chat or topic to a session
/whoamisay which session this chat is bound to
/nick <name>name the bound session's agent (CON-88)
/idyour own user id; answers anyone
/openevery conversation the daemon has hosted, by project, newest first: an open one is switched to, a closed one opens in a new terminal window in its project (CON-167)
/newa new session in a chosen project
/reloadreload every open window
/restartrestart the daemon through its service, after a ✅; it ends the runs going on
/servicebring back the Service button

These commands reach no agent. An unknown command goes to the bound session like a message. /open, /new, /reload and /restart say in the chat when they are done.

A message with no binding goes to the only open session, and says so. With several open, it is held, and you get buttons to choose; at most 20 are held per chat, never dropped in silence (CON-87).

The Service button

A 🛠 Service button stays at the bottom of each chat (CON-169). It reaches no agent, and opens these controls as buttons: Open, New, Reload windows, Restart daemon, Sessions and Which session.

Status

multitool daemon --status shows the channel's counters, and the harness says how the channel stands: off with no token, on with the chats bound and the messages waiting, or on with its last error. The token is never shown.

Limits and status

Specs and decisions

This page's source