homelab/.planning/PROJECT.md

Telegram Claude Code Bridge

What This Is

A Telegram bot frontend for Claude Code that lets Mikkel chat with Claude naturally from Telegram, with full tool access to the homelab. Messages flow through the existing Telegram bot to Claude Code CLI sessions, with session management, idle timeout, and file handling — turning Telegram into a mobile terminal for Claude Code.

Core Value

Frictionless conversation with Claude Code from anywhere via Telegram — no SSH, no manual inbox checking, just message and get a response.

Requirements

Validated

• ✓ Telegram bot receives messages and saves to inbox — existing
• ✓ CLI helper sends messages back to Telegram — existing
• ✓ Bot handles photos and files — existing
• ✓ Helper scripts (pve, dns, pbs, beszel, kuma, etc.) available — existing

Active

• Auto-respond: incoming Telegram message triggers Claude Code session that reads and responds
• Session management: path-based sessions (~/telegram/sessions/<name>/) with own Claude Code history and files
• Session switching: /session <name> command in Telegram to switch active session
• Session listing: /sessions command showing all sessions sorted by last activity
• Session creation: /new <name> creates a session; first-ever message auto-creates a default session
• Default session: messages go to last active session unless explicitly switched
• Idle timeout: configurable timer that gracefully suspends Claude Code session after inactivity
• Session resume: suspended sessions resume with full conversation history via claude --resume
• Cost-efficient polling: Haiku-based loop monitors for new messages, only spawns/resumes Opus session when needed
• Output modes: default shows final answer + tool-call progress notifications; toggleable /verbose (stream everything) and /smart (smart truncation with file attachments)
• File handling: any file type/size attached in Telegram gets saved to session folder and made available to Claude
• Full tool access: Claude Code sessions have same capabilities as terminal (SSH, helper scripts, file ops)

Out of Scope

• Multi-user support — personal use only, single admin
• Web UI — Telegram is the interface
• Rate limiting / abuse prevention — trusted single user
• Message encryption beyond Telegram's built-in — trusted environment

Context

• Existing Telegram bot runs as systemd user service (telegram-bot.service) on mgmt container (102)
• Bot written in Python using python-telegram-bot library
• Current bot handles: /status, /pbs, /backups, /beszel, /kuma, /ping commands
• Text messages saved to ~/homelab/telegram/inbox.json, photos to telegram/images/, files to telegram/files/
• Claude Code CLI available on mgmt container, supports --resume for session continuation
• Helper scripts in ~/bin/ provide API access to all homelab services
• Python venv at ~/venv with dependencies installed

Constraints

• Runtime: Python, must integrate with existing telegram bot codebase
• Container: Runs on mgmt LXC (102), 4GB RAM, 4 CPU — must be resource-conscious
• Cost: Haiku for polling/monitoring, Opus only for actual conversation — minimize API spend
• Single user: Only Mikkel's Telegram account interacts with the bot
• Systemd: Must run as systemd user service like existing bot

Key Decisions

Decision	Rationale	Outcome
Claude Code CLI over raw API	Gets full tool access, --resume support, and all Claude Code features for free	— Pending
Haiku polling + Opus conversation	Avoids burning expensive Opus tokens on idle monitoring	— Pending
Path-based sessions	Leverages Claude Code's native session-per-directory behavior, files naturally scoped	— Pending
Extend existing bot	Reuse proven Telegram integration rather than building from scratch	— Pending

---

Last updated: 2026-02-04 after initialization