snqb takopi — Telegram Bridge for Coding Agents
Repo: banteg/takopi (761⭐) Docs: takopi.dev
What It Does
Telegram ↔ agent CLI bridge. Send messages from Telegram, agent runs on your server, streams progress back. Supports pi, Claude Code, Codex, OpenCode as engines.
Install
uv tool install -U takopi
Requires: uv, Python 3.14+, at least one engine CLI on PATH (pi, claude, codex, opencode).
Quick Start
cd ~/my-project
takopi # setup wizard on first run
takopi --onboard # re-run wizard
takopi --debug # debug logging to debug.log
takopi doctor # validate telegram + config
Telegram Commands
| Command | Description |
|---|---|
/<engine> |
Use engine for this message: /pi, /claude, /codex, /opencode |
/<project> |
Target a registered project |
@branch |
Run in a git worktree for that branch |
/cancel |
Reply to progress message to stop run |
/new |
Clear session, start fresh thread |
/agent |
Show current default engine |
/agent set <engine> |
Set default engine for chat/topic |
/agent clear |
Remove default engine |
/ctx |
Show current context binding |
/ctx set <project> [@branch] |
Bind context |
/ctx clear |
Remove context binding |
/model |
Show/set model override |
/file put <path> |
Upload file to repo (needs file transfer enabled) |
/file get <path> |
Fetch file/dir from repo (dirs auto-zipped) |
/topic <project> @branch |
Create/bind forum topic |
Directive Combinations
/pi fix the auth bug # engine only
/dota read the README # project only
/dota @feat/new-detector improve accuracy # project + branch
/claude /dota @main refactor pipeline # engine + project + branch
Directives are parsed from the start of the first line only. Order doesn't matter.
Projects
Register a project
cd ~/mobile-research/twitch-autohighlights-dota2
takopi init dota
Or via config:
takopi config set projects.dota.path "~/mobile-research/twitch-autohighlights-dota2"
takopi config set projects.dota.default_engine "pi"
TOML equivalent (~/.takopi/takopi.toml)
[projects.dota]
path = "~/mobile-research/twitch-autohighlights-dota2"
default_engine = "pi"
[projects.research]
path = "~/mobile-research"
default_engine = "pi"
Set default project
takopi config set default_project "research"
Use from Telegram
/dota explain the highlight detection pipeline
/dota @feat/audio add audio-based detection
/research find papers on game highlight detection
Reply to continue in the same project+branch context (the ctx: footer carries forward).
Worktrees
Run on feature branches without touching main checkout:
takopi config set projects.dota.worktrees_dir ".worktrees"
takopi config set projects.dota.worktree_base "main"
/dota @feat/audio-detect add whisper-based kill detection
Creates .worktrees/feat/audio-detect as a git worktree.
Conversation Modes
| Workflow | Session Mode | Topics | Resume Lines |
|---|---|---|---|
| assistant | chat (auto-resume) | off | hidden |
| workspace | chat | on (forum topics) | hidden |
| handoff | stateless | off | shown |
Chat mode (recommended for personal use)
Just send messages — auto-resumes the current thread. /new to reset.
takopi config set transports.telegram.session_mode "chat"
takopi config set transports.telegram.show_resume_line false
Stateless mode
Every message is independent. Reply to a message to continue that session.
Engine Config
Pi engine
[pi]
model = "claude-opus-4-6"
provider = "anthropic"
extra_args = []
takopi config set pi.model "claude-opus-4-6"
takopi config set pi.provider "anthropic"
Claude Code engine
[claude]
model = "claude-sonnet-4-5-20250929"
allowed_tools = ["Bash", "Read", "Edit", "Write"]
dangerously_skip_permissions = false
Engine selection precedence (highest wins)
- Resume token (from reply)
- Explicit directive (
/claude ...) - Topic default (
/agent set) - Chat default (
/agent set) - Project default (
default_engine) - Global default (
default_engineat top level)
File Transfer
takopi config set transports.telegram.files.enabled true
takopi config set transports.telegram.files.auto_put true
- Upload files: attach document or
/file put docs/spec.pdf - Download files:
/file get src/main.py - Dirs auto-zipped on download
- 20 MiB upload / 50 MiB download limits
Voice Notes
takopi config set transports.telegram.voice_transcription true
Requires OPENAI_API_KEY in environment. Transcribes voice → runs as text prompt.
Forum Topics (Workspace Mode)
Bind Telegram forum threads to project+branch:
takopi config set transports.telegram.topics.enabled true
takopi config set transports.telegram.topics.scope "auto"
Inside a topic: /topic dota @feat/audio to bind it.
Schedule Tasks
Use Telegram's built-in schedule: long-press send → Schedule Message.
Config Hot-Reload
takopi config set watch_config true
Edit ~/.takopi/takopi.toml while takopi is running — changes apply immediately (except transport).
CLI Reference
| Command | Description |
|---|---|
takopi |
Start (runs wizard if no config) |
takopi <engine> |
Start with specific engine |
takopi init <alias> |
Register current repo as project |
takopi chat-id |
Capture current chat ID |
takopi doctor |
Validate config + Telegram |
takopi plugins |
List plugins |
takopi config list |
Show all config |
takopi config get <key> |
Get config value |
takopi config set <key> <value> |
Set config value |
Full Config Reference (~/.takopi/takopi.toml)
watch_config = true
default_engine = "pi"
default_project = "research"
transport = "telegram"
[transports.telegram]
bot_token = "..."
chat_id = 123456789
allowed_user_ids = [123456789]
session_mode = "chat"
show_resume_line = false
message_overflow = "split" # "trim" | "split"
voice_transcription = false
[transports.telegram.files]
enabled = true
auto_put = true
auto_put_mode = "upload" # "upload" | "prompt"
uploads_dir = "incoming"
[transports.telegram.topics]
enabled = false
scope = "auto" # "auto" | "main" | "projects" | "all"
[pi]
model = "claude-opus-4-6"
provider = "anthropic"
extra_args = []
[claude]
model = "claude-sonnet-4-5-20250929"
allowed_tools = ["Bash", "Read", "Edit", "Write"]
[projects.dota]
path = "~/mobile-research/twitch-autohighlights-dota2"
default_engine = "pi"
worktrees_dir = ".worktrees"
worktree_base = "main"
[projects.research]
path = "~/mobile-research"
default_engine = "pi"
Troubleshooting
| Issue | Fix |
|---|---|
| Bot doesn't respond | Check takopi is running in tmux. takopi doctor |
| "unknown project" | Run takopi init <alias> in the repo first |
| Engine CLI not found | Install engine, ensure it's on PATH |
| Resume doesn't work | Reply to message with resume line, or use chat mode |
| Progress stuck on "starting" | Agent doing slow work, or /cancel and retry |
| Context not carrying forward | Reply to ctx: message, or set default_project |
Docs Index
- Install: tutorials/install.md
- First run: tutorials/first-run.md
- Projects: how-to/projects.md
- Worktrees: how-to/worktrees.md
- File transfer: how-to/file-transfer.md
- Topics: how-to/topics.md
- Voice: how-to/voice-notes.md
- Config: reference/config.md
- Commands: reference/commands-and-directives.md
- Context: reference/context-resolution.md
- Plugins: docs/plugins.md