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.

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

• 📡 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
• 🧩 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)

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

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

/claude /myproject @feat/auth implement OAuth2

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.

• 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

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

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
• Architecture — how the pieces fit together

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.

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.

MIT — Made by Little Bear Apps 🐶