This tutorial walks you through sending your first task, watching it execute, and learning the core interaction patterns. Your agent runs on your machine; yo...

This tutorial walks you through sending your first task, watching it execute, and learning the core interaction patterns. Your agent runs on your machine; you control it from Telegram on whatever device is in your hand.

What you’ll learn: How Untether streams progress, how to continue conversations, and how to cancel a run.

1. Start Untether in a repo

Untether runs agent CLIs in your current directory. Navigate to a repo you want to work in:

cd ~/dev/your-project
untether

Untether keeps running in your terminal. In Telegram, your bot will post a startup message like:

Untether 🐕 untether v0.34.0 is ready

engine: `codex` · projects: `3`<br>
working in: /Users/you/dev/your-project

The message is compact by default — diagnostic lines only appear when they carry signal (e.g. mode: chat when in chat mode, or engine issues). This tells you:

Which engine is the default and how many projects are registered
Which directory Untether will run in
Any engine issues (missing, misconfigured) when relevant

Untether runs where you start it The agent will see files in your current directory. If you want to work on a different repo, stop Untether (Ctrl+C) and restart it in that directory—or set up projects to switch repos from chat.

2. Send a task

Open Telegram and send a message to your bot:

You explain what this repo does

3. Watch progress stream

Untether immediately posts a progress message and updates it as the agent works:

Untether starting · codex · 0s

As the agent calls tools and makes progress, you’ll see updates like:

Untether working · codex · 12s · step 3

✓ tool: read: readme.md<br>
✓ tool: read: docs/index.md<br>
✓ tool: read: src/untether/runner.py

The progress message is edited in-place.

4. See the final answer

When the agent finishes, Untether sends a new message and replaces the progress message, so you get a notification.

Untether done · codex · 11s · step 5

Untether is a Telegram bridge for AI coding agents (Codex, Claude Code, OpenCode, Pi). It lets you run agents from chat, manage multiple projects and git worktrees, stream progress (commands, file changes, elapsed time), and resume sessions from either chat or terminal. It also supports file transfer, group topics mapped to repo/branch contexts, and multiple engines via chat commands, with a plugin system for engines/transports/commands.

`codex resume 019bb89b-1b0b-7e90-96e4-c33181b49714`

That last line is the resume line—it’s how Untether knows which conversation to continue.

5. Continue the conversation

How you continue depends on your mode.

If you’re in chat mode: just send another message (no reply needed).

You now add tests for the API

Use /new any time you want a fresh thread.

If you’re in stateless mode: reply to a message that has a resume line.

Untether done · codex · 11s · step 5

You what command line arguments does it support?

Untether extracts the resume token from the message you replied to and continues the same agent session.

Reply-to-continue still works in chat mode If resume lines are visible, replying to any older message branches the conversation from that point. Use show_resume_line = true if you want this behavior all the time.

Reset with /new /new clears stored sessions for the current chat or topic.

6. Cancel a run

Sometimes you want to stop a run in progress—maybe you realize you asked the wrong question, or it’s taking too long.

While the progress message is showing, tap the cancel button or reply to it with:

Untether working · codex · 12s · step 3

You /cancel

Untether sends SIGTERM to the agent process and posts a cancelled status:

Failure cancelled · codex · 12s

`codex resume 019bb89b-1b0b-7e90-96e4-c33181b49714`

If a resume token was already issued (and resume lines are enabled), it will still be included so you can continue from where it stopped.

Cancel only works on progress messages If the run already finished, there’s nothing to cancel. Just send a new message or reply to continue.

7. Try a different engine

Want to use a different engine for one message? Prefix your message with /<engine>:

You /claude explain the error handling in this codebase

This uses Claude Code for just this message. The resume line will show claude --resume ..., and replies will automatically use Claude Code.

Available prefixes depend on what you have installed: /claude, /codex, /opencode, /pi, /gemini, /amp.

Set a default engine Use /agent set claude to make this chat (or topic) use Claude Code by default. Run /agent to see what’s set.

What just happened

Key points:

Untether spawns the agent CLI as a subprocess
The agent streams JSONL events (tool calls, progress, answer)
Untether renders these as an editable progress message
When done, the progress message is replaced with the final answer
Chat mode auto-resumes; resume lines let you reply to branch

Troubleshooting

Progress message stuck on “starting” (or not updating)

The agent might be doing something slow (large repo scan, network call). Wait a bit, or /cancel and try a more specific prompt.

Agent CLI not found

The agent CLI isn’t on your PATH. Install the CLI for the engine you’re using (e.g., npm install -g @openai/codex) and make sure the install location is in your PATH.

Bot doesn’t respond at all

Check that Untether is still running in your terminal. You should also see a startup message (“untether is ready”) from the bot in Telegram. If not, restart it.

Resume doesn’t work (starts a new conversation)

Make sure you’re replying to a message that contains a resume line. If you hid resume lines (show_resume_line = false), turn them on or use chat mode to continue by sending another message.

You’ve mastered the basics. Next, learn how to control Claude Code’s actions in real time with Telegram buttons.

Interactive control →

First run