docs: onboarding v2, widgets for telegram workflows, hero widget (#138)
This commit is contained in:
banteg
@@ -1,6 +1,6 @@
|
||||
# Routing & sessions
|
||||
|
||||
Takopi is **stateless by default**: each message starts a new engine session unless a resume token is present.
|
||||
Takopi supports both **stateless** and **chat** modes for session handling. In stateless mode, each message starts a new session unless you reply to continue. In chat mode, new messages auto-resume the previous session.
|
||||
|
||||
## Continuation (how threads persist)
|
||||
|
||||
|
||||
@@ -2,8 +2,13 @@
|
||||
|
||||
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.
|
||||
|
||||
!!! tip "Assistant and workspace workflows"
|
||||
If you chose **assistant** or **workspace** during [onboarding](../tutorials/install.md), chat sessions are already enabled. This guide covers how they work and how to customize them.
|
||||
|
||||
## Enable chat sessions
|
||||
|
||||
If you chose **handoff** during onboarding and want to switch to chat mode:
|
||||
|
||||
```toml
|
||||
[transports.telegram]
|
||||
session_mode = "chat" # stateless | chat
|
||||
|
||||
@@ -2,6 +2,9 @@
|
||||
|
||||
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.
|
||||
|
||||
!!! 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.
|
||||
|
||||
## Why use topics
|
||||
|
||||
- Keep each thread tied to a repo + branch
|
||||
@@ -15,6 +18,13 @@ Topics bind Telegram **forum threads** to a project/branch context. Each topic k
|
||||
- The bot is an **admin** with **Manage Topics** permission
|
||||
- If you want topics in project chats, set `projects.<alias>.chat_id`
|
||||
|
||||
!!! note "Setting up workspace from scratch"
|
||||
If you didn't choose workspace during onboarding and want to enable topics now:
|
||||
|
||||
1. Create a group and enable topics in group settings
|
||||
2. Add your bot as admin with "Manage Topics" permission
|
||||
3. Update your config to enable topics (see below)
|
||||
|
||||
## Enable topics
|
||||
|
||||
```toml
|
||||
|
||||
+52
-111
@@ -1,140 +1,81 @@
|
||||
# Takopi documentation
|
||||
|
||||
> Telegram bridge for coding agents (Codex, Claude Code, OpenCode, Pi).
|
||||
|
||||
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)
|
||||
Takopi runs coding agents on your computer and bridges them to Telegram. Send tasks from anywhere, watch progress stream live, pick up when back at the terminal. Scale from quick one-offs to multi-project workflows with topics and parallel worktrees.
|
||||
|
||||
<div class="hero-demo">
|
||||
<div class="hero-chat">
|
||||
<div class="chat-messages"></div>
|
||||
</div>
|
||||
<div class="hero-terminal">
|
||||
<div class="terminal-content"></div>
|
||||
</div>
|
||||
|
||||
## Choose your path
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
- :lucide-sparkles:{ .lg } **I’m new / I want to get it running**
|
||||
|
||||
---
|
||||
|
||||
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**
|
||||
|
||||
---
|
||||
|
||||
Use [How-to guides](how-to/index.md).
|
||||
|
||||
- [Projects](how-to/projects.md) and [Worktrees](how-to/worktrees.md)
|
||||
- [Topics](how-to/topics.md) and [Route by chat](how-to/route-by-chat.md)
|
||||
- [File transfer](how-to/file-transfer.md) and [Voice notes](how-to/voice-notes.md)
|
||||
|
||||
- :lucide-book:{ .lg } **I need exact knobs, defaults, and contracts**
|
||||
|
||||
---
|
||||
|
||||
Go straight to [Reference](reference/index.md).
|
||||
|
||||
- [Commands & directives](reference/commands-and-directives.md)
|
||||
- [Configuration](reference/config.md)
|
||||
- [Specification](reference/specification.md) (normative behavior)
|
||||
|
||||
- :lucide-lightbulb:{ .lg } **I'm trying to understand the design**
|
||||
|
||||
---
|
||||
|
||||
Read [Explanation](explanation/index.md).
|
||||
|
||||
- [Architecture](explanation/architecture.md)
|
||||
- [Routing & sessions](explanation/routing-and-sessions.md)
|
||||
- [Plugin system](explanation/plugin-system.md)
|
||||
|
||||
</div>
|
||||
|
||||
## Quick start
|
||||
|
||||
If you just want to see it work end-to-end:
|
||||
|
||||
```bash
|
||||
# Install
|
||||
uv tool install -U takopi
|
||||
|
||||
# Configure Telegram + defaults
|
||||
takopi --onboard
|
||||
|
||||
# Run in a repo
|
||||
cd /path/to/your/repo
|
||||
takopi
|
||||
```
|
||||
|
||||
Then open Telegram and send a task to your bot.
|
||||
Onboarding walks you through bot setup and asks how you want to work. [Full install guide →](tutorials/install.md)
|
||||
|
||||
## Core concepts
|
||||
## Pick your workflow
|
||||
|
||||
* **Engine**: the CLI that actually does the work (e.g. `codex`, `claude`, `opencode`, `pi`).
|
||||
* **Project**: a named alias for a repo path (so you can run from anywhere).
|
||||
* **Worktree / branch selection**: pick where work should happen (`@branch`).
|
||||
* **Continuation**: how Takopi safely “continues” a run:
|
||||
<div class="grid cards" markdown>
|
||||
- :lucide-message-circle:{ .lg } **Assistant**
|
||||
|
||||
* reply-to-continue (always available)
|
||||
* forum topics (thread-bound continuation)
|
||||
* chat sessions (auto-resume)
|
||||
* **Contract**: the stable rules (resume lines, event ordering, rendering expectations) in the
|
||||
[Specification](reference/specification.md) and runner contract tests.
|
||||
---
|
||||
|
||||
## For plugin authors
|
||||
Ongoing chat. New messages auto-continue; `/new` to reset.
|
||||
|
||||
Start here:
|
||||
Best for: solo work, natural conversation flow.
|
||||
|
||||
* [Plugin API](reference/plugin-api.md) — **stable** `takopi.api` surface for plugins
|
||||
* [Write a plugin](how-to/write-a-plugin.md)
|
||||
* [Add a runner](how-to/add-a-runner.md)
|
||||
[Get started →](tutorials/first-run.md)
|
||||
|
||||
If you’re contributing to core:
|
||||
- :lucide-folder-kanban:{ .lg } **Workspace**
|
||||
|
||||
* [Dev setup](how-to/dev-setup.md)
|
||||
* [Module map](explanation/module-map.md)
|
||||
---
|
||||
|
||||
## For LLM agents
|
||||
Forum topics bound to projects and branches.
|
||||
|
||||
In the docs, start here:
|
||||
Best for: teams, organized multi-repo workflows.
|
||||
|
||||
* [Reference: For agents](reference/agents/index.md)
|
||||
* [Repo map](reference/agents/repo-map.md)
|
||||
* [Invariants](reference/agents/invariants.md)
|
||||
[Set up topics →](how-to/topics.md)
|
||||
|
||||
## Where to look when something feels “off”
|
||||
- :lucide-terminal:{ .lg } **Handoff**
|
||||
|
||||
* “Why didn’t it route to the right repo/branch?” → [Context resolution](reference/context-resolution.md)
|
||||
* “Why didn’t it continue where I left off?” → [Commands & directives](reference/commands-and-directives.md) and [Specification](reference/specification.md)
|
||||
* “Why did Telegram messages behave weirdly?” → [Telegram transport](reference/transports/telegram.md)
|
||||
* “Why is it built this way?” → [Architecture](explanation/architecture.md)
|
||||
---
|
||||
|
||||
## Legacy portals
|
||||
Reply-to-continue. Copy resume lines to your terminal.
|
||||
|
||||
These pages remain as curated pointers to preserve old links:
|
||||
Best for: explicit control, terminal-first workflow.
|
||||
|
||||
- [User guide](user-guide.md)
|
||||
- [Plugins](plugins.md)
|
||||
- [Developing](developing.md)
|
||||
[Get started →](tutorials/first-run.md)
|
||||
|
||||
</div>
|
||||
|
||||
You can change workflows later by editing `~/.takopi/takopi.toml`.
|
||||
|
||||
## Tutorials
|
||||
|
||||
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
|
||||
|
||||
## How-to guides
|
||||
|
||||
- [Chat sessions](how-to/chat-sessions.md), [Topics](how-to/topics.md), [Projects](how-to/projects.md), [Worktrees](how-to/worktrees.md)
|
||||
- [Voice notes](how-to/voice-notes.md), [File transfer](how-to/file-transfer.md), [Schedule tasks](how-to/schedule-tasks.md)
|
||||
- [Write a plugin](how-to/write-a-plugin.md), [Add a runner](how-to/add-a-runner.md), [Dev setup](how-to/dev-setup.md)
|
||||
|
||||
## Reference
|
||||
|
||||
Exact options, defaults, and contracts:
|
||||
|
||||
- [Commands & directives](reference/commands-and-directives.md)
|
||||
- [Configuration](reference/config.md)
|
||||
- [Specification](reference/specification.md) — normative behavior
|
||||
|
||||
@@ -0,0 +1,159 @@
|
||||
// Animated hero chat + terminal widget for Takopi docs
|
||||
(function() {
|
||||
const TIME_SCALE = 0.5; // 2x speed
|
||||
const RESUME_ID = '019bb498';
|
||||
const RESUME_CMD = `codex resume ${RESUME_ID}`;
|
||||
|
||||
const EVENTS = [
|
||||
{ time: 2515, thinking: "Listing files for inspection" },
|
||||
{ time: 2892, cmd: "ls" },
|
||||
{ time: 4755, thinking: "Inspecting readme" },
|
||||
{ time: 4982, cmd: "cat readme.md" },
|
||||
{ time: 7217, thinking: "Scanning source structure" },
|
||||
{ time: 7642, cmd: "ls src" },
|
||||
{ time: 9024, cmd: "ls src/takopi" },
|
||||
{ time: 10927, thinking: "Exploring Telegram integration" },
|
||||
{ time: 11213, cmd: "rg telegram src/takopi" },
|
||||
{ time: 14884, thinking: "Planning deeper codebase inspection" },
|
||||
{ time: 15210, cmd: "rg scripts pyproject.toml" },
|
||||
{ time: 16796, cmd: "cat pyproject.toml" },
|
||||
{ time: 21565, thinking: "Summarizing project purpose" },
|
||||
];
|
||||
|
||||
const ANSWER_TIME = 21500;
|
||||
const DONE_TIME = 23000;
|
||||
const MAX_VISIBLE = 5;
|
||||
|
||||
const ANSWER = `Takopi is a Telegram bridge for agent CLIs like Codex, Claude Code, OpenCode, and Pi. It lets you run agents from chat, stream progress back, manage multiple repos and branches, and resume sessions from either chat or terminal.`;
|
||||
|
||||
const USER_QUESTION = 'what does this project do?';
|
||||
|
||||
async function typeText(element, text, delay = 30) {
|
||||
for (const char of text) {
|
||||
element.textContent += char;
|
||||
await new Promise(r => setTimeout(r, delay));
|
||||
}
|
||||
}
|
||||
|
||||
async function animateDemo() {
|
||||
const chat = document.querySelector('.hero-chat');
|
||||
const terminal = document.querySelector('.hero-terminal');
|
||||
if (!chat || !terminal) return;
|
||||
|
||||
const messages = chat.querySelector('.chat-messages');
|
||||
const termContent = terminal.querySelector('.terminal-content');
|
||||
messages.innerHTML = '';
|
||||
termContent.innerHTML = '<div class="prompt shell"><span class="prompt-symbol">$</span> <span class="prompt-input"></span><span class="cursor">▋</span></div>';
|
||||
|
||||
// User message appears
|
||||
await new Promise(r => setTimeout(r, 800 * TIME_SCALE));
|
||||
const userMsg = document.createElement('div');
|
||||
userMsg.className = 'msg msg-user';
|
||||
userMsg.textContent = USER_QUESTION;
|
||||
messages.appendChild(userMsg);
|
||||
|
||||
// Bot starts responding
|
||||
await new Promise(r => setTimeout(r, 600 * TIME_SCALE));
|
||||
const botMsg = document.createElement('div');
|
||||
botMsg.className = 'msg msg-bot';
|
||||
botMsg.innerHTML = `<div class="status">starting · codex · 0s</div><div class="tools"></div><div class="resume">${RESUME_CMD}</div>`;
|
||||
messages.appendChild(botMsg);
|
||||
|
||||
const statusEl = botMsg.querySelector('.status');
|
||||
const toolsDiv = botMsg.querySelector('.tools');
|
||||
const startTime = Date.now();
|
||||
const allTools = [];
|
||||
|
||||
let step = 0;
|
||||
const timerInterval = setInterval(() => {
|
||||
const elapsed = Math.floor((Date.now() - startTime) / 1000);
|
||||
if (step === 0) {
|
||||
statusEl.textContent = `starting · codex · ${elapsed}s`;
|
||||
} else {
|
||||
statusEl.textContent = `working · codex · ${elapsed}s · step ${step}`;
|
||||
}
|
||||
}, 1000);
|
||||
|
||||
// Schedule each event
|
||||
for (const event of EVENTS) {
|
||||
const wait = event.time * TIME_SCALE - (Date.now() - startTime);
|
||||
if (wait > 0) await new Promise(r => setTimeout(r, wait));
|
||||
|
||||
step++;
|
||||
|
||||
const elapsed = Math.floor((Date.now() - startTime) / 1000);
|
||||
statusEl.textContent = `working · codex · ${elapsed}s · step ${step}`;
|
||||
|
||||
const prevRunning = toolsDiv.querySelector('.running');
|
||||
if (prevRunning) prevRunning.classList.remove('running');
|
||||
|
||||
const toolEl = document.createElement('div');
|
||||
toolEl.className = event.cmd ? 'tool cmd running' : 'tool running';
|
||||
toolEl.textContent = event.thinking || event.cmd;
|
||||
allTools.push(toolEl);
|
||||
toolsDiv.appendChild(toolEl);
|
||||
|
||||
if (allTools.length > MAX_VISIBLE) {
|
||||
const old = allTools.shift();
|
||||
old.remove();
|
||||
}
|
||||
}
|
||||
|
||||
const lastRunning = toolsDiv.querySelector('.running');
|
||||
if (lastRunning) lastRunning.classList.remove('running');
|
||||
|
||||
const remaining = ANSWER_TIME * TIME_SCALE - (Date.now() - startTime);
|
||||
if (remaining > 0) await new Promise(r => setTimeout(r, remaining));
|
||||
|
||||
const doneRemaining = DONE_TIME * TIME_SCALE - (Date.now() - startTime);
|
||||
if (doneRemaining > 0) await new Promise(r => setTimeout(r, doneRemaining));
|
||||
|
||||
clearInterval(timerInterval);
|
||||
const finalElapsed = Math.floor((Date.now() - startTime) / 1000);
|
||||
|
||||
// Show done state with answer and resume line
|
||||
botMsg.innerHTML = `
|
||||
<div class="status">done · codex · ${finalElapsed}s · step ${step}</div>
|
||||
<div class="answer">${ANSWER}</div>
|
||||
<div class="resume">${RESUME_CMD}</div>
|
||||
`;
|
||||
|
||||
// Wait, then animate terminal
|
||||
await new Promise(r => setTimeout(r, 1500));
|
||||
|
||||
// Type resume command in terminal
|
||||
const promptInput = termContent.querySelector('.prompt-input');
|
||||
await typeText(promptInput, RESUME_CMD, 40);
|
||||
|
||||
// Press enter
|
||||
await new Promise(r => setTimeout(r, 300));
|
||||
termContent.querySelector('.cursor').remove();
|
||||
termContent.querySelector('.prompt').classList.add('executed');
|
||||
|
||||
// Show codex output
|
||||
await new Promise(r => setTimeout(r, 500));
|
||||
const output = document.createElement('div');
|
||||
output.className = 'codex-output';
|
||||
output.innerHTML = `<div class="codex-msg user">${USER_QUESTION}</div>
|
||||
<div class="codex-msg assistant">${ANSWER}</div>
|
||||
<div class="codex-prompt"><span class="codex-input"></span><span class="cursor">▋</span></div>`;
|
||||
termContent.appendChild(output);
|
||||
|
||||
// Type a follow-up message
|
||||
await new Promise(r => setTimeout(r, 800));
|
||||
const codexInput = output.querySelector('.codex-input');
|
||||
await typeText(codexInput, 'omg takopi you are the best', 50);
|
||||
}
|
||||
|
||||
function init() {
|
||||
if (document.querySelector('.hero-chat') && document.querySelector('.hero-terminal')) {
|
||||
animateDemo();
|
||||
}
|
||||
}
|
||||
|
||||
if (document.readyState === 'loading') {
|
||||
document.addEventListener('DOMContentLoaded', init);
|
||||
} else {
|
||||
init();
|
||||
}
|
||||
})();
|
||||
@@ -33,8 +33,8 @@ chat_id = 123
|
||||
| `voice_transcription` | bool | `false` | Enable voice note transcription. |
|
||||
| `voice_max_bytes` | int | `10485760` | Max voice note size (bytes). |
|
||||
| `voice_transcription_model` | string | `"gpt-4o-mini-transcribe"` | OpenAI transcription model name. |
|
||||
| `session_mode` | `"stateless"`\|`"chat"` | `"stateless"` | Auto-resume mode. |
|
||||
| `show_resume_line` | bool | `true` | Show resume line in message footer. |
|
||||
| `session_mode` | `"stateless"`\|`"chat"` | `"stateless"` | Auto-resume mode. Onboarding sets `"chat"` for assistant/workspace. |
|
||||
| `show_resume_line` | bool | `true` | Show resume line in message footer. Onboarding sets `false` for assistant/workspace. |
|
||||
|
||||
### `transports.telegram.topics`
|
||||
|
||||
|
||||
@@ -42,8 +42,9 @@ ignores it. If your server requires a specific model name, set
|
||||
|
||||
## Chat sessions (optional)
|
||||
|
||||
Takopi is stateless by default unless you reply to a bot message containing a resume
|
||||
line. If you want auto-resume without replies, enable chat sessions.
|
||||
If you chose the **handoff** workflow during onboarding, Takopi uses stateless mode
|
||||
where you reply to continue a session. The **assistant** and **workspace** workflows
|
||||
use chat mode with auto-resume enabled.
|
||||
|
||||
Configuration (under `[transports.telegram]`):
|
||||
|
||||
@@ -81,8 +82,9 @@ chunks add a "continued (N/M)" header.
|
||||
|
||||
## Forum topics (optional)
|
||||
|
||||
Takopi can bind Telegram forum topics to a project/branch and persist resume tokens
|
||||
per topic, so replies keep the right context even after restarts.
|
||||
If you chose the **workspace** workflow during onboarding, topics are already enabled.
|
||||
Topics bind Telegram forum threads to a project/branch and persist resume tokens per
|
||||
topic, so replies keep the right context even after restarts.
|
||||
|
||||
Configuration (under `[transports.telegram]`):
|
||||
|
||||
|
||||
@@ -0,0 +1,221 @@
|
||||
/* Animated hero chat + terminal widget */
|
||||
/* Takopi pink: #F4A5B8, Flower pink: #E87A9F, Teal: #4A9B8E */
|
||||
|
||||
.hero-demo {
|
||||
display: flex;
|
||||
gap: 16px;
|
||||
max-width: 800px;
|
||||
margin: 24px auto;
|
||||
align-items: stretch;
|
||||
height: 320px;
|
||||
}
|
||||
|
||||
@media (max-width: 700px) {
|
||||
.hero-demo {
|
||||
flex-direction: column;
|
||||
}
|
||||
}
|
||||
|
||||
.hero-chat {
|
||||
background: #fff;
|
||||
border-radius: 12px;
|
||||
padding: 12px;
|
||||
flex: 1;
|
||||
min-width: 0;
|
||||
font-size: 14px;
|
||||
line-height: 1.4;
|
||||
border: 1px solid #e5e5e5;
|
||||
box-shadow: 0 4px 24px rgba(0, 0, 0, 0.08);
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.hero-terminal {
|
||||
background: #1a1b26;
|
||||
border-radius: 12px;
|
||||
padding: 12px;
|
||||
flex: 1;
|
||||
min-width: 0;
|
||||
font-family: var(--md-code-font-family, monospace);
|
||||
font-size: 14px;
|
||||
line-height: 1.4;
|
||||
color: #a9b1d6;
|
||||
box-shadow: 0 4px 24px rgba(0, 0, 0, 0.15);
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.hero-terminal .terminal-content {
|
||||
white-space: pre-wrap;
|
||||
word-break: break-word;
|
||||
}
|
||||
|
||||
.hero-terminal .prompt.shell {
|
||||
color: #4A9B8E;
|
||||
}
|
||||
|
||||
.hero-terminal .prompt.shell .prompt-symbol {
|
||||
color: #4A9B8E;
|
||||
}
|
||||
|
||||
.hero-terminal .prompt.shell .cursor {
|
||||
color: #4A9B8E;
|
||||
}
|
||||
|
||||
.hero-terminal .cursor {
|
||||
color: #7aa2f7;
|
||||
animation: cursor-blink 1s step-end infinite;
|
||||
}
|
||||
|
||||
@keyframes cursor-blink {
|
||||
50% { opacity: 0; }
|
||||
}
|
||||
|
||||
.hero-terminal .codex-output {
|
||||
margin-top: 12px;
|
||||
}
|
||||
|
||||
.hero-terminal .codex-msg.user {
|
||||
background: #13141c;
|
||||
margin: 0 -12px;
|
||||
padding: 8px 12px;
|
||||
}
|
||||
|
||||
.hero-terminal .codex-msg.user::before {
|
||||
content: "› ";
|
||||
color: #a9b1d6;
|
||||
}
|
||||
|
||||
.hero-terminal .codex-msg.assistant {
|
||||
margin-top: 8px;
|
||||
}
|
||||
|
||||
.hero-terminal .codex-msg.assistant::before {
|
||||
content: "• ";
|
||||
color: #a9b1d6;
|
||||
}
|
||||
|
||||
.hero-terminal .codex-prompt {
|
||||
background: #13141c;
|
||||
margin: 12px -12px -12px;
|
||||
padding: 8px 12px;
|
||||
}
|
||||
|
||||
.hero-terminal .codex-prompt::before {
|
||||
content: "› ";
|
||||
color: #a9b1d6;
|
||||
}
|
||||
|
||||
.hero-chat .chat-messages {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
.hero-chat .msg {
|
||||
max-width: 90%;
|
||||
padding: 8px 12px;
|
||||
border-radius: 14px;
|
||||
opacity: 0;
|
||||
transform: translateY(10px);
|
||||
animation: msg-appear 0.3s ease forwards;
|
||||
}
|
||||
|
||||
@keyframes msg-appear {
|
||||
to {
|
||||
opacity: 1;
|
||||
transform: translateY(0);
|
||||
}
|
||||
}
|
||||
|
||||
.hero-chat .msg-user {
|
||||
background: #4A9B8E;
|
||||
color: #fff;
|
||||
align-self: flex-end;
|
||||
border-bottom-right-radius: 6px;
|
||||
}
|
||||
|
||||
.hero-chat .msg-bot {
|
||||
background: #fafafa;
|
||||
color: #333;
|
||||
align-self: flex-start;
|
||||
border: 1px solid #e5e5e5;
|
||||
border-bottom-left-radius: 6px;
|
||||
}
|
||||
|
||||
.hero-chat .msg-bot .status {
|
||||
color: #999;
|
||||
}
|
||||
|
||||
.hero-chat .msg-bot .tools {
|
||||
margin-top: 8px;
|
||||
}
|
||||
|
||||
.hero-chat .msg-bot .tool {
|
||||
opacity: 0;
|
||||
animation: tool-appear 0.2s ease forwards;
|
||||
}
|
||||
|
||||
@keyframes tool-appear {
|
||||
to {
|
||||
opacity: 1;
|
||||
}
|
||||
}
|
||||
|
||||
.hero-chat .msg-bot .tool.cmd {
|
||||
font-family: var(--md-code-font-family, monospace);
|
||||
}
|
||||
|
||||
.hero-chat .msg-bot .tool::before {
|
||||
content: "✓";
|
||||
color: #4A9B8E;
|
||||
font-family: system-ui, sans-serif;
|
||||
display: inline-block;
|
||||
width: 1.2em;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.hero-chat .msg-bot .tool.running::before {
|
||||
content: "•";
|
||||
font-family: system-ui, sans-serif;
|
||||
}
|
||||
|
||||
.hero-chat .msg-bot .answer {
|
||||
margin-top: 8px;
|
||||
color: #333;
|
||||
}
|
||||
|
||||
.hero-chat .msg-bot .resume {
|
||||
margin-top: 8px;
|
||||
color: #999;
|
||||
}
|
||||
|
||||
.hero-chat .typing-indicator {
|
||||
display: flex;
|
||||
gap: 4px;
|
||||
padding: 4px 0;
|
||||
}
|
||||
|
||||
.hero-chat .typing-indicator span {
|
||||
width: 6px;
|
||||
height: 6px;
|
||||
background: #999;
|
||||
border-radius: 50%;
|
||||
animation: typing-bounce 1s ease-in-out infinite;
|
||||
}
|
||||
|
||||
.hero-chat .typing-indicator span:nth-child(2) {
|
||||
animation-delay: 0.15s;
|
||||
}
|
||||
|
||||
.hero-chat .typing-indicator span:nth-child(3) {
|
||||
animation-delay: 0.3s;
|
||||
}
|
||||
|
||||
@keyframes typing-bounce {
|
||||
0%, 60%, 100% {
|
||||
transform: translateY(0);
|
||||
}
|
||||
30% {
|
||||
transform: translateY(-4px);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
/* Telegram-style chat preview (light mode with brand colors) */
|
||||
/* Takopi pink: #F4A5B8, Flower pink: #E87A9F, Teal: #4A9B8E */
|
||||
|
||||
.workflow-preview {
|
||||
background: #fff;
|
||||
border-radius: 12px;
|
||||
padding: 12px;
|
||||
margin: 8px 0;
|
||||
font-size: 0.85rem;
|
||||
line-height: 1.4;
|
||||
border: 1px solid #e5e5e5;
|
||||
width: 360px;
|
||||
}
|
||||
|
||||
.workflow-preview .msg {
|
||||
max-width: 85%;
|
||||
padding: 6px 12px;
|
||||
border-radius: 16px;
|
||||
margin: 4px 0;
|
||||
clear: both;
|
||||
}
|
||||
|
||||
.workflow-preview .msg-you {
|
||||
background: #4A9B8E;
|
||||
color: #fff;
|
||||
float: right;
|
||||
border-bottom-right-radius: 4px;
|
||||
}
|
||||
|
||||
.workflow-preview .msg-bot {
|
||||
background: #fafafa;
|
||||
color: #999;
|
||||
float: left;
|
||||
border: 1px solid #e5e5e5;
|
||||
border-bottom-left-radius: 4px;
|
||||
}
|
||||
|
||||
.workflow-preview .resume {
|
||||
display: block;
|
||||
}
|
||||
|
||||
.workflow-preview .resume .id-1 {
|
||||
color: #4A9B8E;
|
||||
}
|
||||
|
||||
.workflow-preview .resume .id-2 {
|
||||
color: #E87A9F;
|
||||
}
|
||||
|
||||
.workflow-preview .cmd {
|
||||
color: #4A9B8E;
|
||||
}
|
||||
|
||||
.workflow-preview .msg-you .cmd {
|
||||
color: #fff;
|
||||
}
|
||||
|
||||
.workflow-preview .clearfix::after {
|
||||
content: "";
|
||||
display: table;
|
||||
clear: both;
|
||||
}
|
||||
|
||||
.workflow-preview .topic-bar {
|
||||
display: flex;
|
||||
gap: 16px;
|
||||
margin-bottom: 12px;
|
||||
padding-bottom: 8px;
|
||||
border-bottom: 1px solid #e5e5e5;
|
||||
font-size: 0.75rem;
|
||||
}
|
||||
|
||||
.workflow-preview .topic-bar .topic {
|
||||
color: #999;
|
||||
padding-bottom: 6px;
|
||||
cursor: pointer;
|
||||
}
|
||||
|
||||
.workflow-preview .topic-bar .topic:hover {
|
||||
color: #666;
|
||||
}
|
||||
|
||||
.workflow-preview .topic-bar .topic-active {
|
||||
color: #E87A9F;
|
||||
font-weight: 500;
|
||||
padding-bottom: 6px;
|
||||
border-bottom: 2px solid #E87A9F;
|
||||
margin-bottom: -9px;
|
||||
}
|
||||
|
||||
.workflow-preview .reply-quote {
|
||||
background: rgba(255, 255, 255, 0.2);
|
||||
border-left: 2px solid rgba(255, 255, 255, 0.6);
|
||||
padding: 2px 6px;
|
||||
margin-bottom: 4px;
|
||||
font-size: 0.75rem;
|
||||
color: rgba(255, 255, 255, 0.85);
|
||||
border-radius: 2px;
|
||||
}
|
||||
@@ -1,11 +1,16 @@
|
||||
# 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.
|
||||
Takopi can handle follow-up messages in two ways: **chat mode** (auto-resume) or **stateless** (reply-to-continue).
|
||||
|
||||
## Quick pick
|
||||
During [onboarding](install.md), you chose a **workflow** (assistant, workspace, or handoff) that automatically configured this for you:
|
||||
|
||||
- **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.
|
||||
| Workflow | Session mode | Topics | Resume lines |
|
||||
|----------|--------------|--------|--------------|
|
||||
| **assistant** | chat | off | hidden |
|
||||
| **workspace** | chat | on | hidden |
|
||||
| **handoff** | stateless | off | shown |
|
||||
|
||||
This page explains what those settings mean and how to change them.
|
||||
|
||||
## Chat mode (auto-resume)
|
||||
|
||||
@@ -48,14 +53,20 @@ To continue the same session, **reply** to a message with a resume line:
|
||||
!!! user "You"
|
||||
now add tests
|
||||
|
||||
## Where to set it
|
||||
## Changing your settings
|
||||
|
||||
Onboarding will ask you, or you can set it in config:
|
||||
You can manually change these settings in your config file:
|
||||
|
||||
```toml
|
||||
[transports.telegram]
|
||||
session_mode = "chat" # or "stateless"
|
||||
show_resume_line = false # optional, see below
|
||||
session_mode = "chat" # "chat" or "stateless"
|
||||
show_resume_line = false # true or false
|
||||
```
|
||||
|
||||
Or re-run onboarding to pick a different workflow:
|
||||
|
||||
```sh
|
||||
takopi --onboard
|
||||
```
|
||||
|
||||
## Resume lines in chat mode
|
||||
|
||||
@@ -153,19 +153,6 @@ Key points:
|
||||
- When done, the progress message is replaced with the final answer
|
||||
- Chat mode auto-resumes; resume lines let you reply to branch
|
||||
|
||||
## The core loop
|
||||
|
||||
You now know the three fundamental interactions:
|
||||
|
||||
| Action | How |
|
||||
|--------|-----|
|
||||
| **Start** | Send a message to your bot |
|
||||
| **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.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Progress message stuck on "starting" (or not updating)**
|
||||
|
||||
+5
-87
@@ -1,90 +1,8 @@
|
||||
# Tutorials
|
||||
|
||||
Tutorials walk you through Takopi step-by-step. Follow them in order if you're new.
|
||||
1. [Install](install.md)
|
||||
2. [First run](first-run.md)
|
||||
3. [Projects & branches](projects-and-branches.md)
|
||||
4. [Multi-engine](multi-engine.md)
|
||||
|
||||
If you already know what you want ("enable topics", "use worktrees"), jump to **[How-to](../how-to/index.md)**.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before starting, make sure you have:
|
||||
|
||||
- A **Telegram account**
|
||||
- **Python 3.14+** and **uv** ([install uv](https://docs.astral.sh/uv/getting-started/installation/))
|
||||
- At least one agent CLI on your `PATH`:
|
||||
|
||||
| Agent | Install |
|
||||
|-------|---------|
|
||||
| Codex | `npm install -g @openai/codex` |
|
||||
| Claude Code | `npm install -g @anthropic-ai/claude-code` |
|
||||
| OpenCode | `npm install -g opencode-ai@latest` |
|
||||
| Pi | `npm install -g @mariozechner/pi-coding-agent` |
|
||||
|
||||
You only need one to get started. Takopi auto-detects what's available.
|
||||
|
||||
## The tutorials
|
||||
|
||||
### 1. Install and onboard
|
||||
|
||||
Set up Takopi, create a Telegram bot, and generate your config.
|
||||
|
||||
**Time:** ~5 minutes
|
||||
|
||||
[Start here →](install-and-onboard.md)
|
||||
|
||||
### 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.
|
||||
|
||||
**Time:** ~10 minutes
|
||||
|
||||
[Continue →](first-run.md)
|
||||
|
||||
### 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.
|
||||
|
||||
**Time:** ~10 minutes
|
||||
|
||||
[Continue →](projects-and-branches.md)
|
||||
|
||||
### 5. Multi-engine workflows
|
||||
|
||||
Use different agents for different tasks. Set defaults per chat or topic.
|
||||
|
||||
**Time:** ~5 minutes
|
||||
|
||||
[Continue →](multi-engine.md)
|
||||
|
||||
## What you'll build
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
And you'll know how to:
|
||||
|
||||
- Send tasks from Telegram and watch progress stream
|
||||
- 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
|
||||
|
||||
## After the tutorials
|
||||
|
||||
- **[How-to guides](../how-to/index.md)** — goal-oriented recipes (topics, file transfer, voice notes)
|
||||
- **[Reference](../reference/index.md)** — exact config keys, commands, and contracts
|
||||
- **[Explanation](../explanation/index.md)** — architecture and design rationale
|
||||
See also: [Conversation modes](conversation-modes.md)
|
||||
|
||||
@@ -1,302 +0,0 @@
|
||||
# Install and onboard
|
||||
|
||||
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, conversation mode, and default engine.
|
||||
|
||||
## 1. Install Python 3.14 and uv
|
||||
|
||||
Install `uv`, the modern Python [package manager](https://docs.astral.sh/uv/):
|
||||
|
||||
```sh
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
```
|
||||
|
||||
Install Python 3.14 with uv:
|
||||
|
||||
```sh
|
||||
uv python install 3.14
|
||||
```
|
||||
|
||||
## 2. Install Takopi
|
||||
|
||||
```sh
|
||||
uv tool install -U takopi
|
||||
```
|
||||
|
||||
Verify it's installed:
|
||||
|
||||
```sh
|
||||
takopi --version
|
||||
```
|
||||
|
||||
You should see something like `0.18.0`.
|
||||
|
||||
## 3. Install agent CLIs
|
||||
|
||||
Takopi shells out to agent CLIs. Install the ones you plan to use (or install them all now):
|
||||
|
||||
### Codex
|
||||
|
||||
```sh
|
||||
npm install -g @openai/codex
|
||||
```
|
||||
|
||||
Takopi uses the official Codex CLI, so your existing ChatGPT subscription applies. Run `codex` and sign in with your ChatGPT account.
|
||||
|
||||
### Claude Code
|
||||
|
||||
```sh
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
Takopi uses the official Claude CLI, so your existing Claude subscription applies. Run `claude` and log in with your Claude account. Takopi defaults to subscription billing unless you opt into API billing in config.
|
||||
|
||||
### OpenCode
|
||||
|
||||
```sh
|
||||
npm install -g opencode-ai@latest
|
||||
```
|
||||
|
||||
OpenCode supports logging in with Anthropic for your Claude subscription or with OpenAI for your ChatGPT subscription, and it can connect to 75+ providers via Models.dev (including local models).
|
||||
|
||||
### Pi
|
||||
|
||||
```sh
|
||||
npm install -g @mariozechner/pi-coding-agent
|
||||
```
|
||||
|
||||
Pi can authenticate via a provider login or use API billing. You can log in with Anthropic (Claude subscription), OpenAI (ChatGPT subscription), GitHub Copilot, Google Cloud Code Assist (Gemini CLI), or Antigravity (Gemini 3, Claude, GPT-OSS), or choose API billing instead.
|
||||
|
||||
## 4. Run onboarding
|
||||
|
||||
Start Takopi without a config file. It will detect this and launch the setup wizard:
|
||||
|
||||
```sh
|
||||
takopi
|
||||
```
|
||||
|
||||
You'll see something like:
|
||||
|
||||
```
|
||||
welcome to takopi!
|
||||
|
||||
let's set up your telegram bot.
|
||||
|
||||
step 1: telegram bot setup
|
||||
|
||||
? do you have a telegram bot token? (yes/no)
|
||||
```
|
||||
|
||||
If you don't have a bot token yet, answer **n** and Takopi will show you the steps.
|
||||
|
||||
## 5. Create a Telegram bot
|
||||
|
||||
If you answered **n**, follow these steps (or skip to step 6 if you already have a token):
|
||||
|
||||
1. Open Telegram and message [@BotFather](https://t.me/BotFather)
|
||||
2. Send `/newbot` or use the mini app
|
||||
3. Choose a display name (the obvious choice is "takopi")
|
||||
4. Choose a username ending in `bot` (e.g., `my_takopi_bot`)
|
||||
|
||||
BotFather will congratulate you on your new bot and will reply with your token:
|
||||
|
||||
```
|
||||
Done! Congratulations on your new bot. You will find it at
|
||||
t.me/my_takopi_bot. You can now add a description, about
|
||||
section and profile picture for your bot, see /help for a
|
||||
list of commands.
|
||||
|
||||
Use this token to access the HTTP API:
|
||||
123456789:ABCdefGHIjklMNOpqrsTUVwxyz
|
||||
|
||||
Keep your token secure and store it safely, it can be used
|
||||
by anyone to control your bot.
|
||||
```
|
||||
|
||||
Copy the token (the `123456789:ABC...` part).
|
||||
|
||||
!!! warning "Keep your token secret"
|
||||
Anyone with your bot token can control your bot. Don't commit it to git or share it publicly.
|
||||
|
||||
## 6. Enter your bot token
|
||||
|
||||
Paste your token when prompted:
|
||||
|
||||
```
|
||||
? paste your bot token: ****
|
||||
validating...
|
||||
connected to @my_takopi_bot
|
||||
```
|
||||
|
||||
Takopi validates the token by calling the Telegram API. If it fails, double-check you copied the full token.
|
||||
|
||||
## 7. Capture your chat ID
|
||||
|
||||
Takopi needs to know which chat to send messages to. It will listen for a message from you:
|
||||
|
||||
```
|
||||
send /start to @my_takopi_bot (works in groups too)
|
||||
waiting...
|
||||
```
|
||||
|
||||
Open Telegram and send `/start` (or any message) to your bot. Takopi will capture the chat:
|
||||
|
||||
```
|
||||
got chat_id 123456789 from @yourusername
|
||||
sent confirmation message
|
||||
```
|
||||
|
||||
!!! 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 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 4: agent cli tools
|
||||
|
||||
agent status install command
|
||||
───────────────────────────────────────────
|
||||
codex ✓ installed
|
||||
claude ✓ installed
|
||||
opencode ✗ not found npm install -g opencode-ai@latest
|
||||
pi ✗ not found npm install -g @mariozechner/pi-coding-agent
|
||||
|
||||
? choose default agent:
|
||||
❯ codex
|
||||
claude
|
||||
```
|
||||
|
||||
Pick whichever you prefer. You can always switch engines per-message later.
|
||||
|
||||
## 12. Save your config
|
||||
|
||||
Takopi shows you a preview of what it will save:
|
||||
|
||||
```
|
||||
step 5: save configuration
|
||||
|
||||
~/.takopi/takopi.toml
|
||||
|
||||
default_engine = "codex"
|
||||
transport = "telegram"
|
||||
|
||||
[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)
|
||||
```
|
||||
|
||||
Press **Enter** to save. You'll see:
|
||||
|
||||
```
|
||||
config saved to ~/.takopi/takopi.toml
|
||||
sent confirmation message
|
||||
|
||||
setup complete. starting takopi...
|
||||
```
|
||||
|
||||
Takopi is now running and listening for messages!
|
||||
|
||||
## What just happened
|
||||
|
||||
Your config file lives at `~/.takopi/takopi.toml`:
|
||||
|
||||
```toml title="~/.takopi/takopi.toml"
|
||||
default_engine = "codex" # new threads use this
|
||||
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.
|
||||
|
||||
## Re-running onboarding
|
||||
|
||||
If you ever need to reconfigure:
|
||||
|
||||
```sh
|
||||
takopi --onboard
|
||||
```
|
||||
|
||||
This will prompt you to update your existing config (it won't overwrite without asking).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"error: missing takopi config"**
|
||||
|
||||
Run `takopi` in a terminal with a TTY. The setup wizard only runs interactively.
|
||||
|
||||
**"failed to connect, check the token and try again"**
|
||||
|
||||
Make sure you copied the full token from BotFather, including the numbers before the colon.
|
||||
|
||||
**Bot doesn't respond to /start**
|
||||
|
||||
If you're still in onboarding, your terminal should show "waiting...". If you accidentally closed it, run `takopi` again and restart the setup.
|
||||
|
||||
**"error: already running"**
|
||||
|
||||
You can only run one Takopi instance per bot token. Find and stop the other process, or remove the stale lock file at `~/.takopi/takopi.lock`.
|
||||
|
||||
## Next
|
||||
|
||||
Next, learn how conversation modes affect follow-ups.
|
||||
|
||||
[Conversation modes →](conversation-modes.md)
|
||||
@@ -0,0 +1,356 @@
|
||||
# Install and onboard
|
||||
|
||||
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, workflow settings, and default engine.
|
||||
|
||||
## 1. Install Python 3.14 and uv
|
||||
|
||||
Install `uv`, the modern Python [package manager](https://docs.astral.sh/uv/):
|
||||
|
||||
```sh
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
```
|
||||
|
||||
Install Python 3.14 with uv:
|
||||
|
||||
```sh
|
||||
uv python install 3.14
|
||||
```
|
||||
|
||||
## 2. Install Takopi
|
||||
|
||||
```sh
|
||||
uv tool install -U takopi
|
||||
```
|
||||
|
||||
Verify it's installed:
|
||||
|
||||
```sh
|
||||
takopi --version
|
||||
```
|
||||
|
||||
You should see something like `0.18.0`.
|
||||
|
||||
## 3. Install agent CLIs
|
||||
|
||||
Takopi shells out to agent CLIs. Install the ones you plan to use (or install them all now):
|
||||
|
||||
### Codex
|
||||
|
||||
```sh
|
||||
npm install -g @openai/codex
|
||||
```
|
||||
|
||||
Takopi uses the official Codex CLI, so your existing ChatGPT subscription applies. Run `codex` and sign in with your ChatGPT account.
|
||||
|
||||
### Claude Code
|
||||
|
||||
```sh
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
Takopi uses the official Claude CLI, so your existing Claude subscription applies. Run `claude` and log in with your Claude account. Takopi defaults to subscription billing unless you opt into API billing in config.
|
||||
|
||||
### OpenCode
|
||||
|
||||
```sh
|
||||
npm install -g opencode-ai@latest
|
||||
```
|
||||
|
||||
OpenCode supports logging in with Anthropic for your Claude subscription or with OpenAI for your ChatGPT subscription, and it can connect to 75+ providers via Models.dev (including local models).
|
||||
|
||||
### Pi
|
||||
|
||||
```sh
|
||||
npm install -g @mariozechner/pi-coding-agent
|
||||
```
|
||||
|
||||
Pi can authenticate via a provider login or use API billing. You can log in with Anthropic (Claude subscription), OpenAI (ChatGPT subscription), GitHub Copilot, Google Cloud Code Assist (Gemini CLI), or Antigravity (Gemini 3, Claude, GPT-OSS), or choose API billing instead.
|
||||
|
||||
## 4. Run onboarding
|
||||
|
||||
Start Takopi without a config file. It will detect this and launch the setup wizard:
|
||||
|
||||
```sh
|
||||
takopi
|
||||
```
|
||||
|
||||
You'll see:
|
||||
|
||||
```
|
||||
step 1: bot token
|
||||
|
||||
? do you already have a bot token from @BotFather? (yes/no)
|
||||
```
|
||||
|
||||
If you don't have a bot token yet, answer **n** and Takopi will show you the steps.
|
||||
|
||||
## 5. Create a Telegram bot
|
||||
|
||||
If you answered **n**, follow these steps (or skip to step 6 if you already have a token):
|
||||
|
||||
1. Open Telegram and message [@BotFather](https://t.me/BotFather)
|
||||
2. Send `/newbot` or use the mini app
|
||||
3. Choose a display name (the obvious choice is "takopi")
|
||||
4. Choose a username ending in `bot` (e.g., `my_takopi_bot`)
|
||||
|
||||
BotFather will congratulate you on your new bot and will reply with your token:
|
||||
|
||||
```
|
||||
Done! Congratulations on your new bot. You will find it at
|
||||
t.me/my_takopi_bot. You can now add a description, about
|
||||
section and profile picture for your bot, see /help for a
|
||||
list of commands.
|
||||
|
||||
Use this token to access the HTTP API:
|
||||
123456789:ABCdefGHIjklMNOpqrsTUVwxyz
|
||||
|
||||
Keep your token secure and store it safely, it can be used
|
||||
by anyone to control your bot.
|
||||
```
|
||||
|
||||
Copy the token (the `123456789:ABC...` part).
|
||||
|
||||
!!! warning "Keep your token secret"
|
||||
Anyone with your bot token can control your bot. Don't commit it to git or share it publicly.
|
||||
|
||||
## 6. Enter your bot token
|
||||
|
||||
Paste your token when prompted:
|
||||
|
||||
```
|
||||
? paste your bot token: ****
|
||||
validating...
|
||||
connected to @my_takopi_bot
|
||||
```
|
||||
|
||||
Takopi validates the token by calling the Telegram API. If it fails, double-check you copied the full token.
|
||||
|
||||
## 7. Pick your workflow
|
||||
|
||||
Takopi shows three workflow previews:
|
||||
|
||||
=== "assistant"
|
||||
|
||||
ongoing chat
|
||||
|
||||
<div class="workflow-preview">
|
||||
<div class="msg msg-you">make happy wings fit</div><div class="clearfix"></div>
|
||||
<div class="msg msg-bot">done · codex · 8s · step 3</div><div class="clearfix"></div>
|
||||
<div class="msg msg-you">carry heavy creatures</div><div class="clearfix"></div>
|
||||
<div class="msg msg-bot">done · codex · 12s · step 5</div><div class="clearfix"></div>
|
||||
<div class="msg msg-you"><span class="cmd">/new</span></div><div class="clearfix"></div>
|
||||
<div class="msg msg-you">add flower pin</div><div class="clearfix"></div>
|
||||
<div class="msg msg-bot">done · codex · 6s · step 2</div><div class="clearfix"></div>
|
||||
</div>
|
||||
|
||||
=== "workspace"
|
||||
|
||||
topics per branch
|
||||
|
||||
<div class="workflow-preview">
|
||||
<div class="topic-bar"><span class="topic-active">happian @memory-box</span><span class="topic">takopi @master</span></div>
|
||||
<div class="msg msg-you">store artifacts forever</div><div class="clearfix"></div>
|
||||
<div class="msg msg-bot">done · codex · 10s · step 4</div><div class="clearfix"></div>
|
||||
<div class="msg msg-you">also freeze them</div><div class="clearfix"></div>
|
||||
<div class="msg msg-bot">done · codex · 6s · step 2</div><div class="clearfix"></div>
|
||||
</div>
|
||||
|
||||
=== "handoff"
|
||||
|
||||
reply to continue
|
||||
|
||||
<div class="workflow-preview">
|
||||
<div class="msg msg-you">make it go back in time</div><div class="clearfix"></div>
|
||||
<div class="msg msg-bot">done · codex · 8s · step 3<br><span class="resume">codex resume <span class="id-1">abc123</span></span></div><div class="clearfix"></div>
|
||||
<div class="msg msg-you">add reconciliation ribbon</div><div class="clearfix"></div>
|
||||
<div class="msg msg-bot">done · codex · 3s · step 1<br><span class="resume">codex resume <span class="id-2">def456</span></span></div><div class="clearfix"></div>
|
||||
<div class="msg msg-you"><div class="reply-quote">done · codex · 8s · step 3</div>more than once</div><div class="clearfix"></div>
|
||||
<div class="msg msg-bot">done · codex · 8s · step 5<br><span class="resume">codex resume <span class="id-1">abc123</span></span></div><div class="clearfix"></div>
|
||||
</div>
|
||||
|
||||
```
|
||||
? how will you use takopi?
|
||||
❯ assistant (ongoing chat, /new to reset)
|
||||
workspace (projects + branches, i'll set those up)
|
||||
handoff (reply to continue, terminal resume)
|
||||
```
|
||||
|
||||
Each choice automatically configures conversation mode, topics, and resume lines:
|
||||
|
||||
| Workflow | Best for | What it does |
|
||||
|----------|----------|--------------|
|
||||
| **assistant** | Single developer, private chat | Chat mode (auto-resume), topics off, resume lines hidden. Use `/new` to start fresh. |
|
||||
| **workspace** | Teams, multiple projects/branches | Chat mode, topics on, resume lines hidden. Each topic binds to a repo/branch. |
|
||||
| **handoff** | Terminal-based workflow | Stateless (reply-to-continue), resume lines always shown. Copy resume line to terminal. |
|
||||
|
||||
!!! tip "Not sure which to pick?"
|
||||
Start with **assistant** (recommended). You can always change settings later in your config file.
|
||||
|
||||
## 8. Connect your chat
|
||||
|
||||
Depending on your workflow choice, Takopi shows different instructions:
|
||||
|
||||
**For assistant or handoff:**
|
||||
|
||||
```
|
||||
step 3: connect chat
|
||||
|
||||
1. open a chat with @my_takopi_bot
|
||||
2. send /start
|
||||
waiting for message...
|
||||
```
|
||||
|
||||
**For workspace:**
|
||||
|
||||
```
|
||||
step 3: connect chat
|
||||
|
||||
set up a topics group:
|
||||
1. create a group and enable topics (settings → topics)
|
||||
2. add @my_takopi_bot as admin with "manage topics"
|
||||
3. send any message in the group
|
||||
waiting for message...
|
||||
```
|
||||
|
||||
Once Takopi receives your message:
|
||||
|
||||
```
|
||||
got chat_id 123456789 for @yourusername (private chat)
|
||||
```
|
||||
|
||||
!!! warning "Workspace requires a forum group"
|
||||
If you chose workspace and the chat isn't a forum-enabled supergroup with proper bot permissions, Takopi will warn you and offer to switch to assistant mode instead.
|
||||
|
||||
## 9. Choose your default engine
|
||||
|
||||
Takopi scans your PATH for installed agent CLIs:
|
||||
|
||||
```
|
||||
step 4: default agent
|
||||
|
||||
takopi runs these agents on your computer. switch anytime with /agent.
|
||||
|
||||
engine status install command
|
||||
───────────────────────────────────────────
|
||||
codex ✓ installed
|
||||
claude ✓ installed
|
||||
opencode ✗ not found npm install -g opencode-ai@latest
|
||||
pi ✗ not found npm install -g @mariozechner/pi-coding-agent
|
||||
|
||||
? choose default agent:
|
||||
❯ codex
|
||||
claude
|
||||
```
|
||||
|
||||
Pick whichever you prefer. You can always switch engines per-message with `/codex`, `/claude`, etc.
|
||||
|
||||
## 10. Save your config
|
||||
|
||||
```
|
||||
step 5: save config
|
||||
|
||||
? save config to ~/.takopi/takopi.toml? (yes/no)
|
||||
```
|
||||
|
||||
Press **y** or **Enter** to save. You'll see:
|
||||
|
||||
```
|
||||
✓ setup complete. starting takopi...
|
||||
```
|
||||
|
||||
Takopi is now running and listening for messages!
|
||||
|
||||
## What just happened
|
||||
|
||||
Your config file lives at `~/.takopi/takopi.toml`. The exact contents depend on your workflow choice:
|
||||
|
||||
=== "assistant"
|
||||
|
||||
```toml title="~/.takopi/takopi.toml"
|
||||
default_engine = "codex"
|
||||
transport = "telegram"
|
||||
|
||||
[transports.telegram]
|
||||
bot_token = "..."
|
||||
chat_id = 123456789
|
||||
session_mode = "chat" # auto-resume
|
||||
show_resume_line = false # cleaner chat
|
||||
|
||||
[transports.telegram.topics]
|
||||
enabled = false
|
||||
scope = "auto"
|
||||
```
|
||||
|
||||
=== "workspace"
|
||||
|
||||
```toml title="~/.takopi/takopi.toml"
|
||||
default_engine = "codex"
|
||||
transport = "telegram"
|
||||
|
||||
[transports.telegram]
|
||||
bot_token = "..."
|
||||
chat_id = -1001234567890 # forum group
|
||||
session_mode = "chat"
|
||||
show_resume_line = false
|
||||
|
||||
[transports.telegram.topics]
|
||||
enabled = true # topics on
|
||||
scope = "auto"
|
||||
```
|
||||
|
||||
=== "handoff"
|
||||
|
||||
```toml title="~/.takopi/takopi.toml"
|
||||
default_engine = "codex"
|
||||
transport = "telegram"
|
||||
|
||||
[transports.telegram]
|
||||
bot_token = "..."
|
||||
chat_id = 123456789
|
||||
session_mode = "stateless" # reply-to-continue
|
||||
show_resume_line = true # always show resume lines
|
||||
|
||||
[transports.telegram.topics]
|
||||
enabled = false
|
||||
scope = "auto"
|
||||
```
|
||||
|
||||
This config file controls all of Takopi's behavior. You can edit it directly to change settings or add advanced features.
|
||||
|
||||
[Full config reference →](../reference/config.md)
|
||||
|
||||
## Re-running onboarding
|
||||
|
||||
If you ever need to reconfigure:
|
||||
|
||||
```sh
|
||||
takopi --onboard
|
||||
```
|
||||
|
||||
This will prompt you to update your existing config (it won't overwrite without asking).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"error: missing takopi config"**
|
||||
|
||||
Run `takopi` in a terminal with a TTY. The setup wizard only runs interactively.
|
||||
|
||||
**"failed to connect, check the token and try again"**
|
||||
|
||||
Make sure you copied the full token from BotFather, including the numbers before the colon.
|
||||
|
||||
**Bot doesn't respond to /start**
|
||||
|
||||
If you're still in onboarding, your terminal should show "waiting...". If you accidentally closed it, run `takopi` again and restart the setup.
|
||||
|
||||
**"error: already running"**
|
||||
|
||||
You can only run one Takopi instance per bot token. Find and stop the other process, or remove the stale lock file at `~/.takopi/takopi.lock`.
|
||||
|
||||
## Next
|
||||
|
||||
Learn more about conversation modes and how your workflow choice affects follow-ups.
|
||||
|
||||
[Conversation modes →](conversation-modes.md)
|
||||
+1
-1
@@ -4,7 +4,7 @@ This guide has been reorganized into smaller Diátaxis pages.
|
||||
|
||||
## Start here
|
||||
|
||||
- [Install & onboard](tutorials/install-and-onboard.md)
|
||||
- [Install & onboard](tutorials/install.md)
|
||||
- [First run](tutorials/first-run.md)
|
||||
|
||||
## Common tasks
|
||||
|
||||
Reference in New Issue
Block a user