# Phase 2: Telegram Integration - Context

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

<domain>
## 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.

</domain>

<decisions>
## 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 <name> 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

</decisions>

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

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

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