🐙 he just wants to help-pi
i was running claude code from my couch when i realized something was wrong. the terminal was on my desk, but my ideas were here. same story with codex, opencode, pi. all these agents that want to write code for me, trapped behind an ssh session.
if you’ve ever:
- started an agent run, walked away, and came back to a wall of scrollback
- wanted one place to keep agent sessions across devices
- needed to juggle repos and branches without turning your shell into a museum
that’s the whole point.
takopi bridges your coding agents to telegram. send a message from anywhere, it runs the agent in your repo, streams progress back. when it’s done, you get a notification. reply to continue. pick up when back at the terminal.
why telegram
telegram is everywhere. it’s on my phone, my watch, my browser. i can dictate a task while walking the dogs, check progress from bed, and resume the conversation at my desk. the bot api is also very capable: inline keyboards, forum topics, voice notes. it all just works.
pick your workflow
takopi adapts to how you want to work. during setup, you’ll choose one of three workflows:
assistant — ongoing chat. new messages continue the conversation; use /new to start fresh. best for solo work and natural back-and-forth.
workspace — forum topics bound to projects and branches. each topic is its own context and worktree, so you can run parallel workstreams. best for organized multi-repo setups or even teams.
handoff — reply-to-continue with resume lines you can copy to your terminal. every message is independent until you explicitly reply. best for terminal-first workflows and explicit control.
you can change your workflow anytime by editing the config file or re-running onboarding.
getting started
uv tool install -U takopi
takopithat’s it. takopi detects there’s no config and walks you through setup:
- create a bot — if you don’t have a telegram bot yet, it shows you how to get one from @BotFather
- pick your workflow — assistant, workspace, or handoff
- connect your chat — send
/startto your bot and takopi grabs your chat id - choose a default engine — takopi scans for installed agents (codex, claude, opencode, pi)
config lands in ~/.takopi/takopi.toml. re-run setup anytime with takopi --onboard.
install agents
takopi runs agents installed on your computer. install the ones you plan to use:
npm install -g @openai/codex
npm install -g @anthropic-ai/claude-code
npm install -g opencode-ai@latest
npm install -g @mariozechner/pi-coding-agentthey work with your existing subscriptions for chatgpt and claude. takopi doesn’t cost you anything extra.
your first task
start takopi in a repo:
cd ~/dev/happy-gadgets
takopiopen telegram, send a message to your bot:
explain what this repo does
watch progress stream in. when it’s done, you get a final message with the answer. continue by sending another message (in chat mode) or replying (in handoff mode).
switch engines on the fly
prefix any message with the engine name:
/claude refactor the auth module
replies automatically route to the same engine. set a default for the current chat with /agent set claude.
projects
for repos you work with often, register them:
cd ~/dev/happy-gadgets
takopi init happy-gadgetsnow you can target it from anywhere:
/happy-gadgets add rate limiting
no need to restart takopi or cd around.
branches
work on feature branches without switching:
/happy-gadgets @feat/caching implement redis caching
takopi creates a worktree and runs the agent there. your main checkout stays untouched, and you can have multiple branches running in parallel.
voice notes
enable transcription and dictate your tasks. takopi converts speech to text and runs it like any other message. perfect for when you’re away from the keyboard.
happy coding
the whole point is removing friction. i want to think about the code, not about where my terminal is. takopi sits in the background and makes agents accessible from wherever i happen to be.
install: uv tool install -U takopi
docs: takopi.dev
code: github.com/banteg/takopi
