Takopi documentation

Telegram bridge for coding agents (Codex, Claude Code, OpenCode, Pi).

Takopi lets you run an engine CLI in a local repo while controlling it from Telegram: send a task, stream updates, and continue safely (reply-to-continue, topics, or sessions).

Choose your path

• I’m new / I want to get it running

• Start with Tutorials:

  • Install & onboard
  • First run

• I know what I want to do (enable a feature / fix a workflow)

• Use How-to guides:

  • Projects and Worktrees
  • Topics and Route by chat
  • File transfer and Voice notes

• I need exact knobs, defaults, and contracts

• Go straight to Reference:

  • Commands & directives
  • Configuration
  • Specification (normative behavior)

• I’m trying to understand the design

• Read Explanation:
  • Architecture
  • Routing & sessions
  • Plugin system

Quick start

If you just want to see it work end-to-end:

# Install
uv tool install -U takopi

# Configure Telegram + defaults
takopi --onboard

# Run in a repo
cd /path/to/your/repo
takopi

Then open Telegram and send a task to your bot.

Core concepts

• Engine: the CLI that actually does the work (e.g. codex, claude, opencode, pi).
• Project: a named alias for a repo path (so you can run from anywhere).
• Worktree / branch selection: pick where work should happen (@branch).

• Continuation: how Takopi safely “continues” a run:

• reply-to-continue (always available)

• forum topics (thread-bound continuation)
• chat sessions (auto-resume)
• Contract: the stable rules (resume lines, event ordering, rendering expectations) in the Specification and runner contract tests.

For plugin authors

Start here:

• Plugin API — stable takopi.api surface for plugins
• Write a plugin
• Add a runner

If you’re contributing to core:

• Dev setup
• Module map

For LLM agents

Takopi publishes an LLM-oriented index at:

• /llms.txt — curated entrypoints + links to Markdown mirrors
• /llms-full.txt — expanded “single file” context of the most important pages

In the docs, start here:

• Reference: For agents
• Repo map
• Invariants

Where to look when something feels “off”

• “Why didn’t it route to the right repo/branch?” → Context resolution
• “Why didn’t it continue where I left off?” → Commands & directives and Specification
• “Why did Telegram messages behave weirdly?” → Telegram transport
• “Why is it built this way?” → Architecture

Legacy portals

These pages remain as curated pointers to preserve old links:

• User guide
• Plugins
• Developing