izackp/takopi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align engine terminology in telegram and docs (#162)

Browse Source
This commit is contained in:
banteg
2026-01-17 13:55:49 +04:00
committed by GitHub
parent 0818e848b3
commit 9d7c6fcd8c
26 changed files with 64 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/explanation/architecture.md
+1 -1
View File
@@ -165,7 +165,7 @@ sequenceDiagram
Command->>RunnerBridge: run_one/run_many (optional)
RunnerBridge->>Telegram: Send progress/final
else Default routing
Bridge->>Bridge: Parse directives<br/>(/engine, /project, @branch)
Bridge->>Bridge: Parse directives<br/>(/&lt;engine-id&gt;, /&lt;project-alias&gt;, @branch)
Bridge->>Bridge: Extract resume token<br/>from reply
Bridge->>Bridge: Resolve worktree<br/>(if @branch)
docs/explanation/plugin-system.md
+1 -1
View File
@@ -72,7 +72,7 @@ This lets you:
## IDs and collisions
Entrypoint names become plugin IDs and appear in user-facing surfaces (CLI subcommands, Telegram commands, `/engine` directives).
Entrypoint names become plugin IDs and appear in user-facing surfaces (CLI subcommands, Telegram commands, `/<engine-id>` directives).
Takopi validates IDs and rejects collisions with reserved names.
Plugin IDs must match:
docs/explanation/routing-and-sessions.md
+1 -1
View File
@@ -27,7 +27,7 @@ Reply-to-continue works even if topics or chat sessions are enabled.
For each message, Takopi:
- parses directive prefixes (`/engine`, `/project`, `@branch`) from the first non-empty line
- parses directive prefixes (`/<engine-id>`, `/<project-alias>`, `@branch`) from the first non-empty line
- attempts to extract a resume token by polling available runners
- if a resume token is found, routes to the matching runner; otherwise uses the configured default engine
docs/how-to/switch-engines.md
+1 -2
View File
@@ -29,7 +29,7 @@ Use `/agent`:
- In normal chats, it affects the whole chat.
- In group chats, only admins can change defaults.
Selection precedence (highest to lowest): resume token → `/engine` directive → topic default → chat default → project default → global default.
Selection precedence (highest to lowest): resume token → `/<engine-id>` directive → topic default → chat default → project default → global default.
## Engine installation
@@ -40,4 +40,3 @@ Takopi shells out to engine CLIs. Install them and make sure they’re on your `
- [Commands & directives](../reference/commands-and-directives.md)
- [Config reference](../reference/config.md)
docs/how-to/topics.md
+3 -3
View File
@@ -1,6 +1,6 @@
# Topics
Topics bind Telegram **forum threads** to a project/branch context. Each topic keeps its own session and default agent, which is ideal for teams or multi-project work.
Topics bind Telegram **forum threads** to a project/branch context. Each topic keeps its own session and default engine, which is ideal for teams or multi-project work.
!!! tip "Workspace workflow"
If you chose the **workspace** workflow during [onboarding](../tutorials/install.md), topics are already enabled. This guide covers advanced topic configuration and usage.
@@ -9,7 +9,7 @@ Topics bind Telegram **forum threads** to a project/branch context. Each topic k
- Keep each thread tied to a repo + branch
- Avoid context collisions in busy team chats
- Set a default agent per topic with `/agent set`
- Set a default engine per topic with `/agent set`
## Requirements checklist
@@ -76,7 +76,7 @@ Note: Outside topics (private chats or main group chats), `/ctx` binds the chat
Use `/new` inside the topic to clear stored sessions for that thread.
## Set a default agent per topic
## Set a default engine per topic
Use `/agent set` inside the topic:
docs/how-to/worktrees.md
+1 -1
View File
@@ -44,7 +44,7 @@ echo ".worktrees/" >> ~/.config/git/ignore
## Context persistence
When project/worktree context is active, Takopi includes a `ctx:` footer in messages.
When you reply, this context carries forward (you usually don’t need to repeat `/project @branch`).
When you reply, this context carries forward (you usually don’t need to repeat `/<project-alias> @branch`).
## Related
docs/how-to/write-a-plugin.md
+3 -1
View File
@@ -24,7 +24,9 @@ mytransport = "mytransport.backend:BACKEND"
mycommand = "mycommand.backend:BACKEND"
```
## Engine backend plugin (runner)
## Engine backend plugin
An engine backend builds a `Runner` via `build_runner(...)`.
Minimal example:
docs/index.md
+1 -1
View File
@@ -68,7 +68,7 @@ Step-by-step guides for new users:
1. [Install & onboard](tutorials/install.md) — set up Takopi and your bot
2. [First run](tutorials/first-run.md) — send a task, watch it stream, continue the conversation
3. [Projects & branches](tutorials/projects-and-branches.md) — target repos from anywhere, run on feature branches
4. [Multi-engine](tutorials/multi-engine.md) — use different agents for different tasks
4. [Multi-engine](tutorials/multi-engine.md) — use different engines for different tasks
## How-to guides
docs/reference/commands-and-directives.md
+3 -3
View File
@@ -8,8 +8,8 @@ Takopi parses the first non-empty line of a message for a directive prefix.
| Directive | Example | Effect |
|----------|---------|--------|
| `/engine` | `/codex fix flaky test` | Select an engine for this message. |
| `/project` | `/happy-gadgets add escape-pod` | Select a project alias. |
| `/<engine-id>` | `/codex fix flaky test` | Select an engine for this message. |
| `/<project-alias>` | `/happy-gadgets add escape-pod` | Select a project alias. |
| `@branch` | `@feat/happy-camera rewind to checkpoint` | Run in a worktree for the branch. |
| Combined | `/happy-gadgets @feat/flower-pin observe unseen` | Project + branch. |
@@ -35,7 +35,7 @@ This line is parsed from replies and takes precedence over new directives.
| Command | Description |
|---------|-------------|
| `/cancel` | Reply to the progress message to stop the current run. |
| `/agent` | Show/set the default agent for the current scope. |
| `/agent` | Show/set the default engine for the current scope. |
| `/model` | Show/set the model override for the current scope. |
| `/reasoning` | Show/set the reasoning override for the current scope. |
| `/trigger` | Show/set trigger mode (mentions-only vs all). |
docs/reference/context-resolution.md
+3 -3
View File
@@ -92,8 +92,8 @@ Takopi parses the first non-empty line of a message for a directive prefix.
Supported directives:
- `/engine` or `/engine@bot`: chooses the engine
- `/project`: chooses a project alias
- `/<engine-id>` or `/<engine-id>@bot`: chooses the engine
- `/<project-alias>`: chooses a project alias
- `@branch`: chooses a git branch/worktree
Rules:
@@ -117,7 +117,7 @@ The `ctx:` line is parsed from replies and takes precedence over new directives.
When a message arrives in a chat whose `chat_id` matches `projects.<alias>.chat_id`,
Takopi defaults the project context to that alias unless a reply `ctx:` or explicit
`/project` directive is present.
`/<project-alias>` directive is present.
In non-topic chats, `/ctx` can bind a chat context. That bound context is treated as
ambient and takes precedence over the default project mapping until cleared.
docs/reference/index.md
+1 -1
View File
@@ -8,7 +8,7 @@ If you’re trying to understand the *why*, use **[Explanation](../explanation/i
## Most-used reference pages
- [Commands & directives](commands-and-directives.md)
- Message prefixes like `/engine`, `/project`, and `@branch`
- Message prefixes like `/<engine-id>`, `/<project-alias>`, and `@branch`
- In-chat commands like `/cancel`, `/new`, `/ctx`, `/file …`, `/topic …`
- [Configuration](config.md)
- `takopi.toml` options and defaults
docs/reference/transports/telegram.md
+1 -1
View File
@@ -65,7 +65,7 @@ To restore “only respond when invoked” behavior, use trigger mode:
Explicit invocation includes any of:
- `@botname` mention in the message.
- `/engine` or `/project_alias` as the first token.
- `/<engine-id>` or `/<project-alias>` as the first token.
- Replying to a bot message.
- Built-in or plugin slash commands (for example `/agent`, `/model`, `/reasoning`, `/file`, `/trigger`).
docs/tutorials/conversation-modes.md
+1 -1
View File
@@ -38,7 +38,7 @@ To pin a project or branch for the chat, use:
`/new` clears the session but keeps the bound context.
Tip: set a default agent for this chat with `/agent set claude`.
Tip: set a default engine for this chat with `/agent set claude`.
## Stateless (reply-to-continue)
docs/tutorials/first-run.md
+3 -3
View File
@@ -19,7 +19,7 @@ Takopi keeps running in your terminal. In Telegram, your bot will post a startup
🐙 takopi is ready
default: codex<br>
agents: codex, claude<br>
engines: codex, claude<br>
projects: none<br>
mode: chat<br>
topics: disabled<br>
@@ -29,7 +29,7 @@ Takopi keeps running in your terminal. In Telegram, your bot will post a startup
The engines/projects list reflects your setup. This tells you:
- Which engine is the default
- Which agents are available (and any missing ones)
- Which engines are available (and any missing ones)
- Which projects are registered
- Which directory Takopi will run in
@@ -131,7 +131,7 @@ If a resume token was already issued (and resume lines are enabled), it will sti
## 7. Try a different engine
Want to use a different agent for one message? Prefix your message with `/<engine>`:
Want to use a different engine for one message? Prefix your message with `/<engine>`:
!!! user "You"
/claude explain the error handling in this codebase
docs/tutorials/install.md
+3 -3
View File
@@ -228,9 +228,9 @@ Once Takopi receives your message:
Takopi scans your PATH for installed agent CLIs:
```
step 4: default agent
step 4: default engine
takopi runs these agents on your computer. switch anytime with /agent.
takopi runs these engines on your computer. switch anytime with /agent.
engine status install command
───────────────────────────────────────────
@@ -239,7 +239,7 @@ takopi runs these agents on your computer. switch anytime with /agent.
opencode ✗ not found npm install -g opencode-ai@latest
pi ✗ not found npm install -g @mariozechner/pi-coding-agent
? choose default agent:
? choose default engine:
❯ codex
claude
```
docs/tutorials/multi-engine.md
+7 -7
View File
@@ -1,14 +1,14 @@
# 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.
This tutorial shows you how to use different engines 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.
**What you'll learn:** Engine directives, persistent defaults, and when to use which engine.
## Why multiple engines?
Different agents have different strengths:
Different engines have different strengths:
| Agent | Good at |
| Engine | Good at |
|-------|---------|
| **Codex** | Fast edits, shell commands, quick fixes |
| **Claude Code** | Complex refactors, architecture, long context |
@@ -65,7 +65,7 @@ Use `/agent set` to change the default for the current scope:
Response:
!!! takopi "Takopi"
chat default agent set to claude
chat default engine set to claude
Now all new conversations in this chat use Claude (unless you explicitly override with `/codex`).
@@ -77,7 +77,7 @@ Check the current default:
Example response:
!!! takopi "Takopi"
agent: claude (chat default)<br>
engine: claude (chat default)<br>
defaults: topic: none, chat: claude, project: none, global: codex<br>
available: codex, claude, opencode, pi
@@ -89,7 +89,7 @@ Clear it:
Response:
!!! takopi "Takopi"
chat default agent cleared.
chat default engine cleared.
## 4. Defaults in topics
docs/tutorials/projects-and-branches.md
+3 -3
View File
@@ -2,7 +2,7 @@
This tutorial shows you how to register repos as projects and run tasks on feature branches without switching directories.
**What you'll learn:** How to target repos from anywhere with `/project`, and run on branches with `@branch`.
**What you'll learn:** How to target repos from anywhere with `/<project-alias>`, and run on branches with `@branch`.
## The problem
@@ -123,7 +123,7 @@ Replies stay on the same branch. Your main checkout is untouched.
## 5. Context persistence
Once you've set a context (via `/project @branch` or by replying), it sticks:
Once you've set a context (via `/<project-alias> @branch` or by replying), it sticks:
!!! user "You"
/happy-gadgets @feat/new-login add tests
@@ -155,7 +155,7 @@ If you mostly work in one repo, set it as the default:
default_project = "happy-gadgets"
```
Now messages without a `/project` prefix go to that repo:
Now messages without a `/<project-alias>` prefix go to that repo:
!!! user "You"
add a health check endpoint