Mikkel Georgsen
786468c98b
Phase 01: Session & Process Foundation - Implementation decisions documented - Phase boundary established
72 lines
3.2 KiB
Markdown
72 lines
3.2 KiB
Markdown
# Phase 1: Session & Process Foundation - Context
|
|
|
|
**Gathered:** 2026-02-04
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
Path-based sessions with isolated directories that spawn and manage Claude Code subprocesses. Users create named sessions, switch between them, and each session runs its own Claude Code process. Telegram integration (messaging, typing indicators, file handling) is Phase 2. Idle timeout and suspend/resume lifecycle is Phase 3.
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## Implementation Decisions
|
|
|
|
### Session structure
|
|
- Each session lives at `~/telegram/sessions/<name>/`
|
|
- Session directory contains a `persona.json` defining Claude's personality/behavior for that session
|
|
- Shared persona library at `~/telegram/personas/` with reusable templates (e.g. `brainstorm.json`, `planner.json`, `research.json`)
|
|
- Sessions reference a library persona by name, but can override/customize locally
|
|
- Metadata tracked per session — Claude decides what's useful (name, timestamps, PID, etc.)
|
|
|
|
### Session switching behavior
|
|
- Switching sessions suspends (not kills) the current process — it stays alive
|
|
- The idle timeout from Phase 3 handles graceful cleanup of suspended processes
|
|
- No limit on concurrent live Claude Code processes — idle timeout manages resources
|
|
- Switching to a session with no running process auto-spawns Claude Code immediately
|
|
- Messages queue to the newly active session
|
|
|
|
### Subprocess interaction model
|
|
- I/O model (PTY vs pipes + stream-json): Claude's discretion — research what works best
|
|
- Output buffering vs streaming: Claude's discretion — pick based on CLI capabilities
|
|
- Messages received while Claude is processing are queued, sent after current response completes
|
|
- If Claude Code crashes: auto-restart with --resume and notify user ("Claude restarted, context preserved")
|
|
|
|
### Command design
|
|
- `/new <name> [persona]` — create session, optionally set persona at creation time
|
|
- `/session <name>` — switch to existing session (auto-spawns process if needed)
|
|
- Session names: permissive — anything that works as a directory name (alphanumeric, hyphens, underscores)
|
|
- Name conflict on /new: Claude's discretion on least-surprising behavior
|
|
- No active session + plain message: prompt user with "No active session. Use /new <name> to start one."
|
|
|
|
### Claude's Discretion
|
|
- Session metadata fields beyond basics
|
|
- I/O model choice (PTY vs pipes + stream-json)
|
|
- Output buffering strategy
|
|
- Name conflict handling on /new
|
|
- Persona JSON schema/fields
|
|
|
|
</decisions>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- Personas should feel like "modes" — brainstorming personality is different from planning personality, research personality, casual chat, etc.
|
|
- Persona library is shared templates, but each session can customize — like CSS inheritance
|
|
- The system should feel lightweight — creating a session should be instant
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
- Persona management commands in Telegram (`/persona list`, `/persona show <name>`, `/persona create`) — belongs in a future phase, not Phase 1
|
|
- In-bot persona editing — for now, manage persona files on filesystem
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 01-session-process-foundation*
|
|
*Context gathered: 2026-02-04*
|