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.
⚡ Quick start
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 wizard
The 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 auto permission mode is now plan-auto, unattended crons deny approvals, Codex safe mode is a real read-only sandbox, and more). Read Upgrading to v0.36.0 first.
🎯 What you get
- 📡 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
/steer sends 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/thing targets 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,
/usage breakdowns (cost budgets)
- ⏰ Schedules and webhooks — cron triggers, webhook triggers, one-shot
/at 30m … runs and Claude Loop mode (schedule tasks, )
Every command is listed in the commands reference.
🔌 Supported engines
| 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.
Engine compatibility
| 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.
Deprecated engines
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.
🔒 Privacy and security
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.
📖 Documentation
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, ,
🤝 Contributing
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.
🙏 Acknowledgements
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.
📄 Licence
MIT — made by Little Bear Apps 🐶
