takopi

🐙 he just wants to help-pi

telegram bot for codex. runs codex exec --json, streams progress, and supports resumable sessions.

features

stateless resume via codex resume <token> lines in chat.

edits a single progress message while codex runs (commands, tools, notes, file changes, elapsed time).

renders markdown to telegram entities.

runs in parallel across threads and queues per thread to keep codex history sane.

requirements

• uv for installation (curl -LsSf https://astral.sh/uv/install.sh | sh)
• codex on PATH (npm install -g @openai/codex or brew install codex)

install

• uv tool install takopi to install as takopi
• or try it with uvx takopi

setup

1. get bot_token from @BotFather
2. get chat_id from @myidbot
3. send /start to the bot (telegram won't let it message you first)
4. run codex once interactively in the repo to trust the directory

config

takopi reads .takopi/takopi.toml in the current repo, otherwise ~/.takopi/takopi.toml. legacy .codex/takopi.toml is migrated automatically.

bot_token = "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
chat_id = 123456789

[codex]
# optional: profile from ~/.codex/config.toml
profile = "takopi"

usage

start takopi in the repo you want to work on:

cd ~/dev/your-repo
takopi

send a message to the bot.

to continue a thread, reply to a bot message containing a resume line.

to stop a run, reply to the progress message with /cancel.

cli

default: progress is silent, final answer is sent as a new message (notification), progress message is deleted.

--no-final-notify edits the progress message into the final answer (no new notification).

--debug enables verbose logs.

notes

• private chat only
• run exactly one instance per bot token

development

see docs/specification.md and docs/developing.md.