banteg
141 lines
4.1 KiB
Markdown
141 lines
4.1 KiB
Markdown
# 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)
|
||
|
||
</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.
|
||
|
||
## Core concepts
|
||
|
||
* **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:
|
||
|
||
* 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
|
||
|
||
Start here:
|
||
|
||
* [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)
|
||
|
||
If you’re contributing to core:
|
||
|
||
* [Dev setup](how-to/dev-setup.md)
|
||
* [Module map](explanation/module-map.md)
|
||
|
||
## For LLM agents
|
||
|
||
In the docs, start here:
|
||
|
||
* [Reference: For agents](reference/agents/index.md)
|
||
* [Repo map](reference/agents/repo-map.md)
|
||
* [Invariants](reference/agents/invariants.md)
|
||
|
||
## Where to look when something feels “off”
|
||
|
||
* “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
|
||
|
||
These pages remain as curated pointers to preserve old links:
|
||
|
||
- [User guide](user-guide.md)
|
||
- [Plugins](plugins.md)
|
||
- [Developing](developing.md)
|