mikkel/homelab
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
homelab/.planning/STATE.md
Mikkel Georgsen 76fb57877d docs(02-01): complete persistent subprocess + telegram utils plan 
Tasks completed: 2/2
- Refactor ClaudeSubprocess to persistent process with stream-json I/O
- Create telegram_utils.py with message formatting and typing indicator

SUMMARY: .planning/phases/02-telegram-integration/02-01-SUMMARY.md
2026-02-04 19:19:07 +00:00

3.4 KiB
Raw Blame History

Project State

Project Reference

See: .planning/PROJECT.md (updated 2026-02-04)

Core value: Frictionless conversation with Claude Code from anywhere via Telegram — no SSH, no manual inbox checking, just message and get a response. Current focus: Phase 2 (Telegram Integration)

Current Position

Phase: 2 of 4 (Telegram Integration) Plan: 02-01 complete (1 of 2 plans completed) Status: In progress Last activity: 2026-02-04 — Completed 02-01-PLAN.md (Persistent subprocess + telegram utils)

Progress: [████░░░░░░░░░░░] 33%

Performance Metrics

Velocity:

  • Total plans completed: 4
  • Average duration: 8 min
  • Total execution time: 0.53 hours

By Phase:

Phase Plans Total Avg/Plan
1 3 27min 9min
2 1 5min 5min

Recent Trend:

  • Last 3 plans: 01-02 (9min), 01-03 (15min), 02-01 (5min)
  • Trend: Improved velocity (yolo mode + better planning)

Updated after each plan completion

Accumulated Context

Decisions

Decisions are logged in PROJECT.md Key Decisions table. Recent decisions affecting current work:

  • Claude Code CLI over raw API: Gets full tool access, --resume support, and all Claude Code features for free
  • Haiku polling + Opus conversation: Avoids burning expensive Opus tokens on idle monitoring (deferred to v2)
  • Path-based sessions: Leverages Claude Code's native session-per-directory behavior, files naturally scoped
  • Extend existing bot: Reuse proven Telegram integration rather than building from scratch
  • Sessions created as 'idle', activated explicitly: Creating doesn't mean in use, switch required (01-01)
  • Metadata read from disk on demand: No caching to avoid stale state (01-01)
  • Asyncio.gather for concurrent stream reading: Prevents pipe deadlock (01-02)
  • Fresh process per turn: Spawn new claude -p invocation for Phase 1 simplicity (01-02)
  • Callback architecture: Decouple subprocess from session management via on_output/on_error/on_complete/on_status (01-02)
  • Sibling imports over package imports: Avoids shadowing pip telegram package (01-03)
  • Archive sessions with tar+pigz: Compression + cleanup to sessions_archive/ (01-03)
  • Persistent subprocess instead of fresh per turn: Eliminates ~1s spawn overhead, maintains context (02-01)
  • Split messages at 4000 chars (not 4096): Leaves room for MarkdownV2 escape expansion (02-01)
  • Never split inside code blocks: Track in_code_block state, only split when safe (02-01)

Pending Todos

None yet.

Blockers/Concerns

Phase 1 (Session & Process Foundation) — COMPLETE

  • Claude Code CLI --resume behavior with pipes vs PTY unknown — RESOLVED: Research confirms pipes + stream-json is correct approach
  • Output format for tool calls not documented — RESOLVED: stream-json format documented and implemented

Phase 2 (Telegram Integration) — IN PROGRESS:

  • Non-persistent process model (spawned fresh per turn) — RESOLVED: Refactored to persistent subprocess with stream-json stdin (02-01)
  • Message batching strategy needs validation against actual Claude output patterns
  • File upload flow (save to session dir, notify Claude) needs end-to-end testing

Session Continuity

Last session: 2026-02-04T19:17:24Z Stopped at: Completed 02-01-PLAN.md (Persistent subprocess + telegram utils) Resume file: None Next: 02-02-PLAN.md (Bot integration with batching, file handling, systemd service)