reply-conventions

name	reply-conventions
description	Use whenever you need to send anything to the user from a supermux session — establishes that all user-facing words go through the supermux reply tool, and the per-channel rules (Telegram vs web).

Replying as a supermux session

You are running inside supermux: a broker connecting the user's chat client(s) to many agent sessions on this machine. You are ONE session. The broker routes the user's inbound messages to you and relays your replies back to their chat client — your terminal/transcript output never reaches them.

How replies reach the user (differs per agent)

• Claude Code sessions: every user-facing word MUST go through the mcp__mux-shim__reply tool. Text written only to your transcript or tmux pane is invisible.
• Cursor and Codex sessions: you do NOT call a reply tool. Your normal assistant response is the message — the broker captures it and relays it to the user. Just respond normally.

Either way the rule below is the same: nothing reaches the user unless it goes out as a proper reply (the tool for Claude, your normal response for Cursor/Codex). Terminal-only output never reaches them.

The one rule that matters

Everything the user should see must leave the session as a reply — via the mcp__mux-shim__reply tool (Claude) or your normal assistant turn (Cursor/Codex). The user reads it on their phone or web client, not in your terminal.

• reply(chat_id, text, …) — send a message. Push-notifies. Your primary output.
• Each inbound message carries chat_id and message_id in its meta. Pass that same chat_id back when replying.
• Don't reply to empty inbounds. Genuine internal scratch work needs no reply.
• Long replies (200+ words) are fine. Don't dump whole files; summarize and offer to send the full content on request.

Which channel am I on? (the chat_id prefix tells you)

• telegram:… — Telegram. Reactions, message edits, attachments, and voice are supported. You may format with markdownv2. One Telegram chat is multiplexed across sessions — exactly one session is "active" at a time.
• web:… — Web PWA. Reactions and edits are NOT supported — do not call react / edit_message. Attachments ARE supported. Markdown renders in the app, so do NOT use markdownv2. Every session is its own separate chat.

Side-effect tools (mux-shim)

• react / edit_message — message side-effects (Telegram only).
• download_attachment — fetch a file the user sent; returns a local path.

(Orchestration tools like spawn_session / set_active / expose_port are described in your environment instructions.)