The Problem
Managing multiple repos and branches while juggling tools like codex, claude, and pi can be a dumpster fire. Switching contexts between your terminal, chat apps, and project management tools often feels like playing whack-a-mole with your productivity. Need to resume a task you started last week or sync files across projects? Good luck digging through your Git history and chat logs. There's no clean way to tie it all together—until now.
What This Does
takopi acts as a glue layer between tools like Anthropic's claude, OpenAI's codex, and the Telegram API. It helps you manage projects, branches, and task queues with minimal friction. The core functionality lives in src/takopi, where modules like runner.py, router.py, and worktrees.py handle things like running commands across multiple agent sessions, mapping group chat topics to repo contexts, and managing Git worktrees.
The Telegram integration is robust. The src/takopi/telegram folder covers everything from chat sessions (chat_sessions.py) to file transfer (files.py) and voice notes (voice.py). Want to trigger a specific command from a Telegram chat? The /commands directory has handlers for things like /codex or /pi. The docs/how-to folder provides solid setup instructions, breaking down workflows like "assistant mode" (ongoing chats) or "workspace mode" (repo-branch mapping).
Plugins are supported via entrypoints—extend functionality for engines, transports, or commands by following the guides in docs/how-to/write-a-plugin.md and docs/reference/plugin-api.md.
Real-World Use
Imagine you're managing a project with multiple branches: main, feat/memory-box, and fix/urgent-bug. You want to run a codex engine to freeze the artifacts on feat/memory-box. Fire up your bot and hit it with:
Want to switch engines mid-task? Just reply /pi. The state resumes like magic. Forget where you left off on fix/urgent-bug? The bot spits out a resume command for your terminal: takopi run --resume.
Got files to transfer between your local repo and your bot? Use /fetch and /send commands to grab directories or push assets. It's like having Git and a project manager in your pocket.
The Bottom Line
takopi is a lifesaver if you're deep into multi-engine workflows and Git-heavy projects. The Telegram integration is slick, and the stateless resume feature is genuinely useful. But let’s be real: this isn't for casual devs or small repos—it’s overkill if all you do is commit and push. If you're managing multiple branches, tools, or AI agents, though? Worth a shot.