takopi/docs/how-to/index.md

How-to guides

How-to guides are goal-oriented recipes. Pick the task you’re trying to accomplish and follow the steps.

If you’re learning from scratch, start with Tutorials.
If you need exact options and defaults, use Reference.

Daily use

• Switch engines (/codex, /claude, /opencode, /pi)
• Projects (register repos + run from anywhere)
• Worktrees (run work on @branch without switching your main checkout)
• Route by chat (dedicated chats per project)
• Topics (forum threads bound to repo/branch + auto-resume)
• Chat sessions (auto-resume without replying)

Messaging extras

• Voice notes (transcribe and run)
• File transfer (/file put and /file get)
• Schedule tasks (Telegram scheduled messages)

Extending Takopi

• Write a plugin (engines, transports, commands)
• Add a runner (implement a new engine backend)
• Dev setup (run from source, tests, linting, type checks)

Debugging and operations

• Troubleshooting (--debug, common gotchas, “why didn’t it route?”)

Not sure where to go?

• If your question starts with “How do I…” → you’re in the right place.
• If your question starts with “What are the exact options / defaults?” → go to Reference.
• If your question starts with “Why is it designed this way?” → go to Explanation.