homelab/.planning/phases/02-telegram-integration/02-CONTEXT.md

Phase 2: Telegram Integration - Context

Gathered: 2026-02-04 Status: Ready for planning

## Phase Boundary

Bidirectional messaging between Telegram and Claude Code with file support and status feedback. User sends messages/files in Telegram, Claude processes via persistent JSON-streamed subprocess, and responds with natural language summaries. Typing indicators and tool call notifications provide progress visibility.

Lifecycle management (idle timeout, suspend/resume) is Phase 3. Output mode switching (verbose/smart) is Phase 4.

## Implementation Decisions

Conversation persistence

• Use JSON streaming to Claude Code so conversations don't cold start for every message
• Maintain persistent process per session rather than spawning fresh claude -p each turn
• This is a key architectural shift from Phase 1's fresh-process-per-turn model

Response formatting

• Use Telegram's native MarkdownV2 for formatting (bold, italic, code, links)
• Claude should communicate in natural language about what it did — no raw code in responses
• Telegram is a mobile-first, on-the-go interface — responses should be concise summaries of work done, not code dumps
• Long responses split at smart boundaries (paragraph/code block breaks) — never break mid-code-block or mid-sentence

Progress feedback

• Tool call notifications include tool name + target (e.g., "Reading config.json...", "Running npm test...")
• No timeout as long as there is progress — Claude Code tasks can legitimately take a while

Claude's Discretion

• Whether to show typing indicator only vs typing + status messages while working
• Whether to send periodic progress updates on long tasks (2+ min) or just wait for completion
• Whether tool call notifications edit a single message in-place or appear as separate messages
• Whether multi-part responses come as one consolidated message or multiple messages
• Error message verbosity and format

File handling

• Photos: save to session folder AND auto-analyze (describe what's in the image immediately)
• Documents/files: save directly to the session's working directory so Claude can reference them
• Claude can send files back to user as Telegram attachments when appropriate (scripts, logs, configs)
• Files sent without message text: infer intent from conversation context rather than asking

Error & edge cases

• No active session + message: prompt user to create one ("No active session. Use /new to start one")
• Rapid sequential messages: batch into a single prompt before sending to Claude
• No hard timeout — as long as progress is happening, let Claude work

## Specific Ideas

• "Telegram is used from a phone when I'm on the move — Claude should focus on doing the work and notifying me how it was solved and what was solved, without showing me code — use natural language"
• JSON streaming to avoid cold starts was explicitly called out as essential
• Batching rapid messages avoids wasting turns on partial thoughts

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 02-telegram-integration Context gathered: 2026-02-04