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

- [x] **Phase 1: Session & Process Foundation** - Multi-session filesystem structure with subprocess management
- [x] **Phase 2: Telegram Integration** - Core messaging loop with file handling and typing indicators
- [x] **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:
- [x] 01-01-PLAN.md -- Session manager module and persona library
- [x] 01-02-PLAN.md -- Claude Code subprocess engine
- [x] 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:
- [x] 02-01-PLAN.md -- Persistent subprocess engine + message formatting utilities
- [x] 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:** 2 plans

Plans:
- [x] 03-01-PLAN.md -- Idle timer module + session metadata extensions + PID tracking
- [x] 03-02-PLAN.md -- Suspend/resume wiring, /timeout, /sessions, startup cleanup, graceful shutdown

### 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 | 2/2 | Complete | 2026-02-04 |
| 4. Output Modes | 0/TBD | Not started | - |