takopi/docs/index.md

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

- :lucide-sparkles:{ .lg } **I’m new / I want to get it running**

---

Start with [Tutorials](tutorials/index.md).

- [Install & onboard](tutorials/install-and-onboard.md)
- [First run](tutorials/first-run.md)

• :lucide-compass:{ .lg } I know what I want to do

  ---

  Use How-to guides.

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

• :lucide-book:{ .lg } I need exact knobs, defaults, and contracts

  ---

  Go straight to Reference.

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

• :lucide-lightbulb:{ .lg } 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

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