# Requirements: Telegram Claude Code Bridge

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

## v1 Requirements

### Core Messaging

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

### Session Management

- [x] **SESS-01**: Path-based sessions stored in `~/telegram/sessions/<name>/` with own Claude Code history
- [x] **SESS-02**: `/session <name>` command switches active session
- [ ] **SESS-03**: `/sessions` command lists all sessions sorted by last activity
- [x] **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

- [x] **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

- [x] **INFRA-01**: Runs as systemd user service alongside existing bot
- [x] **INFRA-02**: Async subprocess management via asyncio (no PIPE deadlocks)
- [x] **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 | Complete |
| MSG-02 | Phase 2 | Complete |
| MSG-03 | Phase 2 | Complete |
| MSG-04 | Phase 2 | Complete |
| SESS-01 | Phase 1 | Complete |
| SESS-02 | Phase 1 | Complete |
| SESS-03 | Phase 3 | Pending |
| SESS-04 | Phase 1 | Complete |
| LIFE-01 | Phase 3 | Pending |
| LIFE-02 | Phase 3 | Pending |
| LIFE-03 | Phase 3 | Pending |
| LIFE-04 | Phase 3 | Pending |
| OUT-01 | Phase 2 | Complete |
| OUT-02 | Phase 4 | Pending |
| OUT-03 | Phase 4 | Pending |
| INFRA-01 | Phase 2 | Complete |
| INFRA-02 | Phase 1 | Complete |
| INFRA-03 | Phase 1 | Complete |

**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*