CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this project is

A Telegram bot that remote-controls a headless Claude Code session via the Python Claude Agent SDK. The user texts the bot from their phone; Claude runs in a project directory on the host (reading/editing files, running commands) and streams replies back. Permission handling is a live control panel in Telegram — the user can flip between ask / allowlist / auto modes mid-conversation.

Commands

pip install -r requirements.txt   # deps: claude-agent-sdk, python-telegram-bot v21+, python-dotenv
python main.py                    # run the bot (long-polling); needs a filled-in .env
python -m py_compile config.py state.py claude_runner.py telegram_bot.py main.py  # syntax check

# Import smoke test without a real token:
TELEGRAM_BOT_TOKEN=dummy ALLOWED_USER_IDS=123 python -c "import telegram_bot; telegram_bot.build_application()"

There is no test suite yet. A real end-to-end test requires a Telegram bot token and an authenticated claude CLI (the SDK reuses its login).

Architecture

Flow: Telegram update → telegram_bot.py handler → claude_runner.run_query() → Claude Agent SDK → events streamed back → Telegram messages.

The critical mechanism is the permission bridge: the SDK's can_use_tool is an async callback, so when Claude wants a tool that isn't auto-approved, the callback sends inline Approve/Deny/Always buttons to Telegram and awaits an asyncio.Future that the button's CallbackQueryHandler resolves (telegram_bot._pending, keyed by a counter-based approval id — Telegram callback_data is capped at 64 bytes, so keep ids short).

• state.py — Session (one per Telegram chat, held in SessionStore): cwd, model, permission mode, tool allowlist, Claude claude_session_id, busy flag. Handlers mutate it live; the permission callback reads it at call time, which is what makes settings changes take effect mid-run without restarting anything.
• claude_runner.py — creates a fresh ClaudeSDKClient per user message, passing resume=session.claude_session_id for continuity (captured from each ResultMessage). Yields typed events (TextEvent/ToolEvent/DoneEvent/ ErrorEvent) so the bot layer never touches SDK message types. Tracks in-flight clients in _active_clients so /stop can interrupt().
• telegram_bot.py — handlers + control panel + _StreamRenderer, which edits one live Telegram message as text streams and rolls over past the 4096-char cap (TG_LIMIT = 4000).
• config.py — env-backed config; refuses to start with an empty ALLOWED_USER_IDS (the bot is an RCE surface; the allowlist is the only gate).

Non-obvious design decisions

• permission_mode="default" + setting_sources=[] are set deliberately so that every dangerous tool call routes through can_use_tool and no local settings file can silently pre-approve tools. Don't "fix" either without understanding this. (Caveat: the SDK may auto-approve read-only tools regardless.)
• Our permission-mode vocabulary (ask/allowlist/auto in state.PERMISSION_MODES) is intentionally not the SDK's PermissionMode — all mode logic lives in our callback so it can be switched live from Telegram.
• Streamed Claude output is sent without parse_mode (arbitrary markdown breaks Telegram's parser); only bot-authored control messages use Markdown.

Project knowledge wiki

docs/wiki/ holds accumulated knowledge: architecture details, ADR-style decisions, and hard-won API facts (Agent SDK, Telegram Bot API). Consult it before working on an area it covers, and update it when you learn something durable or change the design — see .claude/skills/wiki/SKILL.md for the workflow.

Conventions

• Git commits: plain messages, no Co-Authored-By trailer.
• Secrets live only in .env (git-ignored); .env.example is the template.