herald
Herald lets you send messages, updates, client copy, files, and completion notices to Telegram, and manage a captured message inbox.
Discover destinations: list allowed projects and their default Telegram chats (
list_destinations).Send formatted text:
send_textwith raw Telegram HTML, provenance, brief/standard/detailed presets, and optional references.Send structured updates:
send_updatewith summary, blockers, completed, next steps, client questions, and decisions needed.Send client-ready copy:
send_client_copywith concrete topics and direct questions, omitting internal reasoning.Send files/images:
send_filewith auto/photo/document kind, captions, and path validation against allowed roots.Send completion notices:
notify_completionsends a concise formatted completion summary when explicitly requested.Inspect capture inbox:
inbox_statusreports buffered volume per chat and daemon heartbeat.Fetch buffered messages:
inbox_fetchretrieves messages by time range/chat, marks them taken, and can include previously taken rows.Mark messages archived:
inbox_doneconfirms archival and deletes downloaded buffer copies.Export inbox bundle:
inbox_exportwrites a self-contained folder with attachments and relative paths for archive import.
Provides tools for sending messages, files, and structured updates to Telegram group topics, as well as capturing incoming messages from working groups into a local inbox buffer.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@herald Send the latest report to the main topic"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Herald
Herald moves project messages, context, files and feedback between people and already-running AI coding sessions. Its core uses a transport adapter, with Telegram as the first and currently only implementation. Herald runs on your machine: you bring the bot, approve the destinations, and keep the token and project data local.
Send | Capture | Watch |
Telegram HTML, files, albums, named batches, replies, and delivery receipts | Project-scoped messages, attachments, reply context, and verified archive handoff | Address an open Claude Code or Codex session from the bot DM and reply through its fixed project route |
Ask naturally:
Send the result to the demo project through Herald.
Send these screenshots as an album with a short caption.
Read this project's Herald inbox.
The default batch is clean client text followed by a separate provenance reply.
Use herald-draft to prepare client-ready text without sending. Named batches can
combine text, files, albums, replies and durable delivery receipts. See
drafts and batches.
Watch is an optional bridge to sessions that are already open. It does not launch
an agent or bypass the host's wake-up model. /status exposes real poll activity,
monitor liveness and stale duties. See Watch runtime.
Install
Requires uv and Claude Code or Codex with plugin support. Use one installation method per client to avoid duplicate tools.
Claude Code:
claude plugin marketplace add ZenonEl/herald
claude plugin install herald@herald --scope userCodex:
codex plugin marketplace add ZenonEl/herald
codex plugin add herald@heraldThese commands install Herald from the marketplace's default branch. For local
development, use a checkout, run uv sync --locked, and register an MCP server
that runs uv run --directory /absolute/path/to/herald herald. The shared skills
are in skills/. Do not mix checkout registration with a marketplace installation
of the same server.
Create ~/.config/herald/config.toml from config.example.toml
if you do not already have a config. Set your bot token file, routes, and projects.
Keep the token and actual chat IDs outside this repository. Restrict token-file
permissions to the owning user. Use HERALD_CONFIG for another config location.
Start a new AI session and ask “Show Herald destinations.” Sending does not require the Capture daemon.
Related MCP server: MCP AgentChat
Update
Claude Code:
claude plugin marketplace update herald
claude plugin update herald@herald --scope userCodex:
codex plugin marketplace upgrade herald
codex plugin add herald@heraldOpen a new AI session after a code or tool-description update. Local writing-style
changes are reread by get_writing_rules, without restarting the server.
Files and albums
send_file sends one attachment. send_files accepts a list of absolute paths:
Mode | Behavior |
| 2–100 files, split into linked Telegram groups of ten |
| 1–100 files, ordered and linked to the first message |
kind=auto sends supported small images as photos and other files as documents.
An album must contain either photos or documents; use kind=document to send
mixed file types together as originals. Native video/audio album types are not
implemented yet; these files can be sent as documents.
All paths are checked against files.allowed_roots before sending. One logical
pack carries its caption and provenance once; later groups reply to the first.
The caption must fit 1024 visible characters including provenance. Batches stop
on a failed send and return confirmed receipts, unconfirmed files, and files not
attempted. There is no automatic retry of uncertain sends.
Album constraints follow Telegram's sendMediaGroup contract.
Configure instructions
See Customization for global and project writing styles,
server instructions, and tool descriptions. Defaults live in
src/herald/prompts/, are included in the Python package,
and can be overridden without editing Python or the installed plugin.
Capture and Watch
Enable Capture and list sources in [[capture.chats]], then run from a stable
checkout:
uv run herald-capture --once
uv run herald-captureRun only one poller per bot token. A user systemd unit is provided in herald-capture.service; adjust its checkout path before enabling it. Bot permissions and privacy settings must allow receiving the messages you want.
Capture is a temporary buffer, not a complete archive or a history reader.
inbox_status and inbox_fetch require a project by default. Explicit source/all
reads remain available: this is a filter for trusted local sessions, not an
access-control boundary between users. Export is source-scoped.
inbox_fetch is a read, not an archive import. Use inbox_export, import and
verify the bundle, then call inbox_done with an opaque archive_ref. Status
flags rows left taken but unconfirmed for more than 24 hours.
For optional Watch, configure an allowed private source and profiles, start the same
Capture daemon, and ask an open AI session to activate a profile. Send
#example Your request in the bot DM. Addressed documents, images, voice notes
and audio are downloaded into the local Watch delivery. A voice note has no normal
caption: reply it to a tagged command, or send a captioned audio file. Herald does
not require a transcription engine; an agent may use an available local one.
Use /help for configured profiles and commands. See
Watch runtime for the exact Claude/Codex duty model.
Architecture and boundaries
MCP tools call an application service; domain objects and a messenger protocol keep Telegram HTTP details in the adapter. Local configuration defines projects, routes, and allowed file roots.
Herald can send to every destination you configure. For review-before-forwarding, configure a private hub rather than a client chat. The skill requires an explicit send request; transport code cannot verify the intent behind an AI tool call.
Herald does not host an LLM, guarantee writing quality, or provide a full remote terminal. Your local config, inbox, token, and custom prompts belong outside Git.
Contributing
See CONTRIBUTING.md. Bug reports with a minimal, sanitized reproduction are welcome. Report whether you used a marketplace install or checkout, the Herald version, the tool called, and the expected result. Remove tokens, private paths, actual chat IDs, and client material.
License
Code and executable skill instructions use AGPL-3.0-or-later. The README documentation and editorial reference material use CC BY-SA 4.0. User messages and attachments keep their own licenses.
Available Tools
28 toolsbatch_cleanupAIdempotent
Delete completed batch ledgers older than the configured retention period, or the explicitly supplied positive number of days. Incomplete and unconfirmed attempts are always retained because deleting them would erase duplicate-send evidence. This removes local message text and file paths; it does not delete Telegram messages or attachment files.
Inputs: older_than_days.
batch_statusARead-onlyIdempotent
Read persisted delivery receipts by request_id. Includes roles, tags, sender session metadata, Telegram message ids and named reply relationships for archives. unconfirmed may mean delivered: do not retry automatically after a crash or timeout.
Inputs: request_id (required).
batch_templatesARead-onlyIdempotent
List named batch templates and the default for a project. Roles and tags are metadata, never automatically added to client text. Template contents fill text and paths by part id. Custom part arrays are also supported.
Inputs: project (required).
get_writing_rulesARead-onlyIdempotent
Read the current configurable writing style before composing a message.
Inputs: project.
inbox_doneA
Mark messages as archived, which deletes their downloaded copies.
Call this only after the messages are in the archive with their hashes. Pass a non-empty archive_ref that identifies the recorded destination/batch. Herald stores it as opaque evidence and does not parse it or call the archive. If there is no archive reference, do not mark the messages done. The buffer copy of a file is redundant from that moment and is what actually grows on disk. Each key is {"chat_id": int, "message_id": int}. Rows survive for the configured TTL so a mistake stays recoverable.
Inputs: keys (required), archive_ref (required).
inbox_exportA
Write a self-contained folder for a range, ready to import into an archive.
Prefer this over inbox_fetch whenever the messages are going into the archive: it copies the attachments next to inbox.json and rewrites their paths to be relative, which is the only form an archive will accept. Passing raw rows instead files every attachment as missing while the bytes are still on disk. Messages are marked taken; call inbox_done once they are recorded.
target must be a fresh directory. Set include_taken to rebuild a bundle for messages handed out earlier but never archived - that is the only route by which their attachments can still reach the archive.
Inputs: target (required), chat, limit, scope, +3 more.
inbox_fetchA
Fetch buffered messages for reading and mark them as taken. This is not an archive operation and must never be described as importing or recording them.
since and until are ISO-8601 timestamps compared against the message date in UTC. Rows carry the forwarded-message origin, so a forwarded quote keeps its real author instead of the person who forwarded it. Fetching does not remove anything. For archival work use inbox_export, import that bundle, then call inbox_done with the imported keys and an archive_ref.
Set include_taken to see messages handed out earlier but never archived - that is how a batch interrupted halfway is recovered.
Inputs: chat, limit, scope, since, +3 more. Returns: result
inbox_statusARead-onlyIdempotent
Summarise what the capture daemon has buffered, without fetching content.
Check this before inbox_fetch: it reports volume per chat and the age of the oldest unprocessed message, so a range can be chosen deliberately. last_poll is the daemon's heartbeat - if it is hours old the daemon is down and Telegram will start dropping undelivered updates after about a day. taken_unarchived is separate from new messages. If attention_required is true, say clearly that messages were read/exported more than 24 hours ago but have not been confirmed in an archive; recover them with include_taken=true.
Inputs: chat, scope, project.
list_destinationsARead-onlyIdempotent
List allowed projects and their default Telegram destinations.
Inputs: no named parameters. Returns: result
list_inbox_sourcesARead-onlyIdempotent
List capture sources and their project ownership without reading messages.
Inputs: no named parameters. Returns: result
notify_completionA
Send a completion notice only when the user requested notification.
Call get_writing_rules(project) before composing the summary. HTML is the default; pass raw Telegram tags. The tool preserves the supplied summary without adding a generic heading and appends the provenance signature.
Inputs: agent (required), model (required), project (required), subject (required), +6 more. Returns: object
preview_batchARead-onlyIdempotent
Prepare and structurally validate a message batch without sending or storing it. Read get_writing_rules first. Supply either parts or template/contents. Parts use unique ids and reply_to names an earlier part. Kinds: text, file, album, provenance. Roles and tags are arbitrary metadata. Provenance is generated, requires reply_to, and takes no text/files. No automatic signatures are added to other parts. All file paths and platform size limits are checked. validation=structure_only is NOT a claim of factual accuracy or client readiness; the AI must check those. Top-level reply_to may anchor one selected reply_part to a stored inbox message; this is separate from a part's named reply_to relationship.
Inputs: agent (required), model (required), project (required), subject (required), +6 more.
send_batchA
Send an explicitly authorized batch after draft review and structural preview. Use one stable request_id per intended send. Reusing it returns recorded receipts, never resends uncertain/unfinished parts; a different plan with that id is rejected. Inspect complete and every part state: sent, unconfirmed, not_attempted. On error, stop and report exactly what is confirmed. Do not create a new id to retry blindly. All messages share one configured destination. Internal/provenance parts are not client copy. Signature metadata identifies the sending session, not text authorship. Top-level reply_to is a stored inbox key; reply_part selects the root batch part that answers it. Nested part reply_to still names an earlier part. Album parts accept 2–100 files and are split into linked Telegram groups of ten.
Inputs: agent (required), model (required), project (required), subject (required), +7 more.
send_client_copyA
Send copy-ready text addressed directly to the client.
Use this tool for explicitly requested named topics, so a manager can copy the body without understanding the project or rewriting it. Each topic title must be a concrete subject taken from the client message or current project, such as "Оплата" or "Фотографии". Never use fixed report headings such as "Проблемы", "Нужно решить", or "Вопросы". Preserve all subjects raised by the client that are inside the requested scope; brevity removes internal reasoning, not necessary facts.
Put concrete facts, proposals, and next actions in details. Address the client directly. Add question only when its answer blocks the next action now, and ask only the earliest unresolved dependency. Omit question when no answer is needed. Keep the visible topic self-contained. Use quotes only for an exact source or optional supporting detail: mode="visible" for a short source and mode="expandable" for longer material. A quote must not hide a required fact, action, blocker, or question, duplicate the visible body, or contain internal reasoning. title can identify the source or say "Подробнее". Do not shorten by a fixed word or item count. Keep all facts the client needs; the only hard content limit is Telegram's 4096 visible characters.
Inputs: agent (required), model (required), topics (required), project (required), +4 more. Returns: object
send_fileB
Send an explicitly requested local file or image with a concise caption.
The path must resolve under files.allowed_roots. kind=auto sends supported, small images as Telegram photos and everything else as documents. Use raw Telegram HTML in an HTML caption and keep it within the 1024-character limit.
Inputs: path (required), agent (required), model (required), caption (required), +7 more. Returns: object
send_filesA
Send explicitly requested files as an album pack (2–100, split into Telegram groups of ten) or separate ordered messages (1–100). Use this only for a simple signed pack; use send_batch when files need multiple captions, roles/tags, clean client copy or a separate provenance reply.
Album auto accepts all photos or all documents; use kind=document for a mixed pack. All paths must be inside files.allowed_roots. One logical pack carries the caption and provenance once; later groups reply to the first. The caption must fit 1024 visible characters. Inspect complete, sent, unconfirmed, not_attempted. Never automatically retry unconfirmed files: they may have been delivered.
Inputs: agent (required), model (required), paths (required), caption (required), +7 more.
send_textB
Send a free-form formatted message with provenance metadata.
Call get_writing_rules(project) before composing. HTML is the default. Use raw Telegram tags: , , , , , , ,
Inputs: text (required), agent (required), model (required), project (required), +6 more. Returns: object
send_updateA
Send an explicitly requested structured internal update.
Call get_writing_rules(project) for the current writing style. The server renders summary and nonempty list fields as escaped Telegram HTML. Fields must remain within preset-specific character and item limits. Use send_text for free-form messages without those field limits.
Inputs: agent (required), model (required), project (required), subject (required), +10 more. Returns: object
watch_ackB
Close a claimed delivery when no content reply is required, or record failure.
Inputs: duty_id (required), success (required), delivery_id (required), error.
watch_activityA
Report this session's current activity: processing, waiting_user, or idle. Use while working and after replying if waiting for input. This is a self-report, not proof of polling. Only watch_wait updates last_poll_at. Refresh during long work when practical; stale activity is displayed as unknown, never assumed busy.
Inputs: state (required), duty_id (required).
watch_inspectARead-onlyIdempotent
Explicitly inspect mine, unaddressed, or the gated all-delivery view.
This is read-only and never claims a delivery. all is refused unless watch.allow_inspect_all=true. Normal work uses watch_wait instead.
Inputs: scope (required), duty_id (required), limit. Returns: result
watch_listARead-onlyIdempotent
List configured Watch profiles without registering a duty session.
Inputs: no named parameters. Returns: result
watch_replyA
Reply to a claimed Watch delivery through its configured Herald route.
The caller supplies no Telegram ids, project, route, agent, or model. Herald derives them from duty_id, delivery_id, and the validated profile. It tries a native Telegram reply first and uses a quoted fallback only after an explicit Telegram rejection. The delivery closes only after a send receipt.
Inputs: text (required), duty_id (required), subject (required), delivery_id (required), +1 more.
watch_reply_batchB
Reply to a claimed Watch delivery with a named, idempotent batch. Herald derives the project, route, source reply, agent and model from the duty and profile. Use this for clean client copy plus a separate provenance reply, multiple text parts, files or albums. Use the same stable request_id to inspect an interrupted attempt; never create another id to retry an unconfirmed delivery. Check complete, every part state and delivery_state before reporting success.
Inputs: duty_id (required), subject (required), request_id (required), delivery_id (required), +4 more.
watch_startA
Register this already-open AI session for deterministic Watch delivery.
The returned duty_id is required by every ordinary Watch read or write. Several profiles require an explicit primary_profile for #all replies. replace is an explicit takeover; it is never inferred. This registers only. It does not start polling. Retain monitor_command and use it with a verified host wake-up monitor, or keep watch_wait running in an active loop. A background shell alone does not wake the AI. Never report unattended listening unless a real addressed test reaches this session.
In Claude Code, Monitor is deferred: load it with ToolSearch("select:Monitor"), then give Monitor the returned command directly with stderr redirected to stdout and a 30-minute timeout. Do not use Bash run_in_background. Re-arm Monitor when its timeout fires.
In Codex, continue current project work by default. Poll cooperatively with watch_wait(timeout=0) at natural checkpoints and after blocking commands; do not report empty polls. Handle a delivery, then resume the interrupted task. Use a foreground wait only for explicitly requested pure duty. Ending the turn still ends polling.
Duties expire after 15 minutes without a monitor probe, AI poll, activity update or acknowledgement. Expiry releases the profiles and unfinished deliveries.
Inputs: agent (required), model (required), session (required), profiles (required), +2 more.
watch_statusAIdempotent
Show this duty's delivery counts, observed_state, activity timestamp, last_poll_at and monitor_at. Registration is not polling. monitor_alive proves only a recent companion probe, not AI wake-up. Stale activity is unknown; self-reported activity does not refresh last_poll_at. lease_age_seconds is the age of the freshest monitor, poll or activity signal; state=expired means the 15-minute lease ended and the profiles were released. Use this to verify a promised listener.
Inputs: duty_id (required).
watch_stopA
Stop this duty and return its unfinished deliveries to their profiles.
Inputs: duty_id (required).
watch_waitA
Wait for and claim only the next delivery addressed to this duty_id.
This never returns another session's delivery, unaddressed messages, or a global queue. A timeout returns {"delivery": null}.
Inputs: duty_id (required), timeout.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
The tool set is divided into distinct domains: watch duties, inbox capture, file/sending, and batch operations. A few closely related pairs like send_file vs send_files and watch_reply vs watch_reply_batch require careful attention to descriptions, but each tool has a clear purpose and overlaps are minimal.
Most tools follow a predictable [resource]_[action] or [action]_[resource] pattern with strong prefixes like watch_, send_, and inbox_. Minor inconsistencies exist such as inbox_done vs watch_ack and get_writing_rules vs list_destinations, but the overall pattern is readable and coherent.
At 28 tools, the count is on the heavier side, though justified by the server's broad scope covering watch lifecycle, inbox capture, batch sending, and file delivery. Some consolidation is possible (e.g., send_file could fold into send_files, watch_reply into watch_reply_batch), making the set feel slightly bloated.
The tool surface covers full lifecycles for its core workflows: watch duties from start to stop, inbox operations from status to archive, batch lifecycle from templates to cleanup, and multiple sending modes. Minor gaps like template editing and writing-rule modification exist, but these are plausibly managed externally.
Maintenance
Related MCP Connectors
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables interaction with Telegram to send, read, and search messages across chats and dialogs. It supports waiting for incoming messages and retrieving conversation history through natural language commands.17 npm3MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server enabling AI agents to interact with users via Telegram, supporting message and image sending, inline quick replies, and waiting for user responses.9 npmMIT
- FlicenseBqualityDmaintenanceA specialized MCP server that allows AI coding assistants to send direct messages via your personal Telegram account.1-
- FlicenseNot gradedqualityDmaintenanceAn MCP server for sending and receiving Telegram messages via a bot, enabling AI assistants to interact directly through Telegram by sending messages, reading recent messages, and sending photos.-