Telegram bridge for AI coding agents.
Send tasks by voice or text, stream progress live, and approve changes — from your phone, anywhere.

Works with Claude Code · Codex · OpenCode · Pi · Gemini CLI · Amp

Quick Start · Features · Engines · Guides · Commands · Contributing

Your AI coding agents need a terminal, but you don't need to sit at one. Untether runs on your machine and connects your agents to a Telegram bot. Send a task from your phone — by voice or text — and watch your agent work in real time. When it needs permission, tap a button. When it's done, read the result. No desk, no SSH, no screen sharing.

_{* Feature availability varies by engine — see engine compatibility}

🐕 Why Untether?

AI coding agents are powerful, but they're chained to a terminal window. Untether breaks that chain:

• Your machine does the work — agents run on your computer (or server) as normal. Untether just bridges them to Telegram.
• Work from anywhere — walking the dog, at the gym, on the train, at a friend's place. If you have Telegram, you have your agents.
• Agents run in the background — start a task from your phone and put it away. The agent keeps working even if you close Telegram, lose signal, or your phone dies. Check the result when you're ready.
• Any device, any time — phone, tablet, laptop, or Telegram Web. Start a task on your phone at the park, review results on your laptop at home.
• Talk instead of type — send a voice note and Untether transcribes it. Hands full? Dictate your next task.
• Swap projects and agents — switch between repos, branches, and engines from the same chat. No restarting, no SSH, no context switching.
• Stay in control remotely — budgets, cost tracking, and interactive approval buttons mean you can trust your agents to run without hovering over a terminal.

⚡ Quick start

uv tool install untether        # recommended
# or
pipx install untether            # alternative

untether                        # run setup wizard

The wizard creates a Telegram bot, picks your workflow, and connects your chat. Then send a message to your bot:

fix the failing tests in src/auth

That's it. Your agent runs on your machine, streams progress to Telegram, and you can reply to continue the conversation.

The wizard offers three workflow modes — pick the one that fits:

Choose a mode → · Conversation modes tutorial →

Tip: Already have a bot token? Pass it directly: untether --bot-token YOUR_TOKEN

📖 See our help guides for detailed setup, engine configuration, and troubleshooting.

🎯 Features

• 📡 Progress streaming — watch your agent work in real time; see tool calls, file changes, and elapsed time as they happen
• 🔐 Interactive permissions — approve plan transitions and answer clarifying questions with inline option buttons; tools auto-execute, with progressive cooldown after "Pause & Outline Plan"
• 📋 Plan mode — toggle per chat with /planmode; choose full manual approval, auto-approved transitions, or no plan phase
• 📁 Projects and worktrees — register repos with untether init, target with /myproject @feat/thing, run branches in isolated worktrees in parallel
• 💰 Cost and usage tracking — run agents remotely with confidence; per-run and daily budgets, /usage breakdowns, and optional auto-cancel keep spending visible
• 💡 Actionable error hints — friendly messages for API outages, rate limits, billing errors, and network failures with resume guidance
• 🏷 Model and mode metadata — every completed message shows model with version, effort level, and permission mode (e.g. 🏷 opus 4.6 · medium · plan) across all engines
• 🎙️ Voice notes — hands full? Dictate tasks instead of typing; Untether transcribes via a configurable Whisper-compatible endpoint
• 🔄 Cross-environment resume — start a session in your terminal, pick it up from Telegram with /continue; works with Claude Code, Codex, OpenCode, Pi, and Gemini (guide)
• 📎 File transfer — upload files to your repo with /file put, download with /file get; agents can also deliver files automatically by writing to .untether-outbox/ during a run — sent as Telegram documents on completion
• 🛡️ Graceful recovery — orphan progress messages cleaned up on restart; stall detection with CPU-aware diagnostics; auto-continue for Claude Code sessions that exit prematurely
• ⏰ Scheduled tasks — cron expressions and webhook triggers
• 💬 Forum topics — map Telegram topics to projects and branches
• 📤 Session export — /export for markdown or JSON transcripts
• 🗂️ File browser — /browse to navigate project files with inline buttons
• ⚙️ Inline settings — /config opens an in-place settings menu; toggle plan mode, ask mode, approval policy (Codex), approval mode (Gemini), verbose, engine, model, reasoning, and trigger with buttons
• 🧩 Plugin system — extend with custom engines, transports, and commands
• 🔌 Plugin-compatible — Claude Code plugins detect Untether sessions via UNTETHER_SESSION env var, preventing hooks from interfering with Telegram output; works with PitchDocs and other Claude Code plugins
• 📊 Session statistics — /stats shows per-engine run counts, action totals, and duration across today, this week, and all time
• 💬 Three workflow modes — assistant (ongoing chat with auto-resume), workspace (forum topics bound to projects/branches), or handoff (reply-to-continue with terminal resume lines); choose a mode to match your workflow

