| name | send-message |
| description | user wants to send a text message on Telegram as their personal account via MTProto, text someone, or message a contact by username, phone, or. |
| allowed-tools | Bash, Read, Grep, Glob |
Send Telegram Message
Send a message from your personal Telegram account (not a bot) via MTProto.
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
Preflight
Before sending, verify the session is authorized (not just that the file exists):
bun "$SCRIPT" check-auth
If EXPIRED, run /tlg:setup first (uses 3-step non-interactive auth pattern).
Supergroup-First Methodology
The Bruntwork group (-1003958083153) is a supergroup with Topics. All messages to this group MUST target a specific topic — never post to the bare supergroup without a topic target.
Why supergroup over basic chat:
- Server-global message IDs. Every member sees the same
id=N for each message. Both sides' Claude Code resolves citations identically — no viewer-qualifier needed, no cross-boundary ambiguity.
- Topic namespaces. Policies don't get buried between daily check-ins. Each subject has its own searchable thread with independent pins.
- AI-agent addressability. Claude Code can target reads/writes to specific topics via
reply_to_msg_id, enabling precise routing: "post this bug report to Bug Reports" or "search Policies for the carve-out decision."
- Emoji reactions as acknowledgment signals. Reactions are programmatically readable via
message.reactions.results — enables lightweight ACK checking without requiring a text reply.
Topic selection discipline: When composing a message, select the most specific topic from the Topic Registry below. Use General only as a fallback. Never cross-post the same message to multiple topics.
Citation convention: Bare id=N citations resolve identically for every member. When referencing a prior message, cite its ID. Claude Code on both sides can look it up autonomously via client.get_messages(supergroup_id, ids=N).
Sending to a topic via tg-cli.ts: use the --reply-to flag with the topic's root_msg_id. See the Topic Registry section below for root_msg_id values.
bun "$SCRIPT" send --html --reply-to 5 -1003958083153 "<b>Policy update</b> ..."
Auto-split for long messages
Telegram's hard limit is 4096 post-parsing chars per message. tg-cli.ts send and draft both auto-split messages exceeding ~3900 plain chars into multiple sequential posts, preserving HTML formatting and section structure.
Split algorithm: splits at the finest-grained safe boundary that fits all chunks:
\n\n━━━━━━━━━━━━━━\n\n (major section separator, preferred)\n━━━━━━━━━━━━━━\n (section separator)\n\n (paragraph break)\n (line break)- Hard character split (last resort — prints warning; may break tags)
Each continuation chunk gets a <i>(Part N/M)</i> header prepended so recipients see the sequence clearly. All parts share the same --reply-to target so a multi-part post stays in one topic thread.
You do NOT need to manually split messages anymore. Compose the full HTML as one string, pass to send, and the splitter handles it.
Size-aware authoring guidance: prefer messages that fit in one post (≤ 3900 plain chars) — splits add visual overhead with part headers. If a message is naturally larger (e.g., a pinned reference), let the splitter do its job. Structure with ━━━━━━━━━━━━━━ separators so split boundaries land cleanly between logical sections.
Usage: tg-cli.ts (when session is valid)
When in doubt, USE --html. If your message contains ANY of: <b>, <i>, <code>, <pre>, <a href>, bold headers, inline code, or markdown-style **bold** / `code`, you MUST either pass --html (and translate markdown → HTML tags first) or strip the decoration. Sending Telegram-style markdown without --html renders the asterisks and backticks literally to the recipient. For multi-section messages with headers, separators, and code spans — always use --html.
Recovery pattern when you've already sent a mangled message: send a follow-up prefixed Correction — earlier message rendered as raw text, corrected version below: then the correctly-HTML-formatted content. Do NOT silently edit if the message has been read (see "Editing Discipline" below).
/usr/bin/env bash << 'SEND_EOF'
ROOT="$(cc-plugin-root tlg)"
SCRIPT="$ROOT/scripts/tg-cli.ts"
bun "$SCRIPT" send @username "Hello"
bun "$SCRIPT" send --html -1003958083153 "<b>Bold header</b>
Body with <code>inline code</code> and <a href='https://example.com'>a link</a>."
bun "$SCRIPT" send -1003958083153 "Hello group"
bun "$SCRIPT" -p missterryli send @username "Hello"
bun "$SCRIPT" edit -1003958083153 12345 "<b>Updated text</b>"
bun "$SCRIPT" delete -1003958083153 12345
SEND_EOF
Long HTML messages: tg-cli.ts send --html auto-splits at the 3900-plain-char threshold. Compose the full HTML as one string and let the splitter handle it. See "Auto-split for long messages" above.
Editing Discipline — unread vs. read
The core principle: edit silently only when you are confident the recipient has NOT read the message yet. Once someone has seen a message, editing it risks creating a false record and confusing them (they remember the original text; the chat now shows different text).
| Situation | Action |
|---|
| You sent a message <30s ago in an active async chat and nobody has touched Telegram since | Edit is safe — iterate freely |
| You just sent a message with a typo or factual error and the recipient has not responded | Edit is safe — they likely have not read it yet |
| The recipient has replied to your message | Do NOT edit silently — send a supplement |
| The recipient has read the message but not yet replied (you see read receipts or their typing indicator came/went) | Do NOT edit silently — send a supplement |
| You're not sure whether the recipient has read it | Default to supplement — safer than confusing them |
| The message has been cited or quoted by others in the chat | Do NOT edit — the citation is now stale context; supplement instead |
Supplement pattern (when edit is unsafe):
Correction on my previous message: <specific change>
or
Update to what I said above: <new info that supersedes>
Make the supplement self-contained so a reader scrolling back understands without having to cross-reference.
Why this matters: silent edits of read messages are one of the most confusing UX anti-patterns in chat systems. The recipient remembers "Terry told me X", sees "X'" now, and wonders if their memory is wrong or if they're being gaslit. Edits are a privilege to use before observation, not to rewrite history.
How to tell if it's been read: Telegram's MTProto exposes read receipts in 1:1 and small group chats via messages.readHistoryOutbox updates, but in large groups this is unreliable. The safest heuristic is time + activity: if more than ~60 seconds have elapsed and/or the recipient has been active in the chat, assume they saw it.
Telegram HTML Formatting Reference
GramJS uses HTML, not Markdown:
| Tag | Renders As |
|---|
<b>text</b> | Bold |
<i>text</i> | Italic |
<u>text</u> | Underline |
<s>text</s> | Strikethrough |
<code>text</code> | Inline code |
<pre>text</pre> | Code block |
<a href="url">text</a> | Hyperlink |
<tg-spoiler>text</tg-spoiler> | Spoiler |
Horizontal separator rules (enforced convention)
Use ━ (U+2501) for horizontal rules between sections in long messages.
Length rule: 14 characters preferred, 22 characters absolute maximum.
- Preferred:
━━━━━━━━━━━━━━ (14 × ━)
- Acceptable ceiling:
━━━━━━━━━━━━━━━━━━━━━━ (22 × ━, = 14 + 8)
- Never exceed 22 characters — longer separators look visually unbalanced on mobile clients and push body content off-screen.
Rationale: Telegram's mobile client reflows body text but does NOT wrap separator lines of box-drawing characters. A 28-char separator forces horizontal scrolling on narrow phones; 14 char fits cleanly in every viewport and still reads as a clear section break. If you need more visual weight, use a heading (<b>...</b>) above the separator rather than making the separator longer.
Emojis are supported but user may prefer decorations without emojis — use <pre> blocks and box-drawing characters instead.
Profiles
| Profile | Account | User ID |
|---|
eon (default) | @EonLabsOperations | 90417581 |
missterryli | @missterryli | 2124832490 |
Known Group Chat IDs
| Group | Chat ID | Type |
|---|
| Terry & MD (Bruntwork) | -1003958083153 | Supergroup |
| Terry & MD (Bruntwork) | -1003958083153 | Legacy basic chat (pre-2026-04-16, read-only for old messages) |
Topic Registry (Bruntwork Supergroup)
To send a message to a specific topic, pass reply_to=<root_msg_id> in send_message() or use --reply-to in tg-cli.ts.
| Topic | root_msg_id | Scope |
|---|
| General | 1 | Catch-all, quick questions |
| Assignments & Deliverables | 2 | Task definitions, PR reviews, Block check-ins |
| Daily Operations | 3 | Commencement/disembarkation, shift status |
| Onboarding & Access | 4 | Repo access, SSH/Tailscale, tool provisioning |
| Policy & Standards | 5 | cc-skills carve-out, conventions, discipline |
| Bug Reports & Incidents | 6 | Merge conflicts, hook bugs, pipeline breaks |
| Tool Setup & Config | 7 | ccmax-monitor, FlowSurface, chronicle pipeline |
| Knowledge Base & Learning | 8 | KB pages, research material, skill references |
| HR & Scheduling | 9 | Shift hours, Bruntwork coordination |
| Session Monitor | 185 | Real-time Claude Code session summaries (CC Nasim Bot) |
Anti-Patterns (NEVER DO)
| Anti-Pattern | Why It Fails |
|---|
Running bun "$SCRIPT" without checking auth first | If session expired, auth will fail |
| Checking only session file existence in preflight | Session file can exist but be expired — must check with check-auth |
| Using plain text for formatted messages | GramJS uses HTML, not Markdown. Use --html flag for formatting |
Error Handling
| Error | Cause | Fix |
|---|
Unknown profile | Invalid -p value | Use eon or missterryli |
Cannot find any entity | Bad username/ID | Verify with dialogs command or use find-user to resolve |
message cannot be empty | Empty string passed | Provide message text |
Session expired | Session no longer valid | Run /tlg:setup to re-authenticate non-interactively |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If tg-cli.ts's interface drifted, update Usage examples and Parameters table to match.
- Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.
