Commands & directives
This page documents Untether’s user-visible command surface: message directives, in-chat commands, and the CLI.
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. 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). |
/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 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> @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 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). |
/usage | Claude 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). |
/export | Export 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). |
/browse | Browse 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). |
/ping | Health 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). |
/health | System + 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. |
/restart | Gracefully drain active runs and restart Untether. |
/verbose | Toggle verbose progress mode (on/off/clear). Shows tool details in progress messages. In a group it needs a group admin (#1042). |
/config | Interactive 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). |
/stats | Per-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. |
/new | Cancel 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,
/ctxbinds the chat context. - In topics,
/ctxbinds the topic context. /newcancels 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;/newin 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 repliesDid you mean `/new`? …so you can resend it (#523). /continueuses 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--continuecan also pick one from a parent or child directory (#1039)./compactisn’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/verbosestate (#481). Tune via[progress] heartbeat_interval. - Loop mode (Claude only): there is no
/loopTelegram command — it’s a Claude Code feature. With Loop mode on, Untether declines Claude’s ownCronCreateand runs the schedule itself, firing each iteration withclaude --resume; with it off, Claude can’t schedule recurring or timed tasks and points you to Loop mode or/at(#925). Self-pacedScheduleWakeupchains stop after[loop] max_iterationsin 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
| 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 path | Print the resolved config file path. |
untether config list | List 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-id | Capture the current chat id. |
untether chat-id --project <alias> | Save the captured chat id to a project. |
untether doctor | Run configuration checks for the active transport (Telegram connectivity, file transfer, voice). |
untether onboarding-paths | Print all possible onboarding paths. |
untether plugins | List discovered plugins without loading them. |
untether plugins --load | Load each plugin to validate types and surface import errors. |
untether agy-gate install | Install 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 status | Show 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 uninstall | Remove the plugin with agy plugin uninstall (--force even if Untether didn’t install it; --agy <path> as for install). |
Common flags
| Flag | Description |
|---|---|
--version | Show the version and exit. |
--onboard | Force the interactive setup wizard before starting. |
--transport <id> | Override the configured transport backend id. |
--debug | Log engine JSONL, Telegram requests and rendered messages (to debug.log unless a log file is already set). |
--final-notify/--no-final-notify | Send the final response as a new message vs an edit. |