🔌 Supported engines

Note: Use your existing Claude or ChatGPT subscription — no extra API keys needed (unless you want API billing).

Engine compatibility

¹ Amp model override maps to --mode (deep/free/rush/smart). ² Defaults to full access (--approval-mode=yolo, all tools auto-approved); toggle via /config to edit files (auto_edit, files OK but no shell) or read-only; pre-run policy, not interactive mid-run approval. ³ Token usage counts only — no USD cost reporting. ⁴ Toggle via /config between full auto (default) and safe (--ask-for-approval=untrusted, untrusted tools blocked); pre-run policy, not interactive mid-run approval. ⁵ Pi requires provider = "openai-codex" in engine config for OAuth subscriptions in headless mode. ⁶ AMP requires an explicit thread ID; no "most recent" mode.

🤖 Commands

Prefix any message with /<engine> to pick an engine for that task, or /<project> to target a repo:

/claude /myproject @feat/auth implement OAuth2

⚙️ Configuration

Untether reads ~/.untether/untether.toml. The setup wizard creates this for you, or configure manually:

default_engine = "codex"

[transports.telegram]
bot_token = "123456789:ABC..."
chat_id = 123456789
session_mode = "chat"

[projects.myapp]
path = "~/dev/myapp"
default_engine = "claude"

[cost_budget]
enabled = true
max_cost_per_run = 2.00
max_cost_per_day = 10.00

See the full configuration reference for all options.

Warning: Never commit your untether.toml — it contains your bot token. The default location (~/.untether/) keeps it outside your repos.

🔄 Upgrading

uv tool upgrade untether        # if installed with uv
# or
pipx upgrade untether            # if installed with pipx

Then restart to apply:

/restart                         # from Telegram (preferred — drains active runs first)

Or from your terminal:

untether                         # start (or restart — Ctrl+C first if already running)

Note: If you've set up a systemd service on Linux, use systemctl --user restart untether instead.

📦 Requirements

• Python 3.12+ — uv python install 3.14
• uv — curl -LsSf https://astral.sh/uv/install.sh | sh
• At least one agent CLI on PATH: claude, codex, opencode, pi, gemini, or amp

📖 Help Guides

Full documentation is available in the docs/ directory.

Getting Started

• Install and onboard — setup wizard walkthrough
• First run — send your first task
• Conversation modes — assistant, workspace, and handoff
• Projects and branches — multi-repo workflows
• Multi-engine workflows — switching between agents

How-To Guides

• Interactive approval — approve and deny tool calls from Telegram
• Plan mode — control plan transitions and progressive cooldown
• Cost budgets — per-run and daily budget limits
• Inline settings — /config button menu
• Voice notes — dictate tasks from your phone
• File browser — /browse inline navigation
• Session export — markdown and JSON transcripts
• Verbose progress — tool detail display
• Group chats — multi-user and trigger modes
• Context binding — per-chat project/branch binding
• Webhooks and cron — automated runs from external events

Engine Guides

• Claude Code — permission modes, plan mode, cost tracking, interactive approvals
• Codex — profiles, extra args, exec mode
• OpenCode — model selection, 75+ providers, local models
• Pi — multi-provider auth, model and provider selection
• Gemini CLI — Google Gemini models, approval mode passthrough
• Amp — mode selection, thread management

Reference

• Configuration reference — full walkthrough of untether.toml
• Troubleshooting — common issues and solutions
• Architecture — how the pieces fit together

🤝 Contributing

Found a bug? Got an idea? Open an issue — we'd love to hear from you.

Want to contribute code? See CONTRIBUTING.md for development setup, testing, and guidelines.

🙏 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 many other features.

📄 Licence

MIT — Made by Little Bear Apps 🐶