Takopi: The Telegram Bridge Making AI Agents 10x More Productive

What if your AI coding assistant followed you everywhere? Not just on your laptop, but in your pocket, on the train, whispering progress through Telegram while you grab coffee. Most developers are chained to their terminals, watching claude code or codex churn through tasks like digital watchmen. But what happens when you step away? The session dies. The context evaporates. You're forced to start over, re-explain, re-contextualize.

There's a secret weapon top developers are already using—and it's hiding in plain sight inside your favorite messaging app.

Meet Takopi, the Telegram bridge that transforms how you interact with AI agents. Created by banteg, the legendary Ethereum developer known for pushing boundaries in developer tooling, Takopi doesn't just connect your agents to Telegram. It reimagines the entire workflow: multiple projects running simultaneously, stateless session resumption across devices, real-time progress streaming, and even voice-note control over your coding agents.

If you're still running codex in a single terminal tab, you're leaving massive productivity gains on the table. This is how elite developers orchestrate AI agents in 2025—and why everyone else is about to feel left behind.

What is Takopi?

Takopi ("he just wants to help-pi!" 🐙) is a Telegram bridge specifically architected for modern AI coding agents. It connects powerful terminal-based tools—Codex, Claude Code, OpenCode, and pi—to Telegram's ubiquitous messaging platform, creating a seamless hybrid environment where terminal power meets mobile flexibility.

The project emerges from a critical insight: AI agents are becoming collaborative partners, not just tools, yet our interfaces remain stubbornly desktop-bound. Banteg recognized that developers don't just code at desks—they think in transit, review progress between meetings, and need to intervene when inspiration strikes at 11 PM from their phones.

Takopi solves this by treating Telegram as a first-class interface, not an afterthought. Unlike simple webhook notifications, it builds a sophisticated conversation layer with three distinct workflows (Assistant, Workspace, Handoff), git worktree integration for parallel development, and even file transfer capabilities. The "stateless resume" feature is particularly ingenious—your agent sessions become location-independent artifacts you can pick up from any device, any terminal, any time.

The tool is trending now because it arrives at a perfect inflection point: AI agents have matured enough to run autonomously, yet lack the mobility layer developers desperately need. With existing Anthropic and OpenAI subscriptions working out of the box, Takopi removes every friction point for adoption.

Key Features That Transform Your Workflow

Multi-Project & Worktree Orchestration

Takopi shatters the single-session limitation. Work on multiple repositories and branches simultaneously through git worktrees—each branch becomes an isolated workspace. Target specific projects with intuitive commands like /happy-gadgets and branch-specific contexts with @feat/memory-box syntax.

Stateless Session Resumption

This is where Takopi outsmarts every alternative. Sessions aren't trapped in terminal buffers—they're resumable artifacts. Continue conversations directly in Telegram chat, or copy a "resume line" to seamlessly transfer context to any terminal. Your agent's state becomes as portable as a URL.

Real-Time Progress Streaming

Watch your agents work in exquisite detail: commands executed, tools invoked, files modified, elapsed time tracked. All streamed directly to your Telegram interface. No more blind trust—full observability in your pocket.

Parallel Execution with Queue Management

Run multiple agent sessions concurrently with per-session queues. Codex steering and cancel controls give you surgical precision over autonomous execution. Start a long-running refactor, queue up documentation generation, and review results—all without blocking.

Native Telegram Integration

Voice notes become commands. Scheduled messages trigger batch operations. Group chats with topic threads map to repository contexts. File transfers flow bidirectionally between Telegram and your project directories. This isn't a bridge—it's deep ecosystem integration.

Zero-Friction Setup

Works with existing subscriptions. No API key juggling. The setup wizard handles bot creation, workflow selection, and engine configuration in minutes.

Real-World Use Cases Where Takopi Dominates

1. The Commuting Architect

You're reviewing a complex system redesign when your train arrives. Instead of killing the session, you receive streaming progress updates on Telegram. Spot an issue? Send a voice note correction from the platform. Resume seamlessly at your desk without losing context.

2. Multi-Repository Maintenance

Maintaining five microservices with interdependent changes? Initialize each with takopi init and orchestrate parallel agent sessions across worktrees. Monitor all streams in organized Telegram topics, intervene precisely when needed. One human, many agents, zero chaos.

3. On-Call Incident Response

Production issue at 2 AM? From bed, trigger /claude analyze recent commits via Telegram, receive file transfers of relevant logs, and guide remediation through voice messages. The session resume line lets your morning shift pick up exactly where you left off.

