Messaging the bot is like typing claude in a shell — same tools, skills, and config. It is your local CLI: /resume picks up any session from the terminal. The bot is a thin stateless router; the CLI owns everything.

✨ Highlights

🚀 Quick start

Claude Code is the prerequisite — so let it install its own bridge. Send it this on the machine that should host the bot:

setup https://github.com/xhyumiracle/tg-claude-bot

This README is the runbook; it will only ask you for the @BotFather token and your user id.

Manual setup

1. Prerequisites — Claude Code CLI installed and logged in, plus uv.

2. Create your bot — @BotFather → /newbot → copy the token. For groups: disable privacy mode (/setprivacy) or make the bot admin.

3. Find your user id — message @userinfobot.

4. Install & configure

git clone https://github.com/xhyumiracle/tg-claude-bot && cd tg-claude-bot
uv sync                 # add --extra voice for local voice transcription
cp .env.example .env && chmod 600 .env   # fill in TG_BOT_TOKEN and OWNER_USER_ID

5. Run it

uv run python bot.py

DM your bot /status — you're live.

Run as a service (recommended)

Once the foreground run works, put it under systemd so it stays reachable when you're away:

# edit the YOUR_USER paths in tg-claude-bot.service first
sudo cp tg-claude-bot.service /etc/systemd/system/
sudo systemctl enable --now tg-claude-bot
journalctl -u tg-claude-bot -f          # watch the logs

Deploy an update with touch ~/.tgclaude/restart-requested — the bot restarts once every conversation is idle, so no reply is cut off. Even a hard crash loses nothing: topics rebind and interrupted turns resume from the transcript.

Configuration

All in .env (see .env.example):

⚖️ How it compares

Deliberate trade-off: no attaching to a live terminal (what tmux bridges like ccbot do) — in exchange, structured events and statelessness.

One turn, end to end: voice → local transcript → live status → clarifying question as buttons.

⌨️ Commands

/ autocompletes in Telegram — the menu is registered via setMyCommands.

🏗 Architecture

Telegram ── python-telegram-bot ── bot.py (stateless router)
                                     │  claude-agent-sdk (one client per chat/topic)
                                     └─ Claude Code CLI ── ~/.claude/projects/*.jsonl

Conversation state lives in the CLI's own files; the bot keeps only a tiny pointer file (~/.tgclaude/) — which topic resumes which session, plus what was mid-flight. Kill the bot — or the power — and topics rebind, interrupted turns continue automatically.

🔒 Security model

• Allowlisted chats only; everything else is ignored.
• All secrets live in .env (chmod 600) — never in the systemd unit, which is world-readable.
• Owner: full permissions. Guests: scoped read/write and a custom prompt; out-of-scope tool calls escalate to the owner as Allow/Deny buttons.
• ! bash mode is the one deliberate shell surface: owner-typed messages only — forwarded text never executes, guests never reach it.
• Session management commands are owner-gated everywhere; so is /mode — permission modes change the guardrails themselves, and bypass permissions disables the guest sandbox for that conversation.
• /login relays the CLI's own claude setup-token flow; the resulting token goes straight into .env and is never echoed to the chat (prefix only). Owner-typed messages only, 5-minute window, /esc cancels.
• Voice notes are transcribed locally and deleted; images follow the CLI's transcript retention.
• Full threat model, verified controls, and accepted risks: SECURITY_AUDIT.md — a line-by-line self-audit by the model this bot bridges.

🙅 Non-goals

• Attaching to a live terminal — see the comparison above.
• Replicating TUI-only dialogs (/config etc.); what matters is rebuilt as bot commands (/model, /effort, /usage).
• Being a framework. It's one file — read it, fork it, make it yours.