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

• 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