Multi-engine workflows¶

This tutorial shows you how to use different agents for different tasks and set up defaults so you don't have to think about it.

What you'll learn: Engine directives, persistent defaults, and when to use which agent.

Why multiple engines?¶

Different agents have different strengths:

You might want Codex for quick tasks and Claude for deep work—without manually specifying every time.

1. One-off engine selection¶

Prefix any message with /<engine>:

The engine only applies to that message. The response will have a resume line for that engine:

When you reply, Takopi sees claude --resume and automatically uses Claude—you don't need to repeat /claude.

2. Engine + project + branch¶

Directives combine. Order doesn't matter:

Or:

Both do the same thing: run Claude in the happy-gadgets project on the feat/di branch.

3. Set a default engine for a chat¶

Use /agent set to change the default for the current scope:

Response:

Now all new conversations in this chat use Claude (unless you explicitly override with /codex).

Check the current default:

Example response:

Clear it:

Response:

4. Defaults in topics¶

If you use Telegram forum topics, /agent set applies per-topic:

Each topic remembers its own default.

5. Per-project defaults¶

Set a default engine in your project config:

[projects.happy-gadgets]
path = "~/dev/happy-gadgets"
default_engine = "claude"

Now /happy-gadgets tasks default to Claude, even if your global default is Codex.

6. Selection precedence¶

When Takopi picks an engine, it checks (highest to lowest):

1. Resume line — replying to claude --resume ... uses Claude
2. Explicit directive — /codex ... uses Codex
3. Topic default — /agent set in this forum topic
4. Chat default — /agent set in this chat
5. Project default — default_engine in project config
6. Global default — default_engine at the top of takopi.toml

This means: resume lines always win, then explicit directives, then the most specific default applies.

7. Practical patterns¶

Pattern: Quick questions vs. deep work

# Global default for quick stuff
default_engine = "codex"

# Project default for complex codebase
[projects.backend]
path = "~/dev/backend"
default_engine = "claude"

Simple messages go to Codex. /backend messages go to Claude.

Pattern: Topic per engine

Create forum topics like "Claude work" and "Codex tasks", then /agent set in each:

Drag tasks to the right topic and the engine follows.

Pattern: Override for specific tasks

Even with defaults, you can always override:

Works regardless of what the default is.

Recap¶

You're done!¶

That's the end of the tutorials. You now know how to:

• ✅ Install and configure Takopi
• ✅ Send tasks and continue conversations
• ✅ Cancel runs mid-flight
• ✅ Target repos and branches from chat
• ✅ Use multiple engines effectively

Where to go next¶

Want to do something specific?

• Enable forum topics for organized threads
• Transfer files between Telegram and your repo
• Use voice notes to dictate tasks
• Schedule tasks to run later

Want to understand the internals?

• Architecture — how the pieces fit together
• Routing and sessions — how context resolution works
• Specification — normative behavior contracts

Need exact syntax?

• Commands & directives
• Configuration