Tutorials¶

Tutorials walk you through Takopi step-by-step. Follow them in order if you're new.

If you already know what you want ("enable topics", "use worktrees"), jump to How-to.

Prerequisites¶

Before starting, make sure you have:

• A Telegram account
• Python 3.14+ and uv (install uv)
• At least one agent CLI on your PATH:

You only need one to get started. Takopi auto-detects what's available.

The tutorials¶

1. Install and onboard¶

Set up Takopi, create a Telegram bot, and generate your config.

Time: ~5 minutes

Start here →

2. First run¶

Send your first task, watch it stream, and learn the core loop: run → continue → cancel.

Time: ~10 minutes

Continue →

3. Projects and branches¶

Register a repo as a project so you can target it from anywhere. Run tasks on feature branches without leaving your main worktree.

Time: ~10 minutes

Continue →

4. Multi-engine workflows¶

Use different agents for different tasks. Set defaults per chat or topic.

Time: ~5 minutes

Continue →

What you'll build¶

By the end of these tutorials, you'll have:

~/.takopi/takopi.toml
├── bot_token + chat_id configured
├── default_engine set
└── projects.your-repo registered

And you'll know how to:

• Send tasks from Telegram and watch progress stream
• Continue conversations by replying
• Cancel runs mid-flight
• Target specific repos and branches
• Switch between agents on the fly

After the tutorials¶

• How-to guides — goal-oriented recipes (topics, file transfer, voice notes)
• Reference — exact config keys, commands, and contracts
• Explanation — architecture and design rationale