Getting Started with Untether

Untether runs on your computer or server and connects your coding agents to a Telegram bot. This page is the short version. The Install and onboard tutorial has every wizard step.

What you’ll need#

• Python 3.12 or newer (3.14 recommended) and uv, or pipx
• A Telegram account
• At least one agent CLI on your PATH, signed in: Claude Code (claude), Codex (codex), OpenCode 1.x (opencode) or Pi (pi)

Install#

uv tool install -U untether

Prefer pipx? pipx install untether works too. Check it’s installed with untether --version.

Run the setup wizard#

Start Untether with no config and it launches the setup wizard:

untether

The wizard:

1. Takes your bot token, or walks you through creating a bot with @BotFather
2. Asks how you’ll use it: assistant (ongoing chat), workspace (forum topics per project and branch) or handoff (reply to continue)
3. Connects your chat: you send /start to the bot (or set up a topics group for workspace)
4. Picks a default engine from the agents you have installed
5. Saves everything to ~/.untether/untether.toml

Run untether --onboard any time to go through it again.

Send your first task#

Leave untether running, open Telegram and message your bot:

fix the failing tests in src/auth

Progress streams into the chat while the agent works, and the final answer arrives when it’s done. To use a different engine for one message, prefix it: /claude explain the error handling in this codebase.

What’s next#

• First run: progress, resuming, cancelling and switching engines
• Projects: register a repo with untether init <alias> and target it from any chat
• Choose a mode: assistant, workspace or handoff in more detail
• Found a bug? Report it on GitHub
• Have a question? Ask in Discussions