takopi: a Telegram bridge that puts Codex, Claude Code, opencode and pi in a chat window

The gap takopi fills between a CLI agent and a phone

Codex, Claude Code, opencode and pi are terminal programs. They expect a shell, a working directory and a keyboard. That is fine at a desk and awkward everywhere else. takopi is a Telegram bot that forwards chat messages to one of those engines running on your own machine and streams the output back into the conversation. The README frames the scope plainly: "telegram bridge for codex, claude code, opencode, pi. manage multiple projects and worktrees, stream progress, and resume sessions anywhere." The audience is narrow and specific. You need at least one of those four engines already installed and resolvable on PATH. You need a Python 3.14 or later interpreter, since the requirements section lists python 3.14+ and the install path goes through uv. You need an Anthropic or OpenAI subscription, because the feature list says takopi "works with existing anthropic and openai subscriptions" rather than requiring separate API keys. If any of those three preconditions is false, the project is not for you. It is a remote control, not an agent. The intelligence still comes from the CLI you already pay for.

Chat message in, engine subprocess out: the data flow

The architecture visible in the README is a relay. A Telegram message arrives, takopi decides which project and which worktree it belongs to, spawns or resumes an engine session in that directory, and streams events back to the chat. Progress streaming covers "commands, tools, file changes, elapsed time", which suggests the bridge parses the engine's own event output rather than scraping a terminal. Engine selection is explicit: prefix a message with /codex, /claude, /opencode or /pi. Routing is by project name and optionally by branch. The README gives this example: `/happy-gadgets @feat/memory-box freeze artifacts forever`. That runs the agent in a dedicated git worktree for the branch feat/memory-box, so two branches of the same repository can be worked on at once without a checkout dance. Group chats are mapped to contexts too, via Telegram topics: "map group topics to repo/branch contexts." The queueing model is per agent session, with steering and cancel controls documented for Codex specifically. Resume is stateless by design. The session state lives in the engine, and takopi hands you a line you can copy out of the chat and paste into a terminal to continue the same conversation locally. That is the most interesting decision in the whole project: the bridge does not try to own session state.

Installing takopi and running the setup wizard

Installation is two commands, both from the README. First uv, if you do not have it: `curl -LsSf https://astral.sh/uv/install.sh | sh`. Then the tool itself: `uv tool install -U takopi`. The -U flag means upgrades are the same command, which matters for maintenance. Note the version jump implied by the release list: v0.23.2, v0.23.3 and v0.23.4 all landed within ten days in May 2026. Expect to re-run that install line often. Before any of that, confirm an engine binary is on PATH, since the requirements are explicit that at least one of codex, claude, opencode or pi must be there. Python 3.14+ is also required and can be provisioned with `uv python install 3.14`. Then run `takopi` with no arguments and the setup wizard takes over. According to the README it walks through four steps: create a bot token via @BotFather, pick a workflow, connect your chat, and choose a default engine. The three workflows are assistant (ongoing chat with auto-resume, marked recommended), workspace (forum topics bound to repos and branches) and handoff (reply-to-continue with terminal resume lines). Each one preconfigures conversation mode, topics and resume lines, so the choice is not cosmetic. Project registration is `takopi init happy-gadgets`, after which `/happy-gadgets <instruction>` works from any chat. Settings are inspectable and editable from the shell with `takopi config list`, `takopi config get` and `takopi config set`.

Where takopi stops being the right tool

The bot token is the weak point, and it is worth stating without hedging. Anyone who can send messages to that bot can, subject to the routing rules, cause an agent to run in one of your registered repositories. takopi has no visible permission layer in the material supplied: no allowlist of Telegram user IDs, no approval prompt before a file write, no sandbox. The only gate described is knowing the project name. In a private one-to-one chat that is probably acceptable. In a group chat with topics mapped to repos, the blast radius is everyone in the group. The second limitation is platform. Nothing in the README mentions Windows, and between uv, git worktrees and four Unix-oriented CLIs, the practical target is macOS or Linux. Third, the project is young and moving fast. Three releases in ten days is a signal about pace, and the README itself defers the hard parts outward, pointing to takopi.dev for "configuration, worktrees, topics, file transfer, and more". That means the repository README is not a complete operations manual. File transfer in particular, described only as "send files to the repo or fetch files/dirs back", is not specified here in terms of size limits, path restrictions or what happens if you fetch a directory with symlinks in it. If your use case depends on that feature, read the site before committing.

How takopi differs from running the agent CLIs directly or over SSH

The obvious alternative is not another Telegram bridge. It is SSH plus tmux, or a self-hosted web terminal such as ttyd. The difference is in what each one optimises for. SSH gives you a full shell, so anything the CLI can do, you can do, including interactive prompts and TUI redraws. takopi gives up the shell and keeps a message queue. In exchange you get things a terminal cannot offer over a flaky mobile connection: Telegram voice notes as input, scheduled messages to kick off work later, and a persistent scrollback that survives your phone locking. The resume-line design is what makes this trade tolerable. Because the session is not trapped inside takopi, you can start a long refactor from a phone and finish it in a terminal by pasting the line the bot gave you. A tmux session does not cross that boundary as cleanly. The other alternative is a hosted agent product with a web UI. Those remove the setup work but also remove the subscription-reuse property and the local worktree model. takopi's bet is that engineers already have the CLIs, already have the subscriptions, and only lack a transport.

Plugins, maintenance and the MIT licence

takopi supports "entrypoint-based plugins for engines, transports, and commands", with two documents cited in the README: docs/how-to/write-a-plugin.md and docs/reference/plugin-api.md. That is the extension path if you want an engine the four built-ins do not cover, or a transport other than Telegram. It also tells you where the maintenance burden sits. Core updates arrive as PyPI releases and are applied with `uv tool install -U takopi`. Plugin updates are yours. The licence is MIT, which is permissive and imposes no copyleft obligation on your own code. The README does not state a licence for the plugin API surface or the documentation, and I have no material on how contributions are governed or whether a CLA exists. Treat the MIT identifier as covering the repository as published and nothing more. On upgrade cost: the release cadence suggests breaking changes are plausible at the 0.x version level, and the config commands (`takopi config list`, `takopi config get`, `takopi config set`) exist precisely so you can inspect what a new version expects before it surprises you. Run `takopi config list` after each upgrade and diff the output against what you had.

Editorial conclusion

Adopt takopi if you already run codex, claude, opencode or pi on a machine you control, you keep an Anthropic or OpenAI subscription rather than API keys, and you want to start or continue agent sessions from Telegram. Do not adopt it if you need a hosted service, a browser UI, Windows support, or if you cannot accept that the bot token grants chat participants the ability to edit files in your repositories. Verify first that Python 3.14 is available on the host, that at least one engine binary resolves on PATH, and that you are comfortable with where takopi writes its configuration before you paste a BotFather token into the wizard.

Official sources

1. banteg/takopi on GitHub
2. License: MIT
3. Project website
4. README
5. Releases