mikkel/homelab
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
homelab/.planning/REQUIREMENTS.md
Mikkel Georgsen 0edb076981 docs: define v1 requirements 
18 requirements across 5 categories
6 requirements deferred to v2
2026-02-04 13:41:23 +00:00

3.5 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 - Pending
MSG-02 - Pending
MSG-03 - Pending
MSG-04 - Pending
SESS-01 - Pending
SESS-02 - Pending
SESS-03 - Pending
SESS-04 - Pending
LIFE-01 - Pending
LIFE-02 - Pending
LIFE-03 - Pending
LIFE-04 - Pending
OUT-01 - Pending
OUT-02 - Pending
OUT-03 - Pending
INFRA-01 - Pending
INFRA-02 - Pending
INFRA-03 - Pending

Coverage:

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

Requirements defined: 2026-02-04 Last updated: 2026-02-04 after initial definition