# 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*
