From ed0c18befc46b6ae50c3b52adcb8cf7c022a135e Mon Sep 17 00:00:00 2001 From: Mikkel Georgsen Date: Wed, 4 Feb 2026 13:26:34 +0000 Subject: [PATCH] docs: initialize project MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Telegram Claude Code Bridge — frictionless Claude Code conversation via Telegram with session management, idle timeout, and full tool access. --- .planning/PROJECT.md | 70 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 .planning/PROJECT.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 0000000..fdd36e4 --- /dev/null +++ b/.planning/PROJECT.md @@ -0,0 +1,70 @@ +# 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//`) with own Claude Code history and files +- [ ] Session switching: `/session ` command in Telegram to switch active session +- [ ] Session listing: `/sessions` command showing all sessions sorted by last activity +- [ ] Session creation: `/new ` 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*