From fedceab5601ef93725870fdbf9d4b8b3b16afe83 Mon Sep 17 00:00:00 2001 From: Mikkel Georgsen Date: Wed, 4 Feb 2026 18:51:53 +0000 Subject: [PATCH] docs(02): capture phase context Phase 02: Telegram Integration - Implementation decisions documented - Phase boundary established --- .../02-telegram-integration/02-CONTEXT.md | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 .planning/phases/02-telegram-integration/02-CONTEXT.md diff --git a/.planning/phases/02-telegram-integration/02-CONTEXT.md b/.planning/phases/02-telegram-integration/02-CONTEXT.md new file mode 100644 index 0000000..bad91df --- /dev/null +++ b/.planning/phases/02-telegram-integration/02-CONTEXT.md @@ -0,0 +1,72 @@ +# 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*