Skip to main content
Reference Last updated: 16 November 2026

Commands & directives

Nathan Schram
By Founder, Little Bear Apps

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.

DirectiveExampleEffect
/<engine-id>/codex fix flaky testSelect an engine for this message.
/<project-alias>/happy-gadgets add escape-podSelect a project alias.
@branch@feat/happy-camera rewind to checkpointRun in a worktree for the branch.
Combined/happy-gadgets @feat/flower-pin observe unseenProject + 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.

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

CommandDescription
/cancelReply to the progress message to stop the current run. Without a reply it stops the single active run (or queued job), else cancels pending /at delays and loops — in a forum topic only that topic’s, in General only General’s (#826). A Claude session idling after its answer isn’t a run: /cancel closes it, still cancels the pending /at delays and loops, and always replies (#902). Also drops a prompt still waiting in the forward-coalesce window with a 🗑️ Dropped N message(s) … reply (#807). A run whose card still reads queued or starting counts as running: it is cancelled before the engine starts (#1082). Cancelling a chat’s first run before it has started its conversation also drops a message waiting on it, with the same 🗑️ Dropped … reply (#1157).
/agentShow/set the default engine for the current scope.
/modelShow/set the model override for the current scope.
/reasoningShow/set the reasoning override for the current scope.
/listenShow/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 still works as a deprecated alias.
/steer <text>Send <text> straight into the running Claude Code turn — Claude picks it up at its next tool step and folds it into the answer it is already working on (or, after its last tool call, answers it as the next turn, replying to your message). Replies ↪️ Steered into the current run.; the run’s progress shows ↪️ steer received: … once Claude has read it. Bare /steer makes steer the default for this chat (or forum topic). Works on Claude Code while a live session is running (a permission mode is set), and on Antigravity CLI while an agy run is working, with Untether’s agy plugin installed on the host (#981); otherwise the message queues and you get ↪️ … — queued instead. See steer follow-ups (#775).
/queue <text>Send <text> as a normal queued follow-up — it waits until the running turn ends — even when the default is steer. Bare /queue makes queue (the built-in default) the default for this chat or topic.
/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> @branchCreate/bind a topic (topics enabled).
/ctxShow context binding (chat or topic).
/ctx set <project> @branchUpdate context binding.
/ctx clearRemove context binding.
/planmodeToggle Claude Code permission mode (on/plan-auto/auto/off/show/clear). plan-auto is plan mode with the plan gate auto-approved; auto is Claude Code’s own classifier-gated mode. In an Antigravity chat on picks Plan first, off goes back to Workspace, and show / clear / the bare toggle work too; plan-auto and auto are Claude-only (#981). Codex chats are pointed to /config → Approval policy (Gemini’s page is called Approval mode). In a forum topic it still sets the whole chat’s mode. In a group, every form except show needs a group admin (#1042).
/usageClaude Code: show subscription usage (5h window, weekly, per-model). Antigravity: agy’s own quota groups, fetched on demand (cached 60 s), and remaining AI credits (#979), then the last session’s tokens; /usage debug adds cache age, last error and the agy version (#558). Other engines (Codex, OpenCode, …): token totals for the chat’s last session of that engine — session total, last run, run count and cost where reported; quota limits aren’t available from those CLIs (#417). The Claude view 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).
/exportExport the chat’s most recently active session transcript as a Markdown or JSON file (/export json), attached as a document with a one-line summary caption (#417, #418). The usage header says whether it’s the last run’s figure or the thread total (Codex; Antigravity labels its last-run duration and thread-total tokens separately) (#859, #1158).
/browseBrowse project files with inline keyboard navigation (needs a project: the chat’s or topic’s /ctx binding, then the chat’s project, then default_project; respects files.deny_globs and hides dotfiles except .github/.gitignore).
/pingHealth check — replies with uptime since last (re)start. Shows a trigger summary if triggers target the current chat (⏸ triggers paused while paused), and ⏳ background: N tasks running while a live Claude Code session, or a running Antigravity turn, holds background tasks (#777, #978).
/healthSystem + triggers + cost snapshot — RAM/swap, Untether process (PID, RSS, FDs, children), trigger counts, today’s API cost, uptime. Compact HTML message (a header and up to seven lines); sections degrade gracefully when sources are unavailable. See operations.
/restartGracefully drain active runs and restart Untether.
/verboseToggle verbose progress mode (on/off/clear). Shows tool details in progress messages. In a group it needs a group admin (#1042).
/configInteractive settings menu — permission mode (titled Permission mode since #741), ask mode, verbose, engine, model, reasoning, listen-mode and follow-up-mode (Claude Code, and Antigravity CLI with Untether’s agy plugin: queue / steer, #775) toggles with inline buttons. In an Antigravity chat the Permission mode page offers Workspace, Full access, Ask me and Plan first, and 🔐 Telegram approvals shows whether Untether’s agy plugin is installed and loaded for the chat’s project (#980). 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); the home page links to it with a ⏰ Triggers button whenever [triggers] is enabled (#296). Each page’s ”📖 Learn more” link opens the matching help-centre article. In a group, changing a setting needs a group admin (#1042).
/statsPer-engine session statistics — runs, actions, duration and last run for one period: today (default), week or all (e.g. /stats week). 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). /stats auth shows each engine CLI’s auth status instead; for Antigravity it shows only the sign-in route agy is set to use (Google sign-in, Gemini API key or Enterprise ADC), from what an earlier run cached, without starting agy or checking that the sign-in still works (#979).
/auth/auth codex — headless device re-authentication for Codex: runs codex login --device-auth and sends the verification URL + device code. Bare /auth (or any other engine) shows a short help text. Codex-only; for each engine’s auth status use /stats auth.
/newCancel any running task and clear stored sessions for the current scope (topic/chat). A prompt still waiting in the forward-coalesce window is dropped with a notice rather than carried into the new session (#807), and so is a message waiting on a first run that hasn’t started its conversation yet (#1157). When the only thing open was Claude’s idle live session after an answer, the reply says 🧹 closed the idle session and cleared … instead of cancelled run (#895).
/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.
/threads [search <query>]List, view, resume or archive AMP threads via inline buttons. AMP-only — deprecated and no longer supported, together with the AMP engine (#458).
/at <duration> <prompt>Schedule a one-shot delayed run. Duration: Ns, Nm or Nh, between 60 s and 24 h. The engine and context a plain message would use are captured at schedule time and used at fire time (mirrors cron freeze-at-dispatch behaviour): the topic’s or chat’s /agent default, then the default of the /ctx-bound (or the chat’s) project, then the global default (#950). 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. In a forum supergroup (and a private chat with topics) it only cancels the runs and loops of the topic it was sent in; /new in General leaves topic runs alone. Non-forum groups stay chat-wide (#826).
  • A message that starts with a dot instead of a slash and names a command (.new, .cancel) isn’t sent to the agent: Untether replies Did you mean `/new`? … so you can resend it (#523).
  • /continue uses the engine’s native “continue” flag: --continue (Claude, OpenCode, Pi), resume --last (Codex), or --resume latest (Gemini, deprecated). For Antigravity, Untether resumes the last conversation run from this exact project directory by id, because agy’s --continue can also pick one from a parent or child directory (#1039).
  • /compact isn’t an Untether command. In an Antigravity chat Untether passes it to agy’s own /compact (agy 1.3.5 or newer) and replies 🗜️ Context compacted (manual); /compact <message> compacts, then answers the message. With no conversation yet (or after /new) Untether says there is nothing to compact and starts nothing. Sent while a run is working, it waits for that run to end and is never steered. It is the only agy slash command passed through: anything else starting with / reaches the model as text (#1114; see Compact the conversation).
  • 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. With Loop mode on, Untether declines Claude’s own CronCreate and runs the schedule itself, firing each iteration with claude --resume; with it off, Claude can’t schedule recurring or timed tasks and points you to Loop mode or /at (#925). Self-paced ScheduleWakeup chains stop after [loop] max_iterations in both modes. Off by default; opt in per chat via /config → 🔁 Loop mode. Cost alerts come from [cost_budget] (checked after each fire), runaway-safety caps from [loop] (#289).

CLI

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

Commands

CommandDescription
untetherStart 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 pathPrint the resolved config file path.
untether config listList config keys as flattened dot-paths.
untether config get <key>Fetch a single config key (dot-path).
untether config set <key> <value>Set a config value (value is auto-parsed).
untether config unset <key>Remove a config key.
untether init <alias>Register the current repo as a project (--default also sets it as default_project).
untether chat-idCapture the current chat id.
untether chat-id --project <alias>Save the captured chat id to a project.
untether doctorRun configuration checks for the active transport (Telegram connectivity, file transfer, voice).
untether onboarding-pathsPrint all possible onboarding paths.
untether pluginsList discovered plugins without loading them.
untether plugins --loadLoad each plugin to validate types and surface import errors.
untether agy-gate installInstall Untether’s agy plugin on this host through agy plugin install (approval buttons in Ask me, question buttons and steer for Antigravity). --wait-s <s> sets how long a question or approval waits (default 900), --force replaces a plugin folder Untether didn’t install or that was edited, --dry-run prints the files without writing, --agy <path> names the agy binary (default: [antigravity] cmd, then agy on PATH, then ~/.local/bin/agy) (#980).
untether agy-gate statusShow whether the plugin is installed and current. --project <dir> also runs agy’s own -p /hooks check there (no model turn); --canary sends one trivial agy turn to check the hooks reach Untether. --agy <path> as for install. Exits 1 when not ready.
untether agy-gate uninstallRemove the plugin with agy plugin uninstall (--force even if Untether didn’t install it; --agy <path> as for install).

Common flags

FlagDescription
--versionShow the version and exit.
--onboardForce the interactive setup wizard before starting.
--transport <id>Override the configured transport backend id.
--debugLog engine JSONL, Telegram requests and rendered messages (to debug.log unless a log file is already set).
--final-notify/--no-final-notifySend the final response as a new message vs an edit.
Was this helpful?

Related Articles