untether 0.27.1

Run AI coding agents from your phone. Bridges Claude Code, Codex, OpenCode, and Pi to Telegram with interactive permissions, voice notes, and live progress.

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

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.

---

⚡ 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

---

🔄 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
systemctl --user restart untether  # from shell (systemd)

---

🎯 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 clarifying questions with inline 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 — per-run and daily budgets, subscription usage in the footer, /usage for detailed breakdowns, optional auto-cancel
• 🏷 Model and mode metadata — every completed message shows the model and permission mode (e.g. 🏷 sonnet · plan) across all engines
• 🎙️ Voice notes — 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, verbose, engine, model, reasoning, and trigger with buttons
• 🧩 Plugin system — extend with custom engines, transports, and commands
• 💬 Conversation modes — 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

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

---

🤖 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, verbose, engine, model, reasoning, trigger)
/ctx	Show or update project/branch context
/reasoning	Set reasoning level override
/trigger	Set group chat trigger mode
/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.

---

📦 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: codex, claude, opencode, or pi

---

📖 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
• 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 🐶