Telegram bridge for AI coding agents.
Send tasks by voice or text, stream progress live, and approve changes — from your phone, anywhere.
🌐 untether.cc · 📖 Help guides
Quick start · Features · Engines · Docs · Contributing
Your AI coding agents need a terminal, but you don't need to sit at one. Untether runs on your machine (or server) and connects Claude Code, Codex, OpenCode and Pi to a Telegram bot. Send a task from your phone, watch the agent work in real time, tap a button when it needs permission, and read the result when it's done — no desk, no SSH, no screen sharing. The agent keeps running if you close Telegram or lose signal.
* Feature availability varies by engine — see engine compatibility
You need Python 3.12+, uv (or pipx), and at least one agent CLI on your PATH (claude, codex, opencode or pi).
uv tool install untether # recommended
# or
pipx install untether
untether # first run starts the setup wizardThe wizard creates your Telegram bot (or takes an existing token), picks a workflow mode — assistant, workspace or handoff — and connects your chat. Then message your bot:
fix the failing tests in src/auth
Step-by-step: Install and onboard → First run. Update with uv tool upgrade untether (or pipx upgrade untether), then send /restart from Telegram — see Update Untether.
Upgrading from 0.35.x? v0.36.0 has breaking changes (the
autopermission mode is nowplan-auto, unattended crons deny approvals, Codex safe mode is a real read-only sandbox, and more). Read Upgrading to v0.36.0 first.
- 📡 Live progress — tool calls, file changes and elapsed time stream into one message as the agent works (verbose progress)
- 🔐 Approvals from your phone (Claude) — approve tool calls, plans and clarifying questions with inline buttons; four permission modes via
/planmode(interactive approval, plan mode) - ↪️ Live sessions and steering (Claude) — background tasks stay visible, and
/steersends a follow-up into the running session (steer follow-ups) - 🎙️ Voice notes — dictate tasks; transcribed by any Whisper-compatible endpoint (voice notes)
- 📁 Projects, branches and worktrees —
/myproject @feat/thingtargets a repo and branch, with parallel runs in isolated worktrees (projects, worktrees) - 💬 Three workflow modes — ongoing chat, forum topics per project, or reply-to-continue handoff (choose a mode)
- 💰 Cost and usage tracking — per-run and daily budgets, outlier alerts, optional stop-at-limit,
/usagebreakdowns (cost budgets) - ⏰ Schedules and webhooks — cron triggers, webhook triggers, one-shot
/at 30m …runs and Claude Loop mode (schedule tasks, webhooks and cron) - 🔄 Terminal ↔ Telegram resume — start in your terminal, pick it up with
/continue(cross-environment resume) - ⚙️ Settings and files from chat —
/configbutton menu,/browse,/file put/getand agent-delivered files (inline settings, file transfer)
Every command is listed in the commands reference.
| Engine | Install | Good at |
|---|---|---|
| Claude Code | npm i -g @anthropic-ai/claude-code |
Complex refactors, architecture, long context — and all interactive features |
| Codex | npm i -g @openai/codex |
Fast edits, shell commands, quick fixes |
| OpenCode | npm i -g opencode-ai@1 |
75+ providers via Models.dev, local models (1.x only — 2.x is refused before it starts) |
| Pi | npm i -g @mariozechner/pi-coding-agent |
Multi-provider auth, conversational |
Use your existing Claude or ChatGPT subscription — no extra API keys needed unless you want API billing. Switch engines per message (/codex …) or per chat (/agent set claude) — see switch engines.
| Feature | Claude Code | Codex | OpenCode | Pi |
|---|---|---|---|---|
| Progress streaming, resume, voice input, model override | ✅ | ✅ | ✅ | ✅ |
Terminal resume (/continue) |
✅ | ✅ | ✅ | ✅² |
| Cost tracking | ✅ | ~¹ | ✅ | ~¹ |
| Reasoning / effort levels | ✅ | ✅ | — | — |
Pre-run approval policy (/config) |
✅ | ✅ | — | — |
| Interactive approvals, plan mode, ask mode, diff preview | ✅ | — | —³ | — |
Live sessions, background tasks, /steer |
✅ | — | — | — |
| Context % in status line, subscription usage | ✅ | — | — | — |
| Context compaction shown | ✅ | — | — | ✅ |
Device re-auth (/auth codex) |
— | ✅ | — | — |
¹ Token counts only, no USD cost. ² Pi needs provider = "openai-codex" for OAuth subscriptions in headless mode. ³ opencode run rejects tools your OpenCode rules set to ask — set them to allow for unattended use.
Gemini CLI and Amp still ship and load, but are deprecated and no longer supported — no testing, no bug fixes, and they may be removed in a future release. Google retired Gemini CLI for individual accounts on 18 June 2026; its successor, Antigravity CLI, arrives as its own engine in v0.36.1. Amp remotely refuses clients it considers out of date, so a working setup can stop without notice. Details: troubleshooting.
Untether runs entirely on your machine: no telemetry, no analytics, no phone-home, no auto-updates. Its own outbound calls are the Telegram Bot API, Anthropic's subscription-usage endpoint for Claude (using Claude Code's existing login) and, only if you enable it, a voice-transcription endpoint; agent CLIs call their own vendors' APIs. Config lives in ~/.untether/untether.toml — it holds your bot token, so never commit it. Lock the bot to your Telegram user ID and read security hardening and where your data goes.
Full docs live in the help centre (mirrored from docs/).
- Tutorials — install, first run, conversation modes, projects and branches, multi-engine workflows
- How-to guides — all guides, including group chats, forum topics, model and reasoning, session export and uninstall
- Reference — configuration, commands, engine runners, architecture
- Help — FAQ, troubleshooting, changelog, upgrading to v0.36.0
Found a bug? Open an issue. Questions and ideas go to GitHub Discussions (Q&A, Ideas); follow Announcements for a plain-English summary of every release.
Want to contribute code? See CONTRIBUTING.md. To report a vulnerability privately, see SECURITY.md.
Untether is a fork of takopi by @banteg, which provided the original Telegram-to-Codex bridge. Untether extends it with interactive permission control, multi-engine support, plan mode, cost tracking and much more.
MIT — made by Little Bear Apps 🐶