Agent preamble

Untether injects a context preamble at the start of the prompt for every new run (including a resumed session), telling the engine it’s running via Telegram and requesting structured end-of-task summaries. Follow-ups and steers sent into a Claude session that is still open don’t repeat it; the session already has it. This works across all engines (Claude Code, Codex, OpenCode, Pi, and the deprecated Gemini CLI and Amp).

What the default preamble does#

The built-in preamble tells the agent:

1. Context — it’s running via Untether on Telegram, and the user is on a mobile device
2. Visibility constraints — only final assistant text is visible; tool calls, thinking blocks, and terminal output are invisible to the user
3. Summary format — every response that completes work should end with a short structured summary (about 500–1,500 characters) including “Completed”, “Next Steps”, and “Decisions Needed” sections, plus how to send files back through .untether-outbox/ (this part is included even when [transports.telegram.files] enabled = false; use a custom text if you don’t want it)
4. Config changes — Untether hot-reloads untether.toml, so the agent must not restart the Untether service after editing it (a restart from inside the session drops its own final answer)
5. Plan mode — the ExitPlanMode plan should be a 3–5 bullet summary, and the reply after approval a brief summary rather than a re-paste of the plan

This means agents naturally produce mobile-friendly summaries instead of expecting the user to read terminal output or file diffs.

Disable the preamble#

If you don’t want Untether to inject any preamble:

toml

[preamble]
enabled = false

Customise the preamble#

Replace the default text with your own:

toml

[preamble]
enabled = true
text = "You are running via Telegram. Keep responses concise and use bullet points."

Set text to your custom string. When text is null (the default), Untether uses the built-in preamble. Setting text to an empty string ("") effectively disables the preamble while keeping the enabled flag on.

Configuration reference#

Ask mode interaction#

Untether appends one more line to the preamble, the built-in one or your own text. Unless ask mode is turned off in /config, the line encourages the agent to use AskUserQuestion with structured options; with ask mode off it tells the agent not to ask and to proceed with defaults instead. The line is added for every engine, although only Claude Code turns those questions into buttons.

Hook awareness#

Claude Code plugins can install hooks that fire at session end (Stop hooks). In a terminal, these are harmless — the user can scroll up. But in Telegram, only the final assistant message is visible. If a Stop hook causes Claude to spend its final response addressing hook concerns, the user’s actual content is lost.

Untether addresses this in two ways:

1. Preamble guidance — the default preamble includes: “If hooks fire at session end, your final response MUST still contain the user’s requested content. Hook concerns are secondary.”

2. UNTETHER_SESSION env var — the Claude runner sets UNTETHER_SESSION=1 in the subprocess environment. Well-behaved Claude Code plugins check for this variable and skip blocking hooks in Telegram sessions. For example, PitchDocs context-guard detects $UNTETHER_SESSION and allows the session to stop without blocking.

For plugin authors

If your Claude Code plugin includes Stop hooks, add an early exit for Untether sessions:

# Skip blocking in Untether sessions — Stop hook blocks displace
# user-requested content in the Telegram final message.
[ -n "${UNTETHER_SESSION:-}" ] && echo '{}' && exit 0

This is not a security bypass — it simply prevents your hook from interfering with Telegram’s single-message output model. See the interference audit for a detailed case study.

Related#

• Configuration reference — full [preamble] config
• Inline settings — /config toggles including ask mode
• Environment variables — UNTETHER_SESSION and other env vars