ayu-bot

A sidekick to Claude Code, reachable over Telegram, on your own server.

Message a bot from your phone and it runs a Claude Code session on your machine, then replies. Send a voice note and it's transcribed; ask for a file and it comes back; start a long job and it pings you when it's done. It's one bot.py and a few small scripts — worth reading before you run it.

It's a sidekick, not a replacement. The heavy lifting still happens in Claude Code at the desk — that's where most of the work actually gets done. This is for the in-between moments: firing off a task from your phone, nudging something along, or a quick question or fix when you're away from the keyboard.

A note on trust. ayu-bot runs Claude Code with permissions bypassed, so whoever the bot accepts messages from can control the server it runs on. The ALLOWED_USER_IDS setting — your Telegram ID, and no one else's — is what keeps that door shut. Run it somewhere you're happy to give an agent that much room, and read bot.py first.

Cost & the rules. ayu-bot is a thin bridge — it drives the same Claude Code you already run, so it's billed exactly the way Anthropic bills Claude Code, with nothing added on top. As of mid-2026 that means API pricing, offset by monthly credits equal to the value of your Claude subscription. It's built to stay within Anthropic's terms and usage policies — it doesn't try to route around anything. It is what it is.

Install in one line

Open Claude Code on the server you want to run it on, and paste this:

Install ayu-bot on this server: fetch https://ayubot.xyz/ayu-bot/install.txt and follow it, asking me for any tokens it needs.

It downloads the code, shows you what it's about to run, sets up a virtual environment, and walks you through making your bot — pausing to ask for your Telegram token and user ID along the way. When it's finished, you message your bot and it answers.

What you'll need

A Linux server — a small VPS is plenty.
Claude Code already installed and signed in on it (which claude should print a path). ayu-bot just drives it.
Python 3.10 or newer, and a Telegram account.

Prefer to install by hand?

Download ayu-bot.tar.gz 18 KB · sha256 c123ff9f5e4c43a5009d5915ac64e96630c1945942f28d66391eb6ddcb175a57

Create your bot: message @BotFather, send /newbot, copy the token.
Get your user ID: message @userinfobot, copy the number.

Unpack and set up:

tar xzf ayu-bot.tar.gz && cd ayu-bot
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env

Edit .env — set TELEGRAM_BOT_TOKEN, ALLOWED_USER_IDS (your id only) and CLAUDE_CODE_PATH (from which claude).
Start it, then message your bot:
```
./run.sh
```

Keep it running

Use a process manager so it survives reboots and crashes:

pm2 start run.sh --name ayu-bot
pm2 save

A systemd unit example is in the README.md inside the tarball.

Configuration

Everything lives in .env:

Key	Notes
`TELEGRAM_BOT_TOKEN`	from @BotFather
`ALLOWED_USER_IDS`	your Telegram id(s), comma-separated — yours only
`CLAUDE_CODE_PATH`	output of `which claude`
`CLAUDE_MODEL`	optional — defaults to `claude-opus-4-8`; `claude-sonnet-4-6` is cheaper
`OPENAI_API_KEY`	optional — turns on voice-note transcription

Provided as-is, no warranty — your server, your keys, your responsibility. It's small on purpose; read bot.py before you run it.

← Back to the AI Log blog