# 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](../tutorials/index.md)**.  
If you need exact options and defaults, use **[Reference](../reference/index.md)**.

## Daily use

- [Switch engines](switch-engines.md) (`/codex`, `/claude`, `/opencode`, `/pi`)
- [Projects](projects.md) (register repos + run from anywhere)
- [Worktrees](worktrees.md) (run work on `@branch` without switching your main checkout)
- [Route by chat](route-by-chat.md) (dedicated chats per project)
- [Topics](topics.md) (forum threads bound to repo/branch + auto-resume)
- [Chat sessions](topics.md#chat-sessions) (auto-resume without replying)

## Messaging extras

- [Voice notes](voice-notes.md) (transcribe and run)
- [File transfer](file-transfer.md) (`/file put` and `/file get`)
- [Schedule tasks](schedule-tasks.md) (Telegram scheduled messages)

## Extending Takopi

- [Write a plugin](write-a-plugin.md) (engines, transports, commands)
- [Add a runner](add-a-runner.md) (implement a new engine backend)
- [Dev setup](dev-setup.md) (run from source, tests, linting, type checks)

## Debugging and operations

- [Troubleshooting](troubleshooting.md) (`--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](../reference/index.md)**.
- If your question starts with “**Why is it designed this way?**” → go to **[Explanation](../explanation/index.md)**.