Mikkel Georgsen 6cf6bfb8d1 docs: create roadmap (4 phases)

Phases:
1. Session & Process Foundation: SESS-01, SESS-02, SESS-04, INFRA-02, INFRA-03
2. Telegram Integration: MSG-01, MSG-02, MSG-03, MSG-04, OUT-01, INFRA-01
3. Lifecycle Management: LIFE-01, LIFE-02, LIFE-03, LIFE-04, SESS-03
4. Output Modes: OUT-02, OUT-03

All 18 v1 requirements mapped to phases.

2026-02-04 13:49:57 +00:00

3.7 KiB

Raw Blame History

Requirements: Telegram Claude Code Bridge

Defined: 2026-02-04 Core Value: Frictionless conversation with Claude Code from anywhere via Telegram

v1 Requirements

Core Messaging

MSG-01: Incoming Telegram message auto-triggers Claude Code session and sends response back
MSG-02: Typing indicator shown in Telegram while Claude is processing
MSG-03: Brief tool-call progress notifications sent to Telegram (e.g. "Reading file...")
MSG-04: Files/photos attached in Telegram saved to session folder and available to Claude

Session Management

SESS-01: Path-based sessions stored in ~/telegram/sessions/<name>/ with own Claude Code history
SESS-02: /session <name> command switches active session
SESS-03: /sessions command lists all sessions sorted by last activity
SESS-04: /new <name> creates new session; first-ever message auto-creates default session

Lifecycle

LIFE-01: Configurable idle timeout suspends Claude Code session after inactivity
LIFE-02: Suspended sessions resume with full conversation history via claude --resume
LIFE-03: Graceful process cleanup on bot stop/restart (no zombie processes)
LIFE-04: /timeout <minutes> command changes idle timeout from Telegram

Output Modes

OUT-01: Default mode: final answer + brief tool-call progress notifications
OUT-02: /verbose mode: stream full Claude Code output across multiple messages
OUT-03: /smart mode: smart truncation with long outputs sent as file attachments

Infrastructure

INFRA-01: Runs as systemd user service alongside existing bot
INFRA-02: Async subprocess management via asyncio (no PIPE deadlocks)
INFRA-03: Concurrent stdout/stderr draining prevents buffer overflow

v2 Requirements

Cost Optimization

COST-01: Haiku-based polling loop monitors for new messages, only spawns Opus for conversation
COST-02: Route simple commands (/status, /pbs) to Haiku instead of Opus
COST-03: Token usage tracking and reporting per session

Advanced Features

ADV-01: Session export (conversation history as markdown file)
ADV-02: Session archiving (compress and move inactive sessions)
ADV-03: Proactive notifications (Claude alerts about homelab events)

Out of Scope

Feature	Reason
Multi-user support	Personal use only, single admin
Web UI	Telegram is the interface
Rate limiting / abuse prevention	Trusted single user
Voice messages	High complexity, text is sufficient
Inline bot mode	Adds complexity, no benefit for single user
Real-time character streaming	Telegram API not designed for it, causes rate limit issues

Traceability

Requirement	Phase	Status
MSG-01	Phase 2	Pending
MSG-02	Phase 2	Pending
MSG-03	Phase 2	Pending
MSG-04	Phase 2	Pending
SESS-01	Phase 1	Pending
SESS-02	Phase 1	Pending
SESS-03	Phase 3	Pending
SESS-04	Phase 1	Pending
LIFE-01	Phase 3	Pending
LIFE-02	Phase 3	Pending
LIFE-03	Phase 3	Pending
LIFE-04	Phase 3	Pending
OUT-01	Phase 2	Pending
OUT-02	Phase 4	Pending
OUT-03	Phase 4	Pending
INFRA-01	Phase 2	Pending
INFRA-02	Phase 1	Pending
INFRA-03	Phase 1	Pending

Coverage:

v1 requirements: 18 total
Mapped to phases: 18
Unmapped: 0

Coverage validation: All 18 v1 requirements mapped to exactly one phase. No orphans.

Requirements defined: 2026-02-04 Last updated: 2026-02-04 after roadmap creation

3.7 KiB Raw Blame History