What It Does
Untether is a Python daemon (installed via uv tool install untether) that runs on your local machine or server and bridges CLI coding agents to a personal Telegram bot. You send tasks by voice note or text from any device with Telegram, the agent runs locally and streams tool calls, file changes, and elapsed time back to Telegram in real time, and you approve or deny permission requests via inline keyboard buttons. When the session ends, results are posted to chat.
It supports six agents — Claude Code, Codex, OpenCode, Pi, Gemini CLI, and Amp — via a plugin-based engine system. Claude Code has the deepest integration (interactive plan approval, ask-mode buttons, diff preview, subscription usage tracking, progressive cooldown). Other engines get basic streaming and session resume. The daemon reads configuration from ~/.untether/untether.toml (created by a setup wizard) and offers three workflow modes: assistant (ongoing chat, auto-resume), workspace (Telegram forum topics bound to projects/branches), and handoff (reply-to-continue with terminal resume lines).
Key Features
- Real-time progress streaming into Telegram: live tool call names, file edit paths, elapsed time — using Telegram’s inline message editing rather than message floods
- Interactive approval buttons: approve/deny plan transitions and answer clarifying questions from inline keyboards (Claude Code only)
- Plan mode control: toggle per-chat with
/planmode; supports full manual approval, auto-approved transitions, or no plan phase - Voice note transcription via configurable Whisper-compatible endpoint (supports self-hosted or third-party APIs; not locked to OpenAI)
- Per-run and daily cost budgets with
/usagebreakdowns and optional auto-cancel - Multi-project and git worktree support: register repos with
untether init, target with/myproject @feat/branch, run branches in isolated worktrees in parallel - Cross-environment session resume: start a session in terminal, pick it up from Telegram with
/continue(supported by Claude Code, Codex, OpenCode, Pi, Gemini CLI) - Plugin system for custom engines, transports, and commands via Python entry points
- Cron expressions and webhook triggers for scheduled autonomous tasks
- File transfer: upload files to repo with
/file put, download with/file get; agents deliver files via.untether-outbox/directory
Use Cases
- Remote long-running agent supervision: A developer starts a multi-hour refactor via Claude Code from their desk, leaves, and monitors progress from their phone — approving plan transitions and reviewing diffs without needing SSH or screen sharing.
- Mobile task delegation during commute or away-from-desk: Dictate a task description by voice note, have the agent start working, and review results when available — useful for “write a failing test for the auth module” type tasks that run unattended.
- Multi-project parallel agent management: Use Telegram forum topics as project channels to track separate agent sessions for different repos/branches simultaneously from a single chat interface.
- Overnight or scheduled autonomous coding tasks: Use cron triggers to run agents against low-priority tasks (documentation updates, lint fixes, dependency upgrades) outside working hours with budget guardrails to limit runaway cost.
Adoption Level Analysis
Small teams (<20 engineers): Fits as a personal power-user tool. Free, MIT-licensed, trivial to install with uv. No infrastructure requirements beyond a Telegram account and a bot token. The security model (Telegram auth + host filesystem access) is appropriate for individual developer use. Not a team coordination tool — the chat_id binding means one Telegram chat per Untether instance, limiting multi-user scenarios.
Medium orgs (20-200 engineers): Does not fit as a shared team tool. No multi-user RBAC, no audit logging, no SSO, no centralized management plane. Individual developers on a team may self-install it as a personal productivity layer, but deploying it as a team resource is out of scope for the current architecture. The bot token as the sole auth factor is a credential management problem at team scale.
Enterprise (200+ engineers): Does not fit. Security requirements (audit logs, centralized credential management, network egress controls, policy enforcement) are not addressed. The model of running a local daemon with Telegram as the transport is architecturally incompatible with enterprise security perimeters.
Alternatives
| Alternative | Key Difference | Prefer when… |
|---|---|---|
| Native agent TUI (Claude Code, OpenCode) | Direct terminal access, no bridge needed | You are at your development machine and want lowest latency |
| tmux + SSH | Full terminal access remotely, no Python process | You want raw terminal control and are comfortable with SSH key management |
| GitHub Actions / CI agents | Fully managed, audit-logged, no local daemon | You want verifiable, reproducible automated coding tasks with org-level controls |
| Slack bot wrappers (custom) | Enterprise messaging platform, SSO-capable | Your org runs on Slack and needs audit logging and RBAC |
Evidence & Sources
- GitHub Repository — littlebearapps/untether — source code, README, feature compatibility matrix
- PyPI Package — untether v0.35.0 — official package, install stats
- Original fork — banteg/takopi — predecessor project (Codex-only Telegram bridge)
- Untether docs — how-to guides, tutorials, configuration reference
Notes & Caveats
- Tight coupling to undocumented agent internals. The interactive approval and plan mode features for Claude Code depend on intercepting Claude Code’s internal event format, which has no published stability guarantee. A Claude Code update that changes permission event structure could silently break the most differentiating features. This is the primary technical risk.
- Single-team bus factor. Little Bear Apps appears to be a one-person studio. The
CONTRIBUTORS.mdfile exists but contribution is early-stage. A bus factor of 1 is a risk for a tool embedded in daily development workflows. - Security model is personal-tool-grade. The Telegram bot token is the sole authentication factor. There is no sandboxing between the agent process and the host filesystem. This is acceptable for personal use but is not suitable for shared infrastructure or machines with sensitive data beyond dev credentials.
- v0.35.0 in 2 months indicates fast iteration but also instability risk. The project is classified as “Beta” (
Development Status :: 4 - Beta) in PyPI classifiers, which is honest. Users should pin versions in production-like setups. - Voice transcription adds an external dependency. Even for local-only AI workflows, voice note transcription requires an outbound API call unless a self-hosted Whisper endpoint is configured. The default likely uses OpenAI’s Whisper API, which may not be acceptable in privacy-conscious environments.
- Rate limiting from Telegram. Telegram’s bot API limits message edits to approximately 1/second per message. High-throughput agents generating rapid tool calls will see batched or throttled progress updates, reducing perceived real-time granularity.
- Fork lineage. The project explicitly acknowledges forking banteg/takopi. The original author is a respected Ethereum/DeFi developer, not a coding agent specialist. Untether’s team has significantly extended the original, but the architectural foundations predate the multi-engine vision.