Telegram-As-Control-Plane-For-Local-Agents
Key takeaways
- Takopi bridges local coding agents to Telegram so users can run agent tasks in repositories via chat and receive streamed progress and completion notifications.
- Takopi offers three workflows—assistant, workspace, and handoff—selected during setup and changeable later via configuration or re-onboarding.
- Takopi's adoption hinges on the reliability of streaming updates and on seamless handoff back to the terminal.
- Takopi is installed via uv, stores configuration at ~/.takopi/takopi.toml, and can rerun onboarding using takopi --onboard.
- In workspace mode, Telegram forum topics are bound to projects and branches, and each topic has its own context and Git worktree to enable parallel workstreams.
Sections
Telegram-As-Control-Plane-For-Local-Agents
The core delta is an interaction/transport shift: tasks and continuation happen in Telegram while execution remains on the user’s machine. This implies a split architecture (chat control plane + local execution plane) with per-message engine routing, aiming to make agent supervision possible away from a terminal while preserving local-repo execution.
- Takopi bridges local coding agents to Telegram so users can run agent tasks in repositories via chat and receive streamed progress and completion notifications.
- Takopi uses Telegram messages as its control plane: a user sends a task, Takopi runs the chosen agent locally in the target repo, streams progress back, and the user can continue by replying.
- Telegram was chosen because it is available across devices and its Bot API supports features such as inline keyboards, forum topics, and voice notes.
- Takopi runs coding agents installed on the user's computer, including Codex, Claude Code, OpenCode, and Pi, which are typically installed via npm.
- Engine selection can be overridden per message by prefixing the engine name, replies continue routing to that engine, and /agent set configures the default engine for a chat.
Workflow-Modes-And-State-Management
Takopi differentiates workflows by how conversational state and continuity are handled: persistent chat context (assistant), topic/branch isolated contexts (workspace), and intentionally constrained continuity with explicit reply-based linkage (handoff). The mental-model update is that 'agent UX' is treated as a set of state/continuity policies rather than a single chat pattern.
- Takopi offers three workflows—assistant, workspace, and handoff—selected during setup and changeable later via configuration or re-onboarding.
- In assistant mode, messages continue an ongoing conversation and the /new command starts a fresh context.
- In workspace mode, Telegram forum topics are bound to projects and branches, and each topic has its own context and Git worktree to enable parallel workstreams.
- In handoff mode, each message is independent unless the user explicitly replies, and Takopi provides resume lines that can be copied back into the terminal for explicit control.
Economic-And-Adoption-Claims
The corpus asserts (without internal validation) that Takopi adds no incremental cost beyond existing agent subscriptions, and frames adoption as contingent on reliable streaming and smooth terminal handoff. Voice-note transcription is presented as an input expansion but dependency and performance details are unspecified.
- Takopi's adoption hinges on the reliability of streaming updates and on seamless handoff back to the terminal.
- Takopi supports Telegram voice notes by transcribing audio into text and running it as a normal task when transcription is enabled.
- Takopi relies on the user's existing ChatGPT and Claude subscriptions for underlying agents and does not add extra cost beyond those services.
- A common failure mode for current coding agents is being trapped behind an SSH terminal session, which leads to lost context and hard-to-follow scrollback when the user steps away.
Onboarding-And-Project-Addressing-Layer
The tool includes a guided Telegram bot setup, chat binding via chat_id capture, and agent auto-detection, plus named project routing so a user can target repos without being in the right directory. This indicates the product is designed around reducing setup friction and enabling remote repo/task addressing.
- Takopi is installed via uv, stores configuration at ~/.takopi/takopi.toml, and can rerun onboarding using takopi --onboard.
- During onboarding, Takopi guides users to create a Telegram bot, select a workflow, connect a chat via /start to capture chat_id, and choose a default engine by scanning installed agents.
- Repositories can be registered as named projects using takopi init, enabling tasks to target them from anywhere via commands like /project-name without changing directories or restarting Takopi.
Parallelism-And-Isolation-Via-Git-Worktrees
Workspace and branch-targeting rely on Git worktrees to isolate concurrent work and avoid switching the primary checkout. The key delta is operational: concurrency is implemented through explicit filesystem/worktree isolation mapped to Telegram topics and/or branch requests.
- In workspace mode, Telegram forum topics are bound to projects and branches, and each topic has its own context and Git worktree to enable parallel workstreams.
- Takopi can run tasks on specific branches without switching by creating a Git worktree per branch request so the main checkout remains untouched and multiple branches can run in parallel.
Watchlist
- Takopi's adoption hinges on the reliability of streaming updates and on seamless handoff back to the terminal.
Unknowns
- How reliable are streamed progress updates and completion notifications in real-world use (delivery failures, latency, reconnect behavior, ordering)?
- What are the concrete security boundaries and threat model (e.g., what data is sent to Telegram, what is stored locally, and how secrets are handled)?
- Does Takopi ever require its own paid plan, and are there any features that require separate API keys or paid third-party services beyond existing agent subscriptions?
- What agents/engines are supported in practice beyond the named examples, and what is the compatibility surface (CLI versions, OS support, failure modes when agents are not installed)?
- How well does the Git worktree concurrency model work operationally (disk usage growth, cleanup behavior, conflicts, integration with existing Git workflows)?