{"id":45778248,"url":"https://github.com/littlebearapps/untether","last_synced_at":"2026-03-09T12:01:47.199Z","repository":{"id":337031137,"uuid":"1152042352","full_name":"littlebearapps/untether","owner":"littlebearapps","description":"Code from anywhere — Telegram bridge for AI coding agents (Claude Code, Codex, OpenCode, Pi, Gemini CLI, Amp). Stream progress, approve actions, and send tasks by voice from your phone.","archived":false,"fork":false,"pushed_at":"2026-03-07T09:20:44.000Z","size":4179,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-07T14:37:44.790Z","etag":null,"topics":["ai-agents","amp","claude-code","cli","cli-tools","codex","coding-assistant","developer-tools","gemini-cli","opencode","python","remote-control","remote-development","telegram","telegram-bot"],"latest_commit_sha":null,"homepage":"https://littlebearapps.com/builds/untether/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"banteg/takopi","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/littlebearapps.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-07T09:17:30.000Z","updated_at":"2026-03-07T09:18:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/littlebearapps/untether","commit_stats":null,"previous_names":["littlebearapps/takopi","littlebearapps/untether"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/littlebearapps/untether","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlebearapps%2Funtether","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlebearapps%2Funtether/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlebearapps%2Funtether/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlebearapps%2Funtether/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/littlebearapps","download_url":"https://codeload.github.com/littlebearapps/untether/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlebearapps%2Funtether/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30294656,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T11:12:22.024Z","status":"ssl_error","status_checked_at":"2026-03-09T11:10:54.577Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","amp","claude-code","cli","cli-tools","codex","coding-assistant","developer-tools","gemini-cli","opencode","python","remote-control","remote-development","telegram","telegram-bot"],"created_at":"2026-02-26T10:49:01.165Z","updated_at":"2026-03-09T12:01:47.191Z","avatar_url":"https://github.com/littlebearapps.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/littlebearapps/untether/master/docs/assets/untether-logo-full.svg\" height=\"200\" alt=\"Untether\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eTelegram bridge for AI coding agents.\u003c/strong\u003e\u003cbr\u003e\n  Send tasks by voice or text, stream progress live, and approve changes — from your phone, anywhere.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Works with \u003ca href=\"https://docs.anthropic.com/en/docs/claude-code\"\u003eClaude Code\u003c/a\u003e · \u003ca href=\"https://github.com/openai/codex\"\u003eCodex\u003c/a\u003e · \u003ca href=\"https://github.com/opencode-ai/opencode\"\u003eOpenCode\u003c/a\u003e · \u003ca href=\"https://github.com/nicholasgasior/pi\"\u003ePi\u003c/a\u003e · \u003ca href=\"https://github.com/google-gemini/gemini-cli\"\u003eGemini CLI\u003c/a\u003e · \u003ca href=\"https://ampcode.com\"\u003eAmp\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/littlebearapps/untether/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/littlebearapps/untether/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/untether/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/untether\" alt=\"PyPI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/untether/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/pyversions/untether\" alt=\"Python\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/littlebearapps/untether/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue\" alt=\"License\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-quick-start\"\u003eQuick Start\u003c/a\u003e · \u003ca href=\"#-features\"\u003eFeatures\u003c/a\u003e · \u003ca href=\"#-supported-engines\"\u003eEngines\u003c/a\u003e · \u003ca href=\"#-commands\"\u003eCommands\u003c/a\u003e · \u003ca href=\"#-contributing\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nYour 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.\n\n---\n\n## 🐕 Why Untether?\n\nAI coding agents are powerful, but they're chained to a terminal window. Untether breaks that chain:\n\n- **Your machine does the work** — agents run on your computer (or server) as normal. Untether just bridges them to Telegram.\n- **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.\n- **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.\n- **Any device, any time** — phone, tablet, laptop, or [Telegram Web](https://web.telegram.org). Start a task on your phone at the park, review results on your laptop at home.\n- **Talk instead of type** — send a voice note and Untether transcribes it. Hands full? Dictate your next task.\n- **Swap projects and agents** — switch between repos, branches, and engines from the same chat. No restarting, no SSH, no context switching.\n- **Stay in control remotely** — budgets, cost tracking, and interactive approval buttons mean you can trust your agents to run without hovering over a terminal.\n\n---\n\n## ⚡ Quick start\n\n```sh\nuv tool install untether        # recommended\n# or\npipx install untether            # alternative\n```\n\n```sh\nuntether                        # run setup wizard\n```\n\nThe wizard creates a Telegram bot, picks your workflow, and connects your chat. Then send a message to your bot:\n\n\u003e fix the failing tests in src/auth\n\nThat's it. Your agent runs on your machine, streams progress to Telegram, and you can reply to continue the conversation.\n\n**Tip:** Already have a bot token? Pass it directly: `untether --bot-token YOUR_TOKEN`\n\n---\n\n## 🎯 Features\n\n- 📡 **Progress streaming** — watch your agent work in real time; see tool calls, file changes, and elapsed time as they happen\n- 🔐 **Interactive permissions** — approve plan transitions and answer clarifying questions with inline option buttons; tools auto-execute, with progressive cooldown after \"Pause \u0026 Outline Plan\"\n- 📋 **Plan mode** — toggle per chat with `/planmode`; choose full manual approval, auto-approved transitions, or no plan phase\n- 📁 **Projects and worktrees** — register repos with `untether init`, target with `/myproject @feat/thing`, run branches in isolated worktrees in parallel\n- 💰 **Cost and usage tracking** — run agents remotely with confidence; per-run and daily budgets, `/usage` breakdowns, and optional auto-cancel keep spending visible\n- 💡 **Actionable error hints** — friendly messages for API outages, rate limits, billing errors, and network failures with resume guidance\n- 🏷 **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\n- 🎙️ **Voice notes** — hands full? Dictate tasks instead of typing; Untether transcribes via a configurable Whisper-compatible endpoint\n- 📎 **File transfer** — upload files to your repo or download results back\n- ⏰ **Scheduled tasks** — cron expressions and webhook triggers\n- 💬 **Forum topics** — map Telegram topics to projects and branches\n- 📤 **Session export** — `/export` for markdown or JSON transcripts\n- 🗂️ **File browser** — `/browse` to navigate project files with inline buttons\n- ⚙️ **Inline settings** — `/config` opens an in-place settings menu; toggle plan mode, ask mode, verbose, engine, model, reasoning, and trigger with buttons\n- 🧩 **Plugin system** — extend with custom engines, transports, and commands\n- 📊 **Session statistics** — `/stats` shows per-engine run counts, action totals, and duration across today, this week, and all time\n- 💬 **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)\n\n---\n\n## 🔌 Supported engines\n\n| Engine | Install | What it's good at |\n|--------|---------|-------------------|\n| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `npm i -g @anthropic-ai/claude-code` | Complex refactors, architecture, long context |\n| [Codex](https://github.com/openai/codex) | `npm i -g @openai/codex` | Fast edits, shell commands, quick fixes |\n| [OpenCode](https://github.com/opencode-ai/opencode) | `npm i -g opencode-ai@latest` | 75+ providers via Models.dev, local models |\n| [Pi](https://github.com/mariozechner/pi-coding-agent) | `npm i -g @mariozechner/pi-coding-agent` | Multi-provider auth, conversational |\n| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm i -g @google/gemini-cli` | Google Gemini models, configurable approval mode |\n| [Amp](https://ampcode.com) | `npm i -g @sourcegraph/amp` | Sourcegraph's AI coding agent, mode selection |\n\n**Note:** Use your existing Claude or ChatGPT subscription — no extra API keys needed (unless you want API billing).\n\n### Engine compatibility\n\n| Feature | Claude Code | Codex CLI | OpenCode | Pi | Gemini CLI | Amp |\n|---------|:-----------:|:---------:|:--------:|:--:|:----------:|:---:|\n| **Progress streaming** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| **Session resume** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| **Model override** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅¹ |\n| **Voice input** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| **Verbose progress** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| **Error hints** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| **Preamble injection** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| **Cost tracking** | ✅ | ~³ | ✅ | ~³ | ~³ | ~³ |\n| **Interactive permissions** | ✅ | — | — | — | — | — |\n| **Plan mode** | ✅ | — | — | — | ~² | — |\n| **Ask mode (option buttons)** | ✅ | — | — | — | — | — |\n| **Diff preview** | ✅ | — | — | — | — | — |\n| **Auto-approve safe tools** | ✅ | — | — | — | — | — |\n| **Progressive cooldown** | ✅ | — | — | — | — | — |\n| **Subscription usage** | ✅ | — | — | — | — | — |\n| **Reasoning/effort levels** | ✅ | ✅ | — | — | — | — |\n| **Device re-auth (`/auth`)** | — | ✅ | — | — | — | — |\n| **Context compaction** | — | — | — | ✅ | — | — |\n\n¹ Amp model override maps to `--mode` (deep/free/rush/smart).\n² Toggle via `/config` between read-only (default) and full access (`--approval-mode=yolo`); not Untether's interactive approve/deny workflow.\n³ Token usage counts only — no USD cost reporting.\n\n---\n\n## 🤖 Commands\n\n| Command | What it does |\n|---------|-------------|\n| `/cancel` | Stop the running agent |\n| `/agent` | Show or set the engine for this chat |\n| `/model` | Override the model for an engine |\n| `/planmode` | Toggle plan mode (on/auto/off) |\n| `/usage` | Show API costs for the current session |\n| `/export` | Export session transcript |\n| `/browse` | Browse project files |\n| `/new` | Clear stored sessions |\n| `/file put/get` | Transfer files |\n| `/topic` | Create or bind forum topics |\n| `/restart` | Gracefully restart Untether (drains active runs first) |\n| `/verbose` | Toggle verbose progress mode (show tool details) |\n| `/config` | Interactive settings menu (plan mode, ask mode, verbose, engine, model, reasoning, trigger, approval mode, cost \u0026 usage) |\n| `/ctx` | Show or update project/branch context |\n| `/reasoning` | Set reasoning level override |\n| `/trigger` | Set group chat trigger mode |\n| `/stats` | Per-engine session statistics (today/week/all-time) |\n| `/auth` | Codex device re-authentication |\n| `/ping` | Health check / uptime |\n\nPrefix any message with `/\u003cengine\u003e` to pick an engine for that task, or `/\u003cproject\u003e` to target a repo:\n\n\u003e /claude /myproject @feat/auth implement OAuth2\n\n---\n\n## ⚙️ Configuration\n\nUntether reads `~/.untether/untether.toml`. The setup wizard creates this for you, or configure manually:\n\n```toml\ndefault_engine = \"codex\"\n\n[transports.telegram]\nbot_token = \"123456789:ABC...\"\nchat_id = 123456789\nsession_mode = \"chat\"\n\n[projects.myapp]\npath = \"~/dev/myapp\"\ndefault_engine = \"claude\"\n\n[cost_budget]\nenabled = true\nmax_cost_per_run = 2.00\nmax_cost_per_day = 10.00\n```\n\nSee the [full configuration reference](https://github.com/littlebearapps/untether/blob/master/docs/reference/config.md) for all options.\n\n**Warning:** Never commit your `untether.toml` — it contains your bot token. The default location (`~/.untether/`) keeps it outside your repos.\n\n---\n\n## 🔄 Upgrading\n\n```sh\nuv tool upgrade untether        # if installed with uv\n# or\npipx upgrade untether            # if installed with pipx\n```\n\nThen restart to apply:\n\n```sh\n/restart                         # from Telegram (preferred — drains active runs first)\n```\n\nOr from your terminal:\n\n```sh\nuntether                         # start (or restart — Ctrl+C first if already running)\n```\n\n\u003e **Note:** If you've set up a systemd service on Linux, use `systemctl --user restart untether` instead.\n\n---\n\n## 📦 Requirements\n\n- **Python 3.12+** — `uv python install 3.14`\n- **uv** — `curl -LsSf https://astral.sh/uv/install.sh | sh`\n- At least one agent CLI on PATH: `claude`, `codex`, `opencode`, `pi`, `gemini`, or `amp`\n\n---\n\n## 📖 Engine guides\n\nDetailed setup and usage for each engine:\n\n- [Claude Code guide](https://github.com/littlebearapps/untether/blob/master/docs/reference/runners/claude/runner.md) — permission modes, plan mode, cost tracking, interactive approvals\n- [Codex guide](https://github.com/littlebearapps/untether/blob/master/docs/reference/runners/codex/exec-json-cheatsheet.md) — profiles, extra args, exec mode\n- [OpenCode guide](https://github.com/littlebearapps/untether/blob/master/docs/reference/runners/opencode/runner.md) — model selection, 75+ providers, local models\n- [Pi guide](https://github.com/littlebearapps/untether/blob/master/docs/reference/runners/pi/runner.md) — multi-provider auth, model and provider selection\n- [Gemini CLI guide](https://github.com/littlebearapps/untether/blob/master/docs/reference/runners/gemini/runner.md) — Google Gemini models, approval mode passthrough\n- [Amp guide](https://github.com/littlebearapps/untether/blob/master/docs/reference/runners/amp/runner.md) — mode selection, thread management\n- [Configuration reference](https://github.com/littlebearapps/untether/blob/master/docs/reference/config.md) — full walkthrough of `untether.toml`\n- [Troubleshooting guide](https://github.com/littlebearapps/untether/blob/master/docs/how-to/troubleshooting.md) — common issues and solutions\n\n---\n\n## 📚 Documentation\n\nFull documentation is available in the [`docs/`](https://github.com/littlebearapps/untether/tree/master/docs) directory.\n\n- [Install and onboard](https://github.com/littlebearapps/untether/blob/master/docs/tutorials/install.md) — setup wizard walkthrough\n- [First run](https://github.com/littlebearapps/untether/blob/master/docs/tutorials/first-run.md) — send your first task\n- [Interactive approval](https://github.com/littlebearapps/untether/blob/master/docs/how-to/interactive-approval.md) — approve and deny tool calls from Telegram\n- [Plan mode](https://github.com/littlebearapps/untether/blob/master/docs/how-to/plan-mode.md) — control plan transitions and progressive cooldown\n- [Cost budgets](https://github.com/littlebearapps/untether/blob/master/docs/how-to/cost-budgets.md) — per-run and daily budget limits\n- [Webhooks and cron](https://github.com/littlebearapps/untether/blob/master/docs/how-to/webhooks-and-cron.md) — automated runs from external events\n- [Projects and branches](https://github.com/littlebearapps/untether/blob/master/docs/tutorials/projects-and-branches.md) — multi-repo workflows\n- [Multi-engine workflows](https://github.com/littlebearapps/untether/blob/master/docs/tutorials/multi-engine.md) — switching between agents\n- [Inline settings](https://github.com/littlebearapps/untether/blob/master/docs/how-to/inline-settings.md) — `/config` button menu\n- [Verbose progress](https://github.com/littlebearapps/untether/blob/master/docs/how-to/verbose-progress.md) — tool detail display\n- [Voice notes](https://github.com/littlebearapps/untether/blob/master/docs/how-to/voice-notes.md) — dictate tasks from your phone\n- [File browser](https://github.com/littlebearapps/untether/blob/master/docs/how-to/browse-files.md) — `/browse` inline navigation\n- [Session export](https://github.com/littlebearapps/untether/blob/master/docs/how-to/export-sessions.md) — markdown and JSON transcripts\n- [Group chats](https://github.com/littlebearapps/untether/blob/master/docs/how-to/group-chat.md) — multi-user and trigger modes\n- [Context binding](https://github.com/littlebearapps/untether/blob/master/docs/how-to/context-binding.md) — per-chat project/branch binding\n- [Conversation modes](https://github.com/littlebearapps/untether/blob/master/docs/tutorials/conversation-modes.md) — assistant, workspace, and handoff\n- [Architecture](https://github.com/littlebearapps/untether/blob/master/docs/explanation/architecture.md) — how the pieces fit together\n\n---\n\n## 🤝 Contributing\n\nFound a bug? Got an idea? [Open an issue](https://github.com/littlebearapps/untether/issues) — we'd love to hear from you.\n\nWant to contribute code? See [CONTRIBUTING.md](https://github.com/littlebearapps/untether/blob/master/CONTRIBUTING.md) for development setup, testing, and guidelines.\n\n---\n\n## 🙏 Acknowledgements\n\nUntether is a fork of [takopi](https://github.com/banteg/takopi) by [@banteg](https://github.com/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.\n\n---\n\n## 📄 Licence\n\n[MIT](https://github.com/littlebearapps/untether/blob/master/LICENSE) — Made by [Little Bear Apps](https://github.com/littlebearapps) 🐶\n","funding_links":[],"categories":["Automation","Tools",":tada: New","Companion Apps \u0026 GUIs"],"sub_categories":["WebUI \u0026 App","Quick Setup with cc-safe-setup"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flittlebearapps%2Funtether","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flittlebearapps%2Funtether","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flittlebearapps%2Funtether/lists"}