Takopi Setup

Takopi is a Telegram bot that provides a chat interface to Claude Code.

GitHub: https://github.com/nuclearthinking/takopi

Prerequisites

• Python 3.10+
• uv (Python package manager)
• Telegram Bot Token (from @BotFather)
• Claude Code installed and authenticated (via claude login)

Step 1: Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Step 2: Install Takopi

uv tool install takopi

Step 3: Configure

Create ~/.takopi/takopi.toml:

default_engine = "claude"
transport = "telegram"
 
[transports.telegram]
bot_token = "YOUR_BOT_TOKEN"  # From @BotFather
chat_id = -123456789          # Your chat ID
allowed_user_ids = [123456789]  # Your Telegram user ID
 
[projects.default]
path = "/home/ubuntu/claude-workspace"
default_engine = "claude"
 
[claude]
dangerously_skip_permissions = true
allowed_tools = ["Bash", "Read", "Edit", "Write"]

To get your Telegram user ID, message @userinfobot.

Note: Takopi uses Claude Code CLI under the hood. Make sure you’ve run claude login first to authenticate via OAuth.

Step 4: Create Start Script

Create ~/start-takopi.sh:

#!/bin/bash
while true; do
    echo "Starting Takopi..."
    takopi run 2>&1 | tee -a ~/takopi.log
    echo "Takopi stopped. Restarting in 5 seconds..."
    sleep 5
done

Make it executable:

chmod +x ~/start-takopi.sh

Step 5: Create Stop Script

Create ~/stop-takopi.sh:

#!/bin/bash
# Kill the restart loop
pkill -f "start-takopi.sh"
# Kill takopi itself
if [ -f ~/.takopi/takopi.pid ]; then
    kill $(cat ~/.takopi/takopi.pid) 2>/dev/null
fi
pkill -f "takopi run"
echo "Takopi stopped"

Make it executable:

chmod +x ~/stop-takopi.sh

Step 6: Run

# Start in background
nohup ~/start-takopi.sh &
 
# Or in tmux
tmux new -s takopi
~/start-takopi.sh
# Ctrl+B, D to detach

Adding Plugins

Takopi supports plugins for custom commands.

Create Plugin

Create a new directory with pyproject.toml:

[project]
name = "takopi-myplugin"
version = "0.1.0"
dependencies = ["takopi"]
 
[project.entry-points."takopi.commands"]
mycommand = "takopi_myplugin.backend:MyCommand"

Create takopi_myplugin/backend.py:

from takopi.commands import CommandBackend, CommandResult
from takopi.context import Context
 
class MyCommand(CommandBackend):
    name = "mycommand"
    description = "My custom command"
 
    async def execute(self, ctx: Context, args: str) -> CommandResult:
        return CommandResult(text="Hello from my command!")

Install Plugin

uv pip install -e /path/to/plugin \
  --python ~/.local/share/uv/tools/takopi/bin/python

Restart Takopi

~/stop-takopi.sh
nohup ~/start-takopi.sh &

Logs

View logs:

tail -f ~/takopi.log

Tips

• Use /help in Telegram to see available commands
• Bot only responds to users in allowed_users list
• Restart after config changes