Metadata-Version: 2.3
Name: untether
Version: 0.22.1
Summary: Telegram bridge for Claude Code, Codex, and other agent CLIs. Fork of takopi with interactive permission control.
Keywords: telegram,claude-code,codex,opencode,ai-agents,coding-assistant,remote-control,cli-bridge
Author: Nathan Schram, banteg (upstream takopi)
License: MIT License
         
         Copyright (c) 2025 banteg
         Copyright (c) 2025-2026 Little Bear Apps and contributors
         Copyright (c) 2025-2026 Nathan Schram and contributors
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Build Tools
Classifier: Typing :: Typed
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: anyio>=4.12.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: markdown-it-py
Requires-Dist: msgspec>=0.20.0
Requires-Dist: openai>=2.15.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: questionary>=2.1.1
Requires-Dist: rich>=14.2.0
Requires-Dist: structlog>=25.5.0
Requires-Dist: sulguk>=0.11.1
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: typer>=0.21.0
Requires-Dist: watchfiles>=0.21.0
Requires-Python: >=3.12
Project-URL: Changelog, https://untether.cc/reference/changelog/
Project-URL: Documentation, https://untether.cc/
Project-URL: Homepage, https://github.com/littlebearapps/untether
Project-URL: Issues, https://github.com/littlebearapps/untether/issues
Project-URL: Repository, https://github.com/littlebearapps/untether
Project-URL: Upstream, https://github.com/banteg/takopi
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/logo.svg" alt="Untether" width="120" />
</p>

<h1 align="center">Untether</h1>

<p align="center">
  <strong>Control your AI coding agents from Telegram.</strong><br>
  Stream progress, approve actions, manage projects — from anywhere.
</p>

<p align="center">
  <a href="https://github.com/littlebearapps/untether/actions/workflows/ci.yml"><img src="https://github.com/littlebearapps/untether/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://pypi.org/project/untether/"><img src="https://img.shields.io/pypi/v/untether" alt="PyPI" /></a>
  <a href="https://pypi.org/project/untether/"><img src="https://img.shields.io/pypi/pyversions/untether" alt="Python" /></a>
  <a href="https://github.com/littlebearapps/untether/blob/master/LICENSE"><img src="https://img.shields.io/github/license/littlebearapps/untether" alt="License" /></a>
</p>

---

Untether is a Telegram bridge for AI coding agents. It connects [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenCode](https://github.com/opencode-ai/opencode), and [Pi](https://github.com/nicholasgasior/pi) to Telegram so you can send coding tasks, watch progress live, and approve actions — all from your phone.

Walk the dog, watch the footy, sit at a friend's place. Your agents keep working. You stay in control.

## Quick start

```sh
uv tool install -U untether    # install
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.

## Why Untether?

| Problem | Untether's solution |
|---------|-------------------|
| You have to sit at your desk while agents work | Stream progress to Telegram — watch from anywhere |
| Agents need permission to run tools | Approve or deny actions with inline buttons on your phone |
| You switch between Claude, Codex, and other agents | One bot, multiple engines — switch with `/claude`, `/codex`, `/opencode`, or `/pi` |
| Managing multiple repos from chat is messy | Register projects, target them with `/myproject`, branch with `@feat/thing` |
| No cost visibility | Per-run and daily cost tracking with configurable budgets |
| Can't continue terminal sessions remotely | Stateless resume — pick up any session in chat or terminal |

## Supported engines

| Engine | Install | What it's good at |
|--------|---------|-------------------|
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `npm i -g @anthropic-ai/claude-code` | Complex refactors, architecture, long context |
| [Codex](https://github.com/openai/codex) | `npm i -g @openai/codex` | Fast edits, shell commands, quick fixes |
| [OpenCode](https://github.com/opencode-ai/opencode) | `npm i -g opencode-ai@latest` | 75+ providers via Models.dev, local models |
| [Pi](https://github.com/mariozechner/pi-coding-agent) | `npm i -g @mariozechner/pi-coding-agent` | Multi-provider auth, conversational |

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

## Features

### Progress streaming

Watch your agent work in real time. See tool calls, file changes, and elapsed time as they happen.

### Interactive permissions (Claude Code)

When Claude Code needs to run a tool, Untether shows **Approve / Deny / Pause & Outline Plan** buttons in Telegram. Routine tools (Read, Grep, Glob) are auto-approved. Dangerous operations require your explicit approval with a diff preview.

### Plan mode

Toggle plan mode per chat with `/planmode`. Claude outlines its approach before making changes. Choose between:

- **on** — full plan mode with manual approval
- **auto** — plan mode with auto-approved transitions
- **off** — no plan phase

### Projects and worktrees

Register repos with `untether init myproject`, then target them from chat:

> /myproject @feat/new-api add the endpoint

Each branch runs in an isolated git worktree. Multiple projects and branches can run in parallel.

### Cost and usage tracking

```toml
[footer]
show_api_cost = false           # hide API cost line (default: true)
show_subscription_usage = true  # show 5h/weekly window usage (default: false)

[cost_budget]
enabled = true
max_cost_per_run = 2.00
max_cost_per_day = 10.00
```

See subscription usage or API costs in the progress footer. Use `/usage` for a detailed breakdown. Budget alerts fire at configurable thresholds, and can optionally auto-cancel runs.

### Conversation modes

| Mode | Best for | How it works |
|------|----------|-------------|
| **Assistant** | Day-to-day use | Ongoing chat with auto-resume. `/new` to start fresh. |
| **Workspace** | Teams and multi-project | Forum topics bound to repos and branches. |
| **Handoff** | Terminal-first workflow | Reply-to-continue with resume lines you can paste into terminal. |

### More features

- **Voice notes** — dictate tasks, Untether transcribes and sends to the agent
- **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

## 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) |

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:

```toml
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](https://untether.cc/reference/config/) for all options.

## 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](https://untether.cc/reference/runners/claude/runner/) — permission modes, plan mode, cost tracking, interactive approvals
- [Codex guide](https://untether.cc/reference/runners/codex/exec-json-cheatsheet/) — profiles, extra args, exec mode
- [OpenCode guide](https://untether.cc/reference/runners/opencode/runner/) — model selection, 75+ providers, local models
- [Pi guide](https://untether.cc/reference/runners/pi/runner/) — multi-provider auth, model and provider selection
- [Configuration reference](https://untether.cc/reference/config/) — full walkthrough of `untether.toml`
- [Troubleshooting guide](https://untether.cc/how-to/troubleshooting/) — common issues and solutions

## Documentation

Full documentation is available at **[untether.cc](https://untether.cc/)**.

- [Install and onboard](https://untether.cc/tutorials/install/) — setup wizard walkthrough
- [First run](https://untether.cc/tutorials/first-run/) — send your first task
- [Projects and branches](https://untether.cc/tutorials/projects-and-branches/) — multi-repo workflows
- [Multi-engine workflows](https://untether.cc/tutorials/multi-engine/) — switching between agents
- [Architecture](https://untether.cc/explanation/architecture/) — how the pieces fit together

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and guidelines.

## Acknowledgements

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

## Licence

[MIT](LICENSE)
