Takopi Architecture
Source analysis of takopi (banteg/takopi, v0.23.4, 2026-05-25, ~1k stars, MIT, Python 3.14+). Multi-engine Telegram bridge — Codex / Claude Code / OpenCode / Pi — with worktree-per-branch routing, not just a single-agent bot.
Key Insights
- Plugin overlay pattern: 222 custom lines via Python entry points extend upstream banteg/takopi (~20K installed) without forking - maintains compatibility while adding behavior
- Auto-discovery: Shell script scans filesystem and generates TOML dynamically - zero-config project addition via convention
- Graceful restart via exit(0): /reload exits cleanly, supervisor restarts, entrypoint re-scans - no complex state serialization
- Minimal code surface: Delegates complexity to upstream, only adds routing layer - minimizes maintenance burden
- Container-to-host bridge: /refresh uses dbus to trigger systemd from inside container - bridges bot with host infrastructure
What's Shocking
- 222 lines of custom code on top of 20K upstream: This entire deployment is 4 Python plugins and a 27-line shell script. Everything else -- LLM integration, transport, routing -- is
pip install takopi. You own almost nothing, and that's the point.
- The plugin overlay pattern: Python entry points (
pluggy) extend upstream without forking it. Upstream updates apply cleanly. No fork maintenance, no merge conflicts, no divergence.
- Auto-discovery at startup: The entrypoint script scans a filesystem directory and generates TOML config dynamically. Adding a project = creating a directory. Zero-config project addition via pure convention.
- Graceful restart via exit(0):
/reload calls sys.exit(0). The container supervisor restarts, the entrypoint re-scans projects, and takopi starts fresh. No state serialization, no persistence layer, no complexity.
- Container-to-host bridge via dbus:
/refresh uses dbus to tell the host's systemd to restart a service -- from inside a container. Bridges the bot with host infrastructure without exposing the host.
- Multi-engine bridge, not a bot: Upstream
banteg/takopi dispatches across four engines (Codex, Claude Code, OpenCode, Pi) over one Telegram transport. v0.23.0 switched the default Codex backend to the Codex app-server and reworked progress-state display. Entrypoint-based plugin system extends engines, transports, and commands. Requires Python 3.14+ and at least one engine on PATH.
- Worktree-per-branch multi-tenancy: Group chats and Telegram forum topics map to repo/branch contexts; each branch is a git worktree. Parallel runs with a per-session queue, resumable/stateless sessions, file transfer to/from the repo, voice notes, and scheduled messages. The v0.23.x cluster (mid-to-late May 2026) is mostly Telegram-rendering and routing fixes — forum-topic document routing, callback routing, Claude reasoning-level support, network retry.
- No isolation of its own: Takopi adds NO sandbox — agents run with the underlying engine's own isolation on the host. Multi-tenancy is git-worktree separation per branch, not container or VM. On the isolation spectrum this lands at None → Prompt level; the security boundary is whatever the chosen engine provides.