Using itTelegram and Discord
Telegram and Discord
Messaging gives each conversation its own Telegram topic or Discord channel. The
vendetta-telegram and vendetta-discord plugins are supervised by the notification
worker, each on its own, so there is no other daemon to run. They handle all six
providers, in tmux or in any other terminal. Only the configured owner can send input.
The vendetta-app plugin serves the iOS and web apps with the same
routing; most of the commands and behavior below apply to them too.
vendetta notify start
vendetta notify status # plugins: telegram=runningTelegram setup
Section titled “Telegram setup”Enable Topics for your bot in @BotFather, then:
[master]
project = "vendetta-master" # optional
[plugins.telegram]
owner_id = 123456789 # your numeric user ID
token = { env = "VENDETTA_TELEGRAM_TOKEN" }
# or a command that prints only the token:
# token = { command = ["op", "read", "op://Vault/Item/password"] }A token command runs as a literal argv, with no shell, within 8 seconds. Unlock
your password manager before starting the worker. Tokens are kept only in memory.
Stop any other poller for the same bot.
New conversations. Message an unbound topic to open a picker, then:
- Choose a project (recently active first) or type a project name or path.
- Choose a provider the worker launches (
[harnesses]), and for omp or Claude a profile, then press Start. It starts on the worker’s launch host ([launch] host). - Once the agent is identified, choose whether your first message becomes its prompt.
/session starts another conversation from an existing Telegram chat, and /cancel
leaves the picker. Optional profiles:
[[master.sessions.profiles]]
name = "reader" # omp unless provider is set
description = "Read and search only"
skills = []
tools = ["read", "grep", "glob", "web_search"]
[[master.sessions.profiles]]
provider = "claude"
name = "claude-reader"
description = "Claude read/search tools"
tools = ["Read", "Grep", "Glob"]Omitted fields inherit native settings, and empty lists disable that capability. A profile is fixed for the conversation’s lifetime. It selects launch options and is not a sandbox.
Topic titles start with the agent’s state: ◌ starting, ▶ running, ✓ ready,
? question, ⚠ approval, ○ unknown for over 10 seconds, ■ exited while running. Exited topics stay
and keep their last title, without a notice. A new message in one restores that
exact conversation.
Discord setup
Section titled “Discord setup”- In the Developer Portal, create a bot with Message Content Intent.
- Create a private category: deny View Channel to
@everyoneand allow it for you and the bot. Add a#controlchannel inside it with synced permissions. - Grant the bot Manage Channels, View Channel, Read Message History, Send Messages, Attach Files, Embed Links, and Pin Messages.
[plugins.discord]
owner_id = "123456789012345678" # quoted IDs
guild_id = "234567890123456789"
category_id = "456789012345678901"
channel_id = "345678901234567890" # #control
token = { env = "VENDETTA_DISCORD_TOKEN" }Discord layout and behavior:
- Each project gets a private category copied from yours, and each conversation a channel inside it. Channel names don’t change after creation.
- Each channel has a pinned status card with Open, Latest reply, Refresh, and Stop (interrupt only).
#controlhas a pinned dashboard with filtered, paged views of all conversations, and text there goes to the Master.- After downtime, missed messages are recovered from channel history, in order.
- Slash commands are typed as ordinary message text.
Commands
Section titled “Commands”| Command | Effect |
|---|---|
/help, /agents |
Commands; live agents and idle-timeout eligibility |
/status |
Whether the agent can take a prompt now, and why not |
/read |
Read-only terminal snapshot (untrusted) |
/progress |
The agent’s Progress in full (omp and Claude natively, any agent through vendetta agent plan); your personal tasks in the Master’s topic |
/queue <prompt>, /q |
omp’s native queue: a follow-up without steering |
/stop |
Telegram and app: SIGTERM the agent once; its conversation and topic stay restorable. Discord: interrupt the turn. |
/delete |
Delete the agent and its topic: after Yes/No confirmation on Telegram and in the app, at once on Discord |
/photo <path> |
Send an image file from the agent’s machine; a relative path starts at its directory |
/new |
Reset an idle omp conversation in the same topic, on Telegram and in the app. For Claude, use /clear locally. |
/mute, /unmute |
Mute the topic’s agent, or unmute it (see below) |
/keep, /unkeep |
Keep the topic’s conversation from auto-delete, or stop keeping it |
Other slash commands go to the provider literally. Optional: register queue and
transcribe with BotFather’s /setcommands so they appear in the menu.
Talking to agents
Section titled “Talking to agents”-
Text goes to the topic’s agent while it is idle, ready, or running, as a normal prompt and never an interrupt. In the root chat it goes to the Master. Telegram reacts 👍 when the agent accepts a message and 👎 when it rejects one. A message the agent accepted but will never read, as when Claude drops it after Escape in its terminal, turns 👎 with a “Not delivered” notice (Discord gives the notice alone); send it again to retry. Nothing is resent for you.
-
Replies from omp, Codex, and Claude come from their transcripts, formatted. OpenCode, Gemini, and Aider send labelled terminal snapshots instead.
-
While it works, one message is edited as the agent goes; the apps label it Activity. It holds commentary and quoted reasoning:
[plugins.telegram.progress] # or [plugins.discord.progress] commentary = true reasoning = true # may contain sensitive context tool_calls = false # one shortened `⏺ Tool(summary)` line eachThe app always receives readable reasoning, marked as thinking, and the tool call lines; each device’s Show Thinking and Show Tool Calls settings show or hide them.
-
Progress is the agent’s todo list, from its harness’s todo tool (omp and Claude) or
vendetta agent plan(any agent). When the agent makes a plan, the chat gets it once in full,Progress 0/5and each item; each change after that posts one short line, such asProgress 2/5 · ✓ Fix login · ▶ Tests · + Docs, edited in place while it is the newest message. Items can link to the agent or reply doing them and to the change holding their work. These messages notify no one. In the app, the bar above the message box shows the plan while the agent has one, done, total, and the item in progress; tap it for every item, and reply to an item as to a message. Finished calls are not kept. -
Questions from omp, Claude, and OpenCode appear as buttons, with multi-select, custom answers, and cancel. For a custom answer, use Reply on the bot’s prompt. A receipt confirms what was accepted. Answering locally removes the buttons. Permission dialogs are never offered remotely.
-
Photos: JPEG, PNG, and WebP images up to 8 MiB each:
- omp and OpenCode receive them natively;
- other providers get a private file path.
An album or reply-to-image batch is at most 10 images and 16 MiB, submitted in order. If any image fails, none is sent.
-
Files arrive as private file paths with their caption, kept in a private cache for a day: up to 20 MiB from Telegram, whose Bot API downloads no more (send uncompressed for originals, such as HEIC), and up to 256 MiB from the app, which uploads larger files and videos in resumable pieces. Videos from the app also play in the chat.
-
Discord takes one image per message and no other files.
-
Images from agents: final-answer images, tool screenshots, and local image links are sent to the topic.
-
Voice: with transcription enabled, a voice note becomes a prompt. After the agent accepts it, the transcript is posted back. Replying to a voice note includes its transcript as context. A note longer than the plugin’s
voice.max_seconds(15 minutes by default) is cut there: its first part is sent, and a notice says how much. While a note is transcribed your other chats go on, and what you send after it in the same chat follows it. -
A voice note that fails before it reached the agent (transcription, a download, or the agent starting a question meanwhile) is told in the chat. On Telegram and Discord the notice has a Retry button for an hour, until the plugin restarts, that fetches and transcribes the same note again; the app keeps the recording on the device and offers to send it again. A note over 20 MB on Telegram cannot be fetched and gets no Retry.
-
Replying to an earlier text message, yours or the agent’s, sends up to 2,000 characters of it (on Telegram, just the part you quote) as quoted context before your message. Replying to a question’s prompt answers it instead.
-
Links to other agents: an agent can link another agent’s chat, or one of its replies, as
vendetta://conversation/…(thevendettaskill tells it how). The app opens them in place. Discord links to that channel or reply message; otherwise the link goes to the web client when[plugins.app] public_urlis set, and is shown as its label alone without it.
Muted agents keep their topics current, but nothing they send makes a sound:
Telegram delivers silently, Discord suppresses notifications, and the app sends no
push and leaves them out of its badge. Their alerts still sound. Agents a manager
starts are muted, and the manager tells you what matters. The manager’s own turns
that its team’s updates start go the same way, reply and progress, unless it flags
one for you; their questions and approvals still notify. /mute and /unmute in
an agent’s topic change it, as do vendetta agent mute and the chooser.
Input is refused while the agent has a pending question or approval, is in an unknown state, or has been replaced by a new process. A refused message is never replayed later; send it again.
Voice transcription uses the speech plugin’s transcription.
Without [plugins.speech.transcription], voice notes are refused, unless this is a person’s
Vendetta that takes the admin’s services (voice for people).
[plugins.telegram.voice] # and the same in [plugins.discord] and [plugins.app]
max_seconds = 900 # 60–1800: one voice note, or all of an app send's voiceStopping and deleting
Section titled “Stopping and deleting”/stop, crashes, and the idle timeout keep the conversation and topic. A new message restores the conversation./delete(after Yes, delete on Telegram and in the app) orx/Xin the chooser (after you confirm) SIGTERMs the exact agent once. After it has exited, its topic is deleted. The chooser’s confirmation lists every affected conversation and topic.- A deleted conversation you resume later, from a terminal or the history, gets a new topic and app chat; the deleted ones never come back.
- With
[auto_delete]on, a conversation stopped longer than itsafteris deleted the same way, topic and app chat included, unless it is kept (/keep,vendetta agent keep, the chooser, or the apps’ Keep). Its files stay. - An ephemeral conversation is stopped and deleted the same way once idle for
[auto_delete] ephemeral_after(30 minutes by default), auto-delete on or not. - Deleting a topic in Telegram itself does not stop the agent, because the Bot API reports no such event.
Uncertain operations
Section titled “Uncertain operations”Telegram and Discord can lose a response. When Vendetta can’t tell whether something happened (a prompt, launch, stop, deletion, or reply), it never repeats it:
- The affected conversation pauses.
- On Telegram and in the app, after 15 minutes the operation is retired with a notice asking you to check the agent terminal. An uncertain reply is dropped without one.
- An uncertain deletion counts as done.
- An unconfirmed tool image is skipped at once, so the final answer still arrives.
- A send the platform refuses is not uncertain: a rate-limited reply waits and is sent later; any other refused part is skipped. The journal names the reason.
To retire a Telegram one sooner, stop the worker, then:
vendetta telegram recovery list
vendetta telegram recovery retire --checkpoint BASENAME --revision REVISION \
--operation OPERATION --without-replayCheckpoints in ~/.local/state/vendetta/notifications/ hold IDs, cursors, and
receipts, never credentials, prompts, or replies. Don’t delete them to force a
retry.
worker.log records each message’s handling as messaging_delivery lines with IDs
and fixed categories, never content; a rejected line’s reason says why, such as
question_open or worker_not_running. Bot chats are not end-to-end encrypted.