Introducing Takopi

Your Coding Agents, Anywhere

takopi

🐙 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.

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.

features

multi-agent: prefix with /codex, /claude, /opencode, or /pi to pick your engine. replies automatically route to the same agent.

projects and worktrees: register a repo with takopi init happy-gadgets, then target it from anywhere with /happy-gadgets shrink and store artifacts forever. add @feat/happy-camera to spin up a worktree.

stateless resume: every response includes a resume line. reply to continue in telegram, or copy it to your terminal. session state lives in the agent, not in takopi.

copy a resume line into your terminal and you’re back in the same session. move between phone and laptop without losing context.

progress streaming: watch commands run, tools fire, files change. you see what the agent sees, updating in real time.

forum topics: bind telegram threads to project/branch pairs. each topic maintains its own session, so you can have multiple parallel workstreams.

voice notes: enable transcription and dictate your tasks. takopi converts speech to text and runs it like any other message.

per-project routing: give each project its own chat. messages from that chat automatically target the right repo.

getting started

uv tool install -U takopi
takopi

takopi will walk you through creating a bot token, capturing your chat id, and picking the default engine. config lands in ~/.takopi/takopi.toml.

make sure at least one agent cli is installed and on your PATH:

npm install -g @openai/codex
npm install -g @anthropic-ai/claude-code

takopi works seamlessly with your openai and anthropic subscriptions, it doesn’t require setting up any api keys.

a simple handoff

cd ~/dev/happy-gadgets
takopi

open telegram, send a message to your bot:

render a diorama of this timeline

watch progress stream in. when it’s done, you get a final message with the answer and a resume token. reply with more instructions to continue.

projects

for repos you work with often:

cd ~/dev/happy-gadgets
takopi init happy-gadgets

now you can target it from anywhere:

/happy-gadgets hard reset the timeline

worktrees

work on multiple branches without switching:

/happy-gadgets @feat/happy-camera rewind to checkpoint

takopi creates a worktree at .worktrees/feat/happy-camera and runs the agent there. you can work on multiple branches simultaneously without the agents fighting with each other.

takopi adds a ctx: footer to messages with project and branch info. when you reply, that context carries forward—no need to repeat /project @branch each time.

topics

for more advanced projects you can use group chats in topics mode.

bind telegram topics to specific contexts. each topic remembers its project, branch, and session state.

[transports.telegram.topics]
enabled = true

context is auto-scoped based on your setup:

one chat for everything — topics per project/branch:

all projects
takopi @master
takopi @feat/topics
happy-gadgets @master
happy-gadgets @feat/happy-camera

per-project chats — each project has its own forum group. the project is inferred from the chat:

takopi
takopi @master
takopi @feat/topics
takopi @feat/voice

happy-gadgets
happy-gadgets @master
happy-gadgets @feat/happy-camera
happy-gadgets @feat/memory-box

create a topic with /topic happy-gadgets @feat/camera, and all messages in that thread route to the right place. /ctx shows the current binding, /new clears stored sessions.

parallel runs

takopi queues messages per-agent thread but runs different agents/threads in parallel. you can fire off three tasks to three different branches or agents and watch them all progress simultaneously.

extending

takopi supports plugins via python entrypoints. add new engines, transports, or slash commands without touching core code.

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

code: github.com/banteg/takopi