untether 0.36.0

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}

⚡ 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, webhooks and cron)
• 🔄 Terminal ↔ Telegram resume — start in your terminal, pick it up with /continue (cross-environment resume)
• ⚙️ Settings and files from chat — /config button menu, /browse, /file put/get and agent-delivered files (inline settings, file transfer)

Every command is listed in the commands reference.

🔌 Supported engines

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

¹ 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, changelog, upgrading to v0.36.0

🤝 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 🐶