homelab/.planning/ROADMAP.md

Roadmap: Telegram Claude Code Bridge

Overview

This project transforms Telegram into a mobile interface for Claude Code, enabling frictionless AI assistance from anywhere. The journey starts with session and subprocess foundations, integrates Telegram messaging with file handling, adds idle timeout management to conserve resources, and finishes with advanced output modes for power users.

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 1: Session & Process Foundation - Multi-session filesystem structure with subprocess management
• Phase 2: Telegram Integration - Core messaging loop with file handling and typing indicators
• Phase 3: Lifecycle Management - Idle timeout, suspend/resume, and graceful cleanup
• Phase 4: Output Modes - Advanced output control for verbose and smart modes

Phase Details

Phase 1: Session & Process Foundation

Goal: Path-based sessions with isolated directories spawn and manage Claude Code subprocesses safely Depends on: Nothing (first phase) Requirements: SESS-01, SESS-02, SESS-04, INFRA-02, INFRA-03 Success Criteria (what must be TRUE):

1. User can create named sessions via /new <name> command
2. User can switch between sessions with /session <name> command
3. Each session has isolated directory at ~/telegram/sessions/<name>/ with metadata and conversation log
4. Claude Code subprocess spawns in session directory and processes input without pipe deadlock
5. Subprocess terminates cleanly on session switch with no zombie processes Plans: 3 plans

Plans:

• 01-01-PLAN.md -- Session manager module and persona library
• 01-02-PLAN.md -- Claude Code subprocess engine
• 01-03-PLAN.md -- Bot command integration (/new, /session, message routing)

Phase 2: Telegram Integration

Goal: Messages flow bidirectionally between Telegram and Claude with file support and status feedback Depends on: Phase 1 Requirements: MSG-01, MSG-02, MSG-03, MSG-04, OUT-01, INFRA-01 Success Criteria (what must be TRUE):

1. User sends message in Telegram and receives Claude's response back
2. Typing indicator appears in Telegram while Claude is processing (10-60s responses)
3. User sees brief progress notifications for tool calls (e.g. "Reading file...")
4. User attaches file/photo in Telegram and Claude can access it in session folder
5. Long responses split at 4096 char Telegram limit with proper code block handling
6. Bot runs as systemd user service and survives container restarts Plans: 2 plans

Plans:

• 02-01-PLAN.md -- Persistent subprocess engine + message formatting utilities
• 02-02-PLAN.md -- Bot integration with batching, file handling, and systemd service

Phase 3: Lifecycle Management

Goal: Sessions suspend automatically after idle period and resume transparently with full context Depends on: Phase 2 Requirements: LIFE-01, LIFE-02, LIFE-03, LIFE-04, SESS-03 Success Criteria (what must be TRUE):

1. Session suspends automatically after configurable idle timeout (default 10 minutes)
2. User sends message to suspended session and conversation resumes with full history
3. User can change idle timeout via /timeout <minutes> command
4. User can list all sessions with last activity timestamp via /sessions command
5. Bot restart leaves no zombie processes (systemd KillMode handles cleanup) Plans: TBD

Plans:

• TBD

Phase 4: Output Modes

Goal: Users control response verbosity and format based on context Depends on: Phase 3 Requirements: OUT-02, OUT-03 Success Criteria (what must be TRUE):

1. User enables /verbose mode and sees full Claude Code output streamed across multiple messages
2. User enables /smart mode and long outputs are sent as file attachments instead of truncation
3. Default mode (already from Phase 2) shows final answer with brief progress notifications Plans: TBD

Plans:

• TBD

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → 3 → 4

Phase	Plans Complete	Status	Completed
1. Session & Process Foundation	3/3	Complete	2026-02-04
2. Telegram Integration	2/2	Complete	2026-02-04
3. Lifecycle Management	0/TBD	Not started	-
4. Output Modes	0/TBD	Not started	-