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/explanation/routing-and-sessions.md
+5 -1
View File
@@ -9,12 +9,15 @@ Takopi supports three ways to continue a thread:
1. **Reply-to-continue** (always available)
- Reply to any bot message that contains a resume line in the footer.
- Takopi extracts the resume token and resumes that engine thread.
- Reply resume lines always take precedence over chat sessions or topic storage.
- The resumed run updates the stored session for that engine when the token is known.
2. **Forum topics** (optional)
- Topics can store resume tokens per topic and auto-resume new messages in that topic.
- Topic state is stored in `telegram_topics_state.json`.
- Reset with `/new`.
3. **Chat sessions** (optional)
- Set `session_mode = "chat"` to store one resume token per chat (per sender in groups).
- Stored sessions are per engine; resuming a different engine does not overwrite others.
- State is stored in `telegram_chat_sessions_state.json`.
- Reset with `/new`.
@@ -39,6 +42,7 @@ The precise invariants are specified in the [Specification](../reference/specifi
## Related
- [Conversation modes](../tutorials/conversation-modes.md)
- [Chat sessions](../how-to/chat-sessions.md)
- [Commands & directives](../reference/commands-and-directives.md)
- [Context resolution](../reference/context-resolution.md)
docs/how-to/chat-sessions.md
+43
View File
@@ -0,0 +1,43 @@
# Chat sessions
Chat sessions store one resume token per engine per chat (per sender in group chats), so new messages can auto-resume without replying. Reply-to-continue still works and updates the stored session for that engine.
## Enable chat sessions
```toml
[transports.telegram]
session_mode = "chat" # stateless | chat
```
With `session_mode = "chat"`, new messages in the chat continue the current thread automatically.
## Reset a session
Use `/new` to clear the stored session for the current scope:
- In a private chat, it resets the chat.
- In a group, it resets **your** session in that chat.
- In a forum topic, it resets the topic session.
See `/new` in [Commands & directives](../reference/commands-and-directives.md).
## Resume lines and branching
Chat sessions do not remove reply-to-continue. If resume lines are visible, you can reply to any older message to branch the conversation.
If you prefer a cleaner chat, hide resume lines:
```toml
[transports.telegram]
show_resume_line = false
```
## How it behaves in groups
In group chats, Takopi stores a session per sender, so different people can work independently in the same chat.
## Related
- [Conversation modes](../tutorials/conversation-modes.md)
- [Forum topics](topics.md)
- [Commands & directives](../reference/commands-and-directives.md)
docs/how-to/index.md
+2 -2
View File
@@ -11,8 +11,8 @@ If you need exact options and defaults, use **[Reference](../reference/index.md)
- [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)
- [Topics](topics.md) (forum threads bound to repo/branch + per-topic defaults)
- [Chat sessions](chat-sessions.md) (auto-resume without replying)
## Messaging extras
docs/how-to/topics.md
+63 -29
View File
@@ -1,6 +1,19 @@
# Topics
Topics bind Telegram forum threads to a specific project/branch context. They can also store resume tokens and a default agent per topic.
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.
## Why use topics
- Keep each thread tied to a repo + branch
- Avoid context collisions in busy team chats
- Set a default agent per topic with `/agent set`
## Requirements checklist
- The chat is a **forum-enabled supergroup**
- **Topics are enabled** in the group settings
- The bot is an **admin** with **Manage Topics** permission
- If you want topics in project chats, set `projects.<alias>.chat_id`
## Enable topics
@@ -10,44 +23,65 @@ enabled = true
scope = "auto" # auto | main | projects | all
```
Your bot needs **Manage Topics** permission in the group.
### Scope explained
If any `projects.<alias>.chat_id` are configured, topics are managed in those project chats; otherwise topics are managed in the main chat.
- `auto` (default): uses `projects` if any project chats exist, otherwise `main`
- `main`: topics only in the main `chat_id`
- `projects`: topics only in project chats (`projects.<alias>.chat_id`)
- `all`: topics available in both the main chat and project chats
## Topic commands
## Create and bind a topic
Run these inside a topic thread:
Run this inside a forum topic thread:
| Command | Description |
|---------|-------------|
| `/topic <project> @branch` | Create a new topic bound to context |
| `/ctx` | Show the current binding |
| `/ctx set <project> @branch` | Update the binding |
| `/ctx clear` | Remove the binding |
| `/new` | Clear stored sessions for this topic |
In project chats, omit the project: `/topic @branch` or `/ctx set @branch`.
## Chat sessions
Chat sessions store one resume token per chat (per sender in groups) so new messages can auto-resume without replying.
Enable:
```toml
[transports.telegram]
session_mode = "chat" # stateless | chat
```
/topic <project> @branch
```
Reset the stored session with `/new`.
Examples:
- In the main chat: `/topic backend @feat/api`
- In a project chat: `/topic @feat/api` (project is implied)
Takopi will bind the topic and rename it to match the context.
## Inspect or change the binding
- `/ctx` shows the current binding
- `/ctx set <project> @branch` updates it
- `/ctx clear` removes it
## Reset a topic session
Use `/new` inside the topic to clear stored sessions for that thread.
## Set a default agent per topic
Use `/agent set` inside the topic:
```
/agent set claude
```
## State files
- Topic state: `telegram_topics_state.json`
- Chat sessions state: `telegram_chat_sessions_state.json`
- Chat defaults (e.g. `/agent`): `telegram_chat_prefs_state.json`
Topic bindings and sessions live in:
- `telegram_topics_state.json`
## Common issues and fixes
- **"topics commands are only available..."**
- Your `scope` does not include this chat. Update `topics.scope`.
- **"chat is not a supergroup" / "topics enabled but chat does not have topics"**
- Convert the group to a supergroup and enable topics.
- **"bot lacks manage topics permission"**
- Promote the bot to admin and grant Manage Topics.
## Related
- [Projects and branches](../tutorials/projects-and-branches.md)
- [Route by chat](route-by-chat.md)
- [Chat sessions](chat-sessions.md)
- [Multi-engine workflows](../tutorials/multi-engine.md)
- [Switch engines](switch-engines.md)
- [Commands & directives](../reference/commands-and-directives.md)
docs/how-to/troubleshooting.md
+7
View File
@@ -8,3 +8,10 @@ takopi --debug
Then check `debug.log` for errors and include it when reporting issues.
You can also run a preflight check:
```sh
takopi doctor
```
This validates your Telegram token, chat id, topics setup, file transfer permissions, and voice transcription configuration.
docs/index.md
+24
View File
@@ -4,6 +4,29 @@
Takopi lets you run an engine CLI in a local repo while controlling it from Telegram: send a task, stream updates, and continue safely (reply-to-continue, topics, or sessions).
## Workflows
<div class="grid cards" markdown>
- :lucide-message-circle:{ .lg } **Solo chat workflow**
---
For a single developer in a private chat.
- [Conversation modes](tutorials/conversation-modes.md)
- [First run](tutorials/first-run.md)
- :lucide-users:{ .lg } **Team topics workflow**
---
For teams using forum topics and per-topic defaults.
- [Topics](how-to/topics.md)
- [Projects and branches](tutorials/projects-and-branches.md)
</div>
## Choose your path
<div class="grid cards" markdown>
@@ -14,6 +37,7 @@ Takopi lets you run an engine CLI in a local repo while controlling it from Tele
Start with [Tutorials](tutorials/index.md).
- [Install & onboard](tutorials/install-and-onboard.md)
- [Conversation modes](tutorials/conversation-modes.md)
- [First run](tutorials/first-run.md)
- :lucide-compass:{ .lg } **I know what I want to do**
docs/reference/commands-and-directives.md
+1 -1
View File
@@ -57,6 +57,7 @@ Takopi’s CLI is an auto-router by default; engine subcommands override the def
| `takopi init <alias>` | Register the current repo as a project. |
| `takopi chat-id` | Capture the current chat id. |
| `takopi chat-id --project <alias>` | Save the captured chat id to a project. |
| `takopi doctor` | Validate Telegram connectivity and related config. |
| `takopi plugins` | List discovered plugins without loading them. |
| `takopi plugins --load` | Load each plugin to validate types and surface import errors. |
@@ -68,4 +69,3 @@ Takopi’s CLI is an auto-router by default; engine subcommands override the def
| `--transport <id>` | Override the configured transport backend id. |
| `--debug` | Write debug logs to `debug.log`. |
| `--final-notify/--no-final-notify` | Send the final response as a new message vs an edit. |
docs/reference/transports/telegram.md
+2 -1
View File
@@ -54,8 +54,9 @@ session_mode = "chat" # or "stateless"
Behavior:
- Stores one resume token per chat (per sender in group chats).
- Stores one resume token per engine per chat (per sender in group chats).
- Auto-resumes when no explicit resume token is present.
- Reply resume lines always take precedence and update the stored session for that engine.
- Reset with `/new`.
State is stored in `telegram_chat_sessions_state.json` alongside the config file.
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**