4. Collaborative Code Review

Map group chat topics to pull request branches. Team members drop @feat/auth-refactor mentions to spawn isolated worktree agents. Progress streams to dedicated topics. Asynchronous, transparent, perfectly organized.

5. Long-Running Autonomous Tasks

Kick off a comprehensive test suite migration, queue documentation generation behind it, and schedule status checks via Telegram's scheduled messages. True fire-and-forget automation with human oversight always available.

Step-by-Step Installation & Setup Guide

Prerequisites

Takopi requires modern tooling. First, install uv, the blazing-fast Python package manager:

# Install uv (the modern Python toolchain)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Python 3.14+ (Takopi rides the bleeding edge)
uv python install 3.14

Ensure at least one AI engine is available on your PATH:

# Verify your preferred engine
which codex    # OpenAI Codex CLI
which claude   # Anthropic Claude Code
which opencode # OpenCode
which pi       # Pi agent

Installation

With uv, installation is effortlessly clean:

# Install Takopi as a global tool (auto-updates with -U flag)
uv tool install -U takopi

The -U flag ensures you always receive the latest version on subsequent updates.

Interactive Setup Wizard

Launch Takopi and let the wizard handle configuration:

# Start the setup process
takopi

The wizard guides you through four critical steps:

1. Bot Token Creation: Automatically directs you to @BotFather for secure Telegram bot registration
2. Workflow Selection: Choose your operational mode (detailed below)
3. Chat Connection: Link your personal or group chat
4. Default Engine: Set your primary AI agent (codex, claude, opencode, or pi)

Workflow Configuration

Your workflow choice fundamentally shapes the experience:

Recommendation: Start with Assistant for immediate productivity gains.

Project Registration

Navigate to your repository and initialize:

cd ~/dev/happy-gadgets
takopi init happy-gadgets

This creates the mapping that lets you target this project from anywhere with /happy-gadgets <command>.

REAL Code Examples from Takopi

Let's examine actual patterns from the repository, demonstrating how Takopi transforms theoretical features into practical power.

Example 1: Basic Session Initialization

The simplest possible start—yet it unlocks everything:

# Navigate to your project directory
cd ~/dev/happy-gadgets

# Launch Takopi (triggers setup wizard on first run, session on subsequent)
takopi

What's happening here? Takopi detects your project context, establishes the Telegram bridge, and prepares to receive commands. On first run, the wizard activates. Thereafter, this becomes your session anchor point—the place where terminal and Telegram synchronize.

After launching, simply send a message to your bot. The magic prefix system lets you dynamically select engines:

/codex refactor the authentication module to use JWT tokens
/claude explain why this recursive function stack overflows
/openerate generate comprehensive API documentation
/pi optimize these database queries for N+1 elimination

Pro insight: The prefix isn't just selection—it's context switching. Different engines excel at different tasks. Codex for implementation, Claude for analysis, pi for optimization. Takopi makes this polymorphism effortless.

Example 2: Project-Targeted Execution with Branch Worktrees

This is where Takopi's architecture shines—sophisticated git worktree management through simple syntax:

# Register your project (one-time setup)
takopi init happy-gadgets

# From anywhere on your system, target this project
/happy-gadgets hard reset the timeline

# Execute on a specific branch worktree with @ syntax
/happy-gadgets @feat/memory-box freeze artifacts forever

Deep dive into the mechanics:

The @feat/memory-box syntax triggers Takopi's worktree engine. Behind the scenes:

1. Branch Detection: Takopi identifies feat/memory-box in your repository
2. Worktree Creation: If absent, it spawns a linked worktree (not a clone—a lightweight git reference)
3. Context Isolation: The agent operates in this isolated directory, preserving your main working tree
4. Execution: The command runs with full branch context, including uncommitted changes specific to that worktree

This is game-changing for parallel development. Work on a hotfix in main, a feature in feat/auth, and experimental spike in spike/graphql—simultaneously, without git stash gymnastics, all orchestrated through Telegram.

Example 3: Configuration Inspection and Modification

Takopi exposes fine-grained configuration control:

# List all current configuration values
takopi config list

# Retrieve specific settings
takopi config get default_engine
takopi config get workflow_mode

# Modify behavior on-the-fly
takopi config set default_engine claude
takopi config set workflow_mode workspace

Why this matters: Configuration isn't buried in dotfiles or environment variables. It's discoverable, inspectable, and mutable through a consistent CLI interface. This enables:

• Scripted environment setup: Automate team onboarding with config sets
• Workflow experimentation: Rapidly switch between assistant and workspace modes
• Debugging: Quickly verify expected configuration state

The list subcommand reveals the complete configuration surface, eliminating guesswork about available options.

Example 4: File Transfer Operations

Bidirectional file movement bridges the Telegram-mobile and terminal-desktop divide:

# In Telegram: send a file to your bot
# Takopi receives it into the active project's repository

# Request files or directories back
/files src/utils/auth.js
/dirs src/components

Implementation insight: File transfers leverage Telegram's robust file handling (up to 2GB per file) while maintaining project context awareness. Send a screenshot of an error from your phone, have the agent analyze it. Request generated artifacts back to review on mobile. The boundary between devices dissolves.

Advanced Usage & Best Practices

Engine Polymorphism Strategy

Don't settle for one agent. Configure multiple engines and task-type optimize:

# Set defaults per project context
takopi config set default_engine codex      # For implementation-heavy projects
takopi config set default_engine claude     # For analysis and debugging tasks

Override dynamically with prefixes when the specific task demands different capabilities.

Topic-Driven Team Workflows

In Workspace mode, map Telegram forum topics to architectural boundaries:

• #frontend → React components, CSS modules
• #backend → API endpoints, database migrations
• #infrastructure → Terraform, Docker configurations

Each topic becomes an isolated conversation context with dedicated worktree support.

Scheduled Message Automation

Leverage Telegram's native scheduling for time-shifted agent orchestration:

1. Compose /codex run full test suite && generate coverage report
2. Schedule for 6 AM
3. Review results with coffee

Stateless Resume Hygiene

Always copy resume lines to your notes system (Notion, Obsidian). These become portable session identifiers—paste into any terminal, anywhere, to reconstruct exact context.

Plugin Ecosystem Exploration

Takopi's entrypoint-based plugin architecture supports custom engines, transports, and commands. Review the plugin documentation to extend for proprietary tools or internal workflows.

Comparison with Alternatives

Verdict: Takopi occupies a unique position—terminal power with mobile flexibility, multi-engine freedom with single-interface simplicity. No alternative combines this depth of agent integration with Telegram's ubiquity.

Frequently Asked Questions

What Python version does Takopi require?

Takopi requires Python 3.14+, reflecting its position on the cutting edge. Install via uv python install 3.14 for clean version management.

Can I use my existing Anthropic or OpenAI subscription?

Absolutely. Takopi works with your existing subscriptions—no additional API costs or separate billing. It simply orchestrates the CLI tools you've already configured.

Is Takopi secure for proprietary code?

Takopi operates locally, using your installed engines. Code doesn't route through third-party servers—only progress metadata and file transfers traverse Telegram's infrastructure. For maximum security, run your own Telegram MTProto proxy.

How does session resumption actually work?

Takopi captures conversation state and working directory context into portable resume tokens. These tokens encode the exact position in an agent session, allowing reconstruction in any environment with matching engine access.

Can multiple team members interact with the same agent session?

In Workspace workflow with group topics, yes—team members can observe streams and contribute via reply threads. For exclusive control, Handoff workflow ensures single-operator semantics.

What happens if my phone dies mid-session?

Nothing is lost. The agent continues executing (or pauses based on configuration). Grab any device with Telegram, locate the resume line, and continue seamlessly. Stateless design means device failure is irrelevant.

How do I extend Takopi for custom internal tools?

Takopi's plugin system uses Python entrypoints. Implement the plugin API to add custom engines, alternative transports (Discord, Slack), or domain-specific commands.

Conclusion: Your Agents Deserve Freedom

Takopi represents more than convenience—it's a fundamental reimagining of human-agent collaboration. By liberating AI coding assistants from terminal captivity, banteg has created something rare: a tool that respects both the power of local development and the reality of modern, mobile lives.

The combination of stateless resumption, git worktree orchestration, and native Telegram integration solves problems you didn't realize were costing you hours weekly. The ability to start a complex codex session at your desk, monitor progress from a coffee shop, and resume from a colleague's terminal isn't luxury—it's the new baseline for serious agent-driven development.

If you're still running agents in single terminal tabs, you're experiencing the equivalent of dial-up in a fiber world. The elite developers already know: mobility and continuity multiply agent effectiveness exponentially.

Stop letting your best ideas escape because you stepped away from your keyboard. Give your agents the freedom to follow you anywhere.

👉 Install Takopi now and transform how you orchestrate AI development.

He just wants to help-pi. Let him. 🐙

For advanced configuration, worktree strategies, topic management, and plugin development, visit takopi.dev.