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 · 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.

---

🐕 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.

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

---

🎯 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
• 📎 File transfer — upload files to your repo or download results back
• ⏰ 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, 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
• 💬 Conversation modes — pick the style that fits how you work: assistant (ongoing chat), workspace (forum topics per project), or handoff (reply-to-continue with terminal resume)

---

🔌 Supported engines

Engine	Install	What it's good at
Claude Code	npm i -g @anthropic-ai/claude-code	Complex refactors, architecture, long context
Codex	npm i -g @openai/codex	Fast edits, shell commands, quick fixes
OpenCode	npm i -g opencode-ai@latest	75+ providers via Models.dev, local models
Pi	npm i -g @mariozechner/pi-coding-agent	Multi-provider auth, conversational
Gemini CLI	npm i -g @google/gemini-cli	Google Gemini models, configurable approval mode
Amp	npm i -g @sourcegraph/amp	Sourcegraph's AI coding agent, mode selection

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

Engine compatibility

Feature	Claude Code	Codex CLI	OpenCode	Pi	Gemini CLI	Amp
Progress streaming	✅	✅	✅	✅	✅	✅
Session resume	✅	✅	✅	✅	✅	✅
Model override	✅	✅	✅	✅	✅	✅¹
Voice input	✅	✅	✅	✅	✅	✅
Verbose progress	✅	✅	✅	✅	✅	✅
Error hints	✅	✅	✅	✅	✅	✅
Preamble injection	✅	✅	✅	✅	✅	✅
Cost tracking	✅	~³	✅	~³	~³	~³
Interactive permissions	✅	—	—	—	—	—
Plan mode	✅	—	—	—	~²	—
Ask mode (option buttons)	✅	—	—	—	—	—
Diff preview	✅	—	—	—	—	—
Auto-approve safe tools	✅	—	—	—	—	—
Progressive cooldown	✅	—	—	—	—	—
Subscription usage	✅	—	—	—	—	—
Reasoning/effort levels	✅	✅	—	—	—	—
Device re-auth (/auth)	—	✅	—	—	—	—
Context compaction	—	—	—	✅	—	—

¹ Amp model override maps to --mode (deep/free/rush/smart). ² Toggle via /config between read-only (default) and full access (--approval-mode=yolo); not Untether's interactive approve/deny workflow. ³ Token usage counts only — no USD cost reporting.

---

🤖 Commands

Command	What it does
/cancel	Stop the running agent
/agent	Show or set the engine for this chat
/model	Override the model for an engine
/planmode	Toggle plan mode (on/auto/off)
/usage	Show API costs for the current session
/export	Export session transcript
/browse	Browse project files
/new	Clear stored sessions
/file put/get	Transfer files
/topic	Create or bind forum topics
/restart	Gracefully restart Untether (drains active runs first)
/verbose	Toggle verbose progress mode (show tool details)
/config	Interactive settings menu (plan mode, ask mode, verbose, engine, model, reasoning, trigger, approval mode, cost & usage)
/ctx	Show or update project/branch context
/reasoning	Set reasoning level override
/trigger	Set group chat trigger mode
/stats	Per-engine session statistics (today/week/all-time)
/auth	Codex device re-authentication
/ping	Health check / uptime

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

---

📖 Engine guides

Detailed setup and usage for each engine:

• Claude Code guide — permission modes, plan mode, cost tracking, interactive approvals
• Codex guide — profiles, extra args, exec mode
• OpenCode guide — model selection, 75+ providers, local models
• Pi guide — multi-provider auth, model and provider selection
• Gemini CLI guide — Google Gemini models, approval mode passthrough
• Amp guide — mode selection, thread management
• Configuration reference — full walkthrough of untether.toml
• Troubleshooting guide — common issues and solutions

---

📚 Documentation

Full documentation is available in the docs/ directory.

• Install and onboard — setup wizard walkthrough
• First run — send your first task
• 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
• Webhooks and cron — automated runs from external events
• Projects and branches — multi-repo workflows
• Multi-engine workflows — switching between agents
• Inline settings — /config button menu
• Verbose progress — tool detail display
• Voice notes — dictate tasks from your phone
• File browser — /browse inline navigation
• Session export — markdown and JSON transcripts
• Group chats — multi-user and trigger modes
• Context binding — per-chat project/branch binding
• Conversation modes — assistant, workspace, and handoff
• 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 🐶