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

feat: onboarding overhaul, persona-based setup (#132)

Browse Source
This commit is contained in:
banteg
2026-01-15 03:28:37 +04:00
committed by GitHub
parent a1a2714c01
commit ffae80dce7
32 changed files with 1870 additions and 445 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tutorials/conversation-modes.md
+88
View File
@@ -0,0 +1,88 @@
# Conversation modes
Takopi can handle follow-up messages in two ways: **chat mode** (auto-resume) or **stateless** (reply-to-continue). Pick the one that matches how you want Telegram to feel.
## Quick pick
- **Choose chat mode** if you want a normal chat flow where new messages continue the same thread.
- **Choose stateless** if you want every message to start clean unless you explicitly reply.
## Chat mode (auto-resume)
**What it feels like:** a normal chat assistant.
!!! user "You"
explain what this repo does
!!! takopi "Takopi"
done · codex · 8s
...
!!! user "You"
now add tests
Takopi treats the second message as a continuation. If you want a clean slate, use:
!!! user "You"
/new
Tip: set a default agent for this chat with `/agent set claude`.
## Stateless (reply-to-continue)
**What it feels like:** every message is independent until you reply.
!!! user "You"
explain what this repo does
!!! takopi "Takopi"
done · codex · 8s
...
codex resume abc123
To continue the same session, **reply** to a message with a resume line:
!!! takopi "Takopi"
done · codex · 8s
!!! user "You"
now add tests
## Where to set it
Onboarding will ask you, or you can set it in config:
```toml
[transports.telegram]
session_mode = "chat" # or "stateless"
show_resume_line = false # optional, see below
```
## Resume lines in chat mode
If you enable chat mode (or topics), Takopi can auto-resume, so you can hide resume lines for a cleaner chat.
Resume lines are still shown when no project context is set, so replies can branch there.
If you prefer always-visible resume lines, set:
```toml
[transports.telegram]
show_resume_line = true
```
## Reply-to-continue still works
Even in chat mode, replying to a message with a resume line takes precedence and branches from that point.
## Related
- [Routing and sessions](../explanation/routing-and-sessions.md)
- [Chat sessions](../how-to/chat-sessions.md)
- [Forum topics](../how-to/topics.md)
- [Commands & directives](../reference/commands-and-directives.md)
## Next
Now that you know which mode you want, move on to your first run:
[First run →](first-run.md)
docs/tutorials/first-run.md
+26 -21
View File
@@ -21,6 +21,9 @@ Takopi keeps running in your terminal. In Telegram, your bot will post a startup
default: codex<br>
agents: codex, claude<br>
projects: none<br>
mode: chat<br>
topics: disabled<br>
resume lines: hidden<br>
working in: /Users/you/dev/your-project
The engines/projects list reflects your setup. This tells you:
@@ -76,7 +79,16 @@ That last line is the **resume line**—it's how Takopi knows which conversation
## 5. Continue the conversation
To follow up, **reply** to the bot's message:
How you continue depends on your mode.
**If you're in chat mode:** just send another message (no reply needed).
!!! user "You"
now add tests for the API
Use `/new` any time you want a fresh thread.
**If you're in stateless mode:** **reply** to a message that has a resume line.
!!! takopi "Takopi"
done · codex · 11s · step 5
@@ -84,25 +96,14 @@ To follow up, **reply** to the bot's message:
!!! user "You"
what command line arguments does it support?
Takopi extracts the resume token from the message you replied to and continues the same agent session. The agent remembers everything from before.
Takopi extracts the resume token from the message you replied to and continues the same agent session.
!!! takopi "Takopi"
done · codex · 47s · step 11
!!! tip "Reply-to-continue still works in chat mode"
If resume lines are visible, replying to any older message branches the conversation from that point.
Use `show_resume_line = true` if you want this behavior all the time.
CLI Args
- Global/auto-router (when you run just takopi): --version, --final-notify/--no-final-notify, --onboard/--no-onboard, --transport <id>, --debug/--no-debug. This is the same option set used by engine subcommands.
- init [alias]: optional positional alias, plus --default to set the project as default_project.
- chat-id: --token <bot_token>, --project <alias> to store a captured chat id into the project config.
- plugins: --load/--no-load to validate plugin imports.
- Engine subcommands: one per engine id; built-ins are codex, claude, opencode, pi, plus any plugin engines. Each accepts --final-notify, --onboard, --transport, --debug.
If you want, I can also summarize takopi --help output verbatim for your local build.
codex resume 019bb89b-1b0b-7e90-96e4-c33181b49714
!!! tip "You can reply to any message with a resume line"
The resume line doesn't have to be in the most recent message. Reply to any earlier message to "branch" the conversation from that point.
!!! tip "Reset with /new"
`/new` clears stored sessions for the current chat or topic.
## 6. Cancel a run
@@ -139,6 +140,9 @@ This uses Claude Code for just this message. The resume line will show `claude -
Available prefixes depend on what you have installed: `/codex`, `/claude`, `/opencode`, `/pi`.
!!! tip "Set a default engine"
Use `/agent set claude` to make this chat (or topic) use Claude by default. Run `/agent` to see what's set.
## What just happened
Key points:
@@ -147,7 +151,7 @@ Key points:
- The agent streams JSONL events (tool calls, progress, answer)
- Takopi renders these as an editable progress message
- When done, the progress message is replaced with the final answer
- The resume line lets you continue the conversation
- Chat mode auto-resumes; resume lines let you reply to branch
## The core loop
@@ -156,7 +160,8 @@ You now know the three fundamental interactions:
| Action | How |
|--------|-----|
| **Start** | Send a message to your bot |
| **Continue** | Reply to any message with a resume line |
| **Continue** | Chat mode: send another message. Stateless: reply to a resume line. |
| **Reset** | `/new` |
| **Cancel** | Tap **cancel** on a progress message |
Everything else in Takopi builds on this loop.
@@ -177,7 +182,7 @@ Check that Takopi is still running in your terminal. You should also see a start
**Resume doesn't work (starts a new conversation)**
Make sure you're **replying** to a message, not sending a new one. The reply must be to a message that contains a resume line.
Make sure you're **replying** to a message that contains a resume line. If you hid resume lines (`show_resume_line = false`), turn them on or use chat mode to continue by sending another message.
## Next
docs/tutorials/index.md
+13 -4
View File
@@ -31,7 +31,15 @@ Set up Takopi, create a Telegram bot, and generate your config.
[Start here →](install-and-onboard.md)
### 2. First run
### 2. Conversation modes
Decide how Takopi should handle follow-up messages: chat mode or reply-to-continue.
**Time:** ~5 minutes
[Continue →](conversation-modes.md)
### 3. First run
Send your first task, watch it stream, and learn the core loop: run → continue → cancel.
@@ -39,7 +47,7 @@ Send your first task, watch it stream, and learn the core loop: run → continue
[Continue →](first-run.md)
### 3. Projects and branches
### 4. 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.
@@ -47,7 +55,7 @@ Register a repo as a project so you can target it from anywhere. Run tasks on fe
[Continue →](projects-and-branches.md)
### 4. Multi-engine workflows
### 5. Multi-engine workflows
Use different agents for different tasks. Set defaults per chat or topic.
@@ -62,6 +70,7 @@ By the end of these tutorials, you'll have:
```
~/.takopi/takopi.toml
├── bot_token + chat_id configured
├── session_mode chosen
├── default_engine set
└── projects.your-repo registered
```
@@ -69,7 +78,7 @@ By the end of these tutorials, you'll have:
And you'll know how to:
- Send tasks from Telegram and watch progress stream
- Continue conversations by replying
- Continue conversations by replying or sending a new message (chat mode)
- Cancel runs mid-flight
- Target specific repos and branches
- Switch between agents on the fly
docs/tutorials/install-and-onboard.md
+59 -7
View File
@@ -2,7 +2,7 @@
This tutorial walks you through installing Takopi, creating a Telegram bot, and generating your config file.
**What you'll have at the end:** A working `~/.takopi/takopi.toml` with your bot token, chat ID, and default engine.
**What you'll have at the end:** A working `~/.takopi/takopi.toml` with your bot token, chat ID, conversation mode, and default engine.
## 1. Install Python 3.14 and uv
@@ -150,12 +150,51 @@ Open Telegram and send `/start` (or any message) to your bot. Takopi will captur
!!! tip "Using Takopi in a group"
You can also send a message in a group where the bot is a member. Takopi will capture that group's chat ID instead. This is useful if you want multiple people to share the same bot.
## 8. Choose your default engine
## 8. Choose a conversation mode
Takopi asks how you want follow-up messages to behave:
```
? choose conversation mode:
❯ chat mode (auto-resume; use /new to start fresh)
stateless (reply-to-continue)
```
**Chat mode** keeps one active thread per chat (per sender in groups). New messages continue automatically.
**Stateless** makes every message start fresh unless you reply to a resume line.
## 9. (Optional) Enable Topics
If you plan to use Telegram **forum topics**, Takopi will ask:
```
? will you use topics?
❯ no, keep topics off
yes, in the main chat (this chat_id)
yes, in project chats (projects.<alias>.chat_id)
yes, in both main and project chats
```
Topics require a **forum-enabled supergroup** and the bot must have **Manage Topics** permission.
## 10. Choose resume line visibility
If you picked chat mode or enabled topics, Takopi asks whether to show resume lines:
```
? show resume lines in messages?
❯ hide resume lines (cleaner chat; use /new to reset)
show resume lines (best for reply-to-continue)
```
Resume lines let you reply to older messages to branch a conversation.
## 11. Choose your default engine
Takopi scans your PATH for installed agent CLIs:
```
step 2: agent cli tools
step 4: agent cli tools
agent status install command
───────────────────────────────────────────
@@ -171,12 +210,12 @@ step 2: agent cli tools
Pick whichever you prefer. You can always switch engines per-message later.
## 9. Save your config
## 12. Save your config
Takopi shows you a preview of what it will save:
```
step 3: save configuration
step 5: save configuration
~/.takopi/takopi.toml
@@ -186,6 +225,12 @@ step 3: save configuration
[transports.telegram]
bot_token = "123456789:ABC..."
chat_id = 123456789
session_mode = "chat"
show_resume_line = false
[transports.telegram.topics]
enabled = false
scope = "auto"
? save this config to ~/.takopi/takopi.toml? (yes/no)
```
@@ -194,6 +239,7 @@ Press **Enter** to save. You'll see:
```
config saved to ~/.takopi/takopi.toml
sent confirmation message
setup complete. starting takopi...
```
@@ -211,6 +257,12 @@ transport = "telegram" # how Takopi talks to you
[transports.telegram]
bot_token = "..." # your bot's API key
chat_id = 123456789 # where to send messages
session_mode = "chat"
show_resume_line = false
[transports.telegram.topics]
enabled = false
scope = "auto"
```
This config file controls all of Takopi's behavior. You'll edit it directly for advanced features.
@@ -245,6 +297,6 @@ You can only run one Takopi instance per bot token. Find and stop the other proc
## Next
Now that Takopi is configured, let's send your first task.
Next, learn how conversation modes affect follow-ups.
[First run →](first-run.md)
[Conversation modes →](conversation-modes.md)
docs/tutorials/multi-engine.md
+10
View File
@@ -130,6 +130,16 @@ When Takopi picks an engine, it checks (highest to lowest):
This means: resume lines always win, then explicit directives, then the most specific default applies.
!!! note
With `session_mode = "chat"`, stored sessions are per engine. Replying to a resume line for another engine runs that engine and updates its stored session without overwriting other engines.
!!! example
Chat sessions with two engines (assume default engine is `codex`):
1. You send: `fix the failing tests` -> bot replies with `codex resume A` (stores Codex session A).
2. You reply to an older Claude message containing `claude --resume B` -> runs Claude and stores Claude session B.
3. You send a new message (not a reply) -> auto-resumes Codex session A (default engine), Claude session B remains stored for future replies or defaults.
## 7. Practical patterns
**Pattern: Quick questions vs. deep work**