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¶

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¶

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