Commands & directives

This page documents Untether’s user-visible command surface: message directives, in-chat commands, and the CLI.

Message directives

Untether parses the first non-empty line of a message for a directive prefix.

Directive	Example	Effect
/<engine-id>	/codex fix flaky test	Select an engine for this message.
/<project-alias>	/happy-gadgets add escape-pod	Select a project alias.
@branch	@feat/happy-camera rewind to checkpoint	Run in a worktree for the branch.
Combined	/happy-gadgets @feat/flower-pin observe unseen	Project + branch.

Notes:

• Directives are only parsed at the start of the first non-empty line.
• Parsing stops at the first non-directive token.
• If a reply contains a dir: line, Untether ignores new directives and uses the reply context.

See Context resolution for the full rules.

Context footer (dir:)

When a run has project context, Untether appends a footer line as part of the 🏷 info line:

• With branch: dir: <project> @<branch>
• Without branch: dir: <project>

This line is parsed from replies and takes precedence over new directives. For backwards compatibility, Untether also accepts the older ctx: format when parsing replies.

Telegram in-chat commands

Command	Description
/cancel	Reply to the progress message to stop the current run.
/agent	Show/set the default engine for the current scope.
/model	Show/set the model override for the current scope.
/reasoning	Show/set the reasoning override for the current scope.
/listen	Show/set listen mode (all / mentions / clear) — controls whether the bot responds to every message in a group chat or only to @-mentions. Renamed from /trigger in v0.35.3 (#297); /trigger continues to work as a deprecated alias for one release cycle.
/file put <path>	Upload a document into the repo/worktree (requires file transfer enabled).
/file get <path>	Fetch a file or directory back into Telegram. Agents can also send files automatically via .untether-outbox/ — see file transfer.
/topic <project> @branch	Create/bind a topic (topics enabled).
/ctx	Show context binding (chat or topic).
/ctx set <project> @branch	Update context binding.
/ctx clear	Remove context binding.
/planmode	Toggle Claude Code plan mode (on/auto/off/show/clear). Claude Code only — non-Claude engines are directed to /config → Approval policy.
/usage	Show Claude Code subscription usage (5h window, weekly, per-model). Claude Code only. Requires Claude Code OAuth credentials (see troubleshooting). /usage debug appends a 🔧 debug block with last-fetch wall time and freshness label, last-error class+message, OAuth token expiry, and the cumulative claude_usage.schema_mismatch counter (#410).
/export	Export last session transcript as Markdown or JSON.
/browse	Browse project files with inline keyboard navigation.
/ping	Health check — replies with uptime since last (re)start. Shows trigger summary if triggers target the current chat.
/health	System + triggers + cost snapshot — RAM/swap, Untether process (PID, RSS, FDs, children), trigger counts, today's API cost, uptime. Compact 6-line HTML message; sections degrade gracefully when sources are unavailable. See operations.
/restart	Gracefully drain active runs and restart Untether.
/verbose	Toggle verbose progress mode (on/off/clear). Shows tool details in progress messages.
/config	Interactive settings menu — plan mode, ask mode, verbose, engine, model, reasoning, listen-mode toggles with inline buttons. The 📡 Triggers page (config:tg) lists per-chat crons (describe_cron(...) schedule, project, engine, last-fired) and webhooks (path, auth, project, engine, last-fired), capped at 10 entries with an overflow marker, plus a master pause/resume toggle (#271, #294).
/stats	Per-engine session statistics — runs, actions, and duration for today, this week, and all time. Includes (N triggered, M manual) per-engine breakdown when at least one count is nonzero (#271 Tier 3). Pass an engine name to filter (e.g. /stats claude).
/auth	Headless device re-authentication for Codex — runs codex login --device-auth and sends the verification URL + device code. /auth status checks CLI availability. Codex-only.
/new	Cancel any running task and clear stored sessions for the current scope (topic/chat).
/continue [prompt]	Resume the most recent session in the project directory. Picks up CLI-started sessions from Telegram. Optional prompt appended. Not supported for AMP.
/at <duration> <prompt>	Schedule a one-shot delayed run. Duration: Ns (60-9999s), Nm, or Nh (up to 24h). The chat's project mapping and engine are captured at schedule time and used at fire time (mirrors cron freeze-at-dispatch behaviour). Pending delays are cancelled via /cancel and lost on restart. Per-chat cap of 20 pending delays. Trigger-source provenance is stamped as at:<token> and rendered in the run footer (⏰ at:<token>), and the run counts toward /stats as triggered (#271 follow-up).

Notes:

• Outside topics, /ctx binds the chat context.
• In topics, /ctx binds the topic context.
• /new cancels running tasks and clears sessions but does not clear a bound context.
• /continue uses the engine's native "continue" flag: --continue (Claude, OpenCode, Pi), resume --last (Codex), or --resume latest (Gemini).
• Long-running tools (Bash, BashOutput, ScheduleWakeup, Monitor, …) surface a heartbeat-driven elapsed-time tail (▸ Bash · 3m 47s · npm run build) on the progress message after ~60s, regardless of /verbose state (#481). Tune via [progress] heartbeat_interval.
• Loop mode (Claude only): there is no /loop Telegram command — it's a Claude Code feature. Untether observes Claude's ScheduleWakeup and CronCreate tool calls and re-fires iterations after the subprocess exits. Off by default; opt in per chat via /config → 🔁 Loop mode. Cost protection lives in [cost_budget], runaway-safety caps in [loop] (#289).

CLI

Untether’s CLI is an auto-router by default; engine subcommands override the default engine.

Commands

Command	Description
untether	Start Untether (runs onboarding if setup/config is missing and you’re in a TTY).
untether <engine>	Run with a specific engine (e.g. untether codex).
untether config	Show config file path and content.
untether init <alias>	Register the current repo as a project.
untether chat-id	Capture the current chat id.
untether chat-id --project <alias>	Save the captured chat id to a project.
untether doctor	Validate Telegram connectivity and related config.
untether plugins	List discovered plugins without loading them.
untether plugins --load	Load each plugin to validate types and surface import errors.

Common flags

Flag	Description
--onboard	Force the interactive setup wizard before starting.
--transport <id>	Override the configured transport backend id.
--debug	Write debug logs to debug.log.
--final-notify/--no-final-notify	Send the final response as a new message vs an edit.