From d291dc0d051d88806909b8ae50567f1f69bca20e Mon Sep 17 00:00:00 2001 From: arkon Date: Thu, 22 Jan 2026 21:36:43 +0100 Subject: [PATCH] docs: sync all documentation with recent state persistence and respawn changes - CLAUDE.md: Add step confirmation behavior, respawnEnabled field, recovery strategy with dual redundancy, updated state lifecycle - README.md: Multi-layer idle detection, step confirmation, state persistence in performance table, updated architecture diagram with State Store - docs/: Updated last-modified dates to 2026-01-22 Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 14 ++++++++++++-- README.md | 9 +++++++-- docs/claude-code-hooks-reference.md | 2 +- docs/ralph-wiggum-guide.md | 2 +- 4 files changed, 21 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f746ac43..d56d40f5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -172,6 +172,8 @@ WATCHING → CONFIRMING_IDLE → SENDING_UPDATE → WAITING_UPDATE → SENDING_C Steps can be skipped via config (`sendClear: false`, `sendInit: false`). Optional `kickstartPrompt` triggers if `/init` doesn't start work. Multi-layer idle detection triggers state transitions. +**Step confirmation**: After sending each step (update, clear, init, kickstart), the controller waits for `completionConfirmMs` (5s) of output silence before proceeding to the next step. This prevents sending commands while Claude is still processing. + ### Session Modes Sessions have a `mode` property (`SessionMode` type): @@ -402,6 +404,7 @@ Writes debounced (500ms) to `~/.claudeman/state.json`. The web server persists f | `autoClearEnabled`, `autoClearThreshold` | Auto-clear settings | | `autoCompactEnabled`, `autoCompactThreshold`, `autoCompactPrompt` | Auto-compact settings | | `ralphEnabled`, `ralphCompletionPhrase` | Ralph / Todo tracker state | +| `respawnEnabled` | Whether respawn controller is currently running | | `respawnConfig` | Full respawn config including `durationMinutes` | | `totalCost`, `inputTokens`, `outputTokens` | Token and cost tracking | @@ -471,6 +474,7 @@ Use `createErrorResponse(code, details?)` from `types.ts`: - **Ghost discovery**: `reconcileScreens()` finds orphaned screens on startup - **Cleanup** (`cleanupSession()`): stops respawn, clears buffers/timers, kills screen, removes from `state.json` - **State sync**: Every session create/delete/update calls `persistSessionState()` which writes full state (including respawn config from controller) to `state.json` +- **Recovery on restart**: Server reads `state.json` first (has all settings), falls back to `screens.json` for any sessions not found. Settings (auto-compact, auto-clear, respawn config, Ralph state) restored to live session objects after screen reattachment. ## TUI Architecture (Ink/React) @@ -604,8 +608,14 @@ Long-running sessions are supported with automatic trimming: - Web server creates → session added to `state.json` + `screens.json` - Settings change → `state.json` updated (debounced 500ms) - Session deleted → removed from `state.json` (screen may survive if `killScreen: false`) -- Server shutdown → all sessions cleaned up from `state.json`, screens preserved for recovery -- Server restart → sessions restored from `screens.json`, state rebuilt in `state.json` +- Server shutdown → sessions preserved in `state.json` (not wiped), screens preserved in `screens.json` +- Server restart → sessions restored from `state.json` (primary) with `screens.json` as fallback + +**Recovery strategy** (double redundancy): +1. **Primary**: `state.json` retains full session state across restarts (settings, tokens, respawn config) +2. **Fallback**: `screens.json` provides screen metadata if `state.json` is missing a session +3. After restoration, all settings (auto-compact, auto-clear, respawn, Ralph) are re-applied to live sessions +4. `persistSessionState()` called after all restorations complete to sync final state Cases created in `~/claudeman-cases/` by default. diff --git a/README.md b/README.md index c67fabdf..990a377f 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,8 @@ CLAUDEMAN_SESSION_ID=abc-123-def CLAUDEMAN_SCREEN_NAME=claudeman-myproject ``` -- Sessions auto-recover on startup +- Sessions auto-recover on startup (dual redundancy: `state.json` + `screens.json`) +- All settings (respawn, auto-compact, tokens) survive server restarts - Ghost session discovery finds orphaned screens - Claude knows it's managed (won't kill its own screen) @@ -58,9 +59,10 @@ WATCHING → IDLE DETECTED → SEND UPDATE → CLEAR → INIT → CONTINUE └──────────────────────────────────────────────────────┘ ``` -- Detects idle state via prompt indicators (`↵ send`, `❯`) +- Multi-layer idle detection (completion messages, output silence, token stability) - Sends configurable update prompts to continue work - Auto-cycles `/clear` → `/init` for fresh context +- Step confirmation (5s silence) between each command - **Keeps working even when Ralph loops stop** - Run for **24+ hours** completely unattended @@ -236,6 +238,7 @@ flowchart TB subgraph Persistence["Persistence Layer"] SCR["GNU Screen Manager"] + SS["State Store
state.json"] end subgraph External["External"] @@ -249,6 +252,7 @@ flowchart TB SM --> S1 SM --> S2 SM --> RC + SM --> SS S1 --> SCR S2 --> SCR RC --> SCR @@ -266,6 +270,7 @@ Optimized for long-running autonomous sessions: | **60fps terminal** | 16ms server batching, `requestAnimationFrame` client | | **Memory management** | Auto-trimming buffers (2MB terminal, 1MB text) | | **Event debouncing** | 50-500ms on rapid state changes | +| **State persistence** | Debounced writes, dual-redundancy recovery | --- diff --git a/docs/claude-code-hooks-reference.md b/docs/claude-code-hooks-reference.md index 3e69282c..cc88abd9 100644 --- a/docs/claude-code-hooks-reference.md +++ b/docs/claude-code-hooks-reference.md @@ -2,7 +2,7 @@ > Official documentation for Claude Code hooks system, extracted from [code.claude.com](https://code.claude.com/docs/en/hooks). -**Last Updated**: 2026-01-20 +**Last Updated**: 2026-01-22 **Source**: [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks) --- diff --git a/docs/ralph-wiggum-guide.md b/docs/ralph-wiggum-guide.md index 0a937470..2845fee8 100644 --- a/docs/ralph-wiggum-guide.md +++ b/docs/ralph-wiggum-guide.md @@ -2,7 +2,7 @@ > This document consolidates official Anthropic documentation, community best practices, and implementation details for autonomous Claude Code loops. -**Last Updated**: 2026-01-20 +**Last Updated**: 2026-01-22 **Sources**: [Official Anthropic Plugin](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum), [Claude Code Docs](https://code.claude.com/docs/en/hooks), [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) ---