Mikkel Georgsen
c2603c395f
- Phase 3: 2/2 plans executed (idle timer + suspend/resume) - Requirements complete: SESS-03, LIFE-01, LIFE-02, LIFE-03, LIFE-04 - ROADMAP, STATE, REQUIREMENTS updated Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
98 lines
3.7 KiB
Markdown
98 lines
3.7 KiB
Markdown
# 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
|
|
- [x] **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
|
|
|
|
- [x] **LIFE-01**: Configurable idle timeout suspends Claude Code session after inactivity
|
|
- [x] **LIFE-02**: Suspended sessions resume with full conversation history via `claude --resume`
|
|
- [x] **LIFE-03**: Graceful process cleanup on bot stop/restart (no zombie processes)
|
|
- [x] **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 | Complete |
|
|
| SESS-04 | Phase 1 | Complete |
|
|
| LIFE-01 | Phase 3 | Complete |
|
|
| LIFE-02 | Phase 3 | Complete |
|
|
| LIFE-03 | Phase 3 | Complete |
|
|
| LIFE-04 | Phase 3 | Complete |
|
|
| 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*
|