Messaging the bot is like typing claude in a shell: fresh session, same
tools, skills, and config — it is your local CLI. /resume picks up any
session you left in 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)

The whole point is being reachable when you're away from the machine, so once
the foreground run works, put it under systemd:

# 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

To deploy an update gracefully: touch ~/.tgclaude/restart-requested — the bot
restarts as soon as every conversation is idle, so no reply is ever cut off.
Even on a hard crash nothing is lost: topics rebind to their sessions, and
interrupted turns resume with continue (the CLI transcript has everything).

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.
• 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.
• 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.