From 7768fd610bec57cec9d5339b826e68af0250899c Mon Sep 17 00:00:00 2001 From: arkon Date: Mon, 19 Jan 2026 13:24:45 +0100 Subject: [PATCH] docs: add inner loop tracking documentation Update CLAUDE.md: - Add inner-loop-tracker.ts to architecture diagram - Add InnerLoopTracker component description - Add Inner Loop Tracking section with patterns and API - Update SSE events list with inner loop events - Update state persistence notes Update README.md: - Add Inner Loop Tracking to features list - Add Inner Loop Tracking section with detection patterns, UI, and API - Update State Files section with state-inner.json Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++--- README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 92 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b3660738..be92987e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -52,6 +52,7 @@ src/ ├── ralph-loop.ts # Autonomous task assignment ├── task-queue.ts # Priority queue with dependencies ├── task-tracker.ts # Background task detection from terminal output +├── inner-loop-tracker.ts # Detect Ralph loops and todos inside Claude sessions ├── state-store.ts # Persistence to ~/.claudeman/state.json ├── types.ts # All TypeScript interfaces ├── web/ @@ -73,7 +74,7 @@ src/ ### Key Components -- **Session** (`src/session.ts`): Wraps Claude CLI as PTY subprocess. Two modes: `runPrompt(prompt)` for one-shot, `startInteractive()` for persistent terminal. Emits events: `output`, `terminal`, `message`, `completion`, `exit`, `idle`, `working`, `autoClear`, `autoCompact`, `clearTerminal`. +- **Session** (`src/session.ts`): Wraps Claude CLI as PTY subprocess. Two modes: `runPrompt(prompt)` for one-shot, `startInteractive()` for persistent terminal. Emits events: `output`, `terminal`, `message`, `completion`, `exit`, `idle`, `working`, `autoClear`, `autoCompact`, `clearTerminal`, `innerLoopUpdate`, `innerTodoUpdate`, `innerCompletionDetected`. - **RespawnController** (`src/respawn-controller.ts`): State machine that keeps sessions productive. Detects idle → sends update prompt → optionally `/clear` → optionally `/init` → optionally kickstart prompt → repeats. State flow: `WATCHING → SENDING_UPDATE → WAITING_UPDATE → SENDING_CLEAR → WAITING_CLEAR → SENDING_INIT → WAITING_INIT → MONITORING_INIT → (optional) SENDING_KICKSTART → WAITING_KICKSTART → WATCHING` @@ -81,6 +82,11 @@ src/ - **WebServer** (`src/web/server.ts`): Fastify server with REST API (`/api/*`) + SSE (`/api/events`). Wires session events to SSE broadcast. +- **InnerLoopTracker** (`src/inner-loop-tracker.ts`): Detects Ralph Wiggum loops and todo lists running inside Claude Code sessions by parsing terminal output. Emits `loopUpdate`, `todoUpdate`, `completionDetected` events. Detection patterns: + - Completion phrases: `PHRASE` + - Todo items: checkbox format (`- [ ]`/`- [x]`), indicator icons (`☐`/`◐`/`✓`), status parentheses + - Loop status: cycle counts, elapsed time, start/completion indicators + ### Session Modes - **One-Shot** (`runPrompt(prompt)`): Single prompt execution, emits completion, exits @@ -149,6 +155,42 @@ Sessions support automatic context management when token thresholds are reached: Both wait for Claude to be idle before executing. Auto-compact runs first if both are enabled. Configured via `session.setAutoCompact(enabled, threshold?, prompt?)` and `session.setAutoClear(enabled, threshold?)`. +### Inner Loop Tracking + +When Claude Code runs inside a claudeman session, it may run its own Ralph Wiggum loops or use the TodoWrite tool. The **InnerLoopTracker** parses terminal output to detect: + +**Completion Phrases:** +``` +COMPLETE +TIME_COMPLETE +CUSTOM_PHRASE +``` + +**Todo Items (multiple formats):** +``` +- [ ] Pending task # Checkbox format +- [x] Completed task +Todo: ☐ Pending task # Indicator format +Todo: ◐ In progress task +Todo: ✓ Completed task +- Task name (in_progress) # Status parentheses +``` + +**Loop Status:** +``` +Loop started at 2024-01-15 +Elapsed: 2.5 hours +cycle #5 +``` + +**API Endpoint:** +```bash +curl localhost:3000/api/sessions/:id/inner-state +# Returns: { loop: InnerLoopState, todos: InnerTodoItem[], todoStats: {...} } +``` + +**UI:** Collapsible panel below session tabs shows loop status and todo progress. Auto-hides when no inner state is detected. + ### Terminal Display Fix (Tab Switch & New Session) When switching tabs or creating new sessions, terminal may be rendered at wrong size. Fix sequence: @@ -163,7 +205,7 @@ Uses `pendingCtrlL` Set to track sessions needing the fix. Waits for `session:id All events broadcast to `/api/events` with format: `{ type: string, sessionId?: string, data: any }`. -Event prefixes: `session:`, `task:`, `respawn:`, `scheduled:`, `case:`, `screen:`, `init`. Key events: `session:idle`, `session:working`, `session:terminal`, `session:clearTerminal`, `session:completion`, `session:autoClear`, `session:autoCompact`. +Event prefixes: `session:`, `task:`, `respawn:`, `scheduled:`, `case:`, `screen:`, `init`. Key events: `session:idle`, `session:working`, `session:terminal`, `session:clearTerminal`, `session:completion`, `session:autoClear`, `session:autoCompact`, `session:innerLoopUpdate`, `session:innerTodoUpdate`, `session:innerCompletionDetected`. ### Frontend (app.js) @@ -248,5 +290,6 @@ Full test plan available at `.claude/skills/e2e-test.md`. ## Notes -- State persists to `~/.claudeman/state.json` and `~/.claudeman/screens.json` +- State persists to `~/.claudeman/state.json`, `~/.claudeman/state-inner.json`, and `~/.claudeman/screens.json` +- Inner loop/todo state persists separately in `state-inner.json` to reduce write frequency - Cases created in `~/claudeman-cases/` by default diff --git a/README.md b/README.md index 4d594e20..54cde81c 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ A Claude Code session manager with an autonomous Ralph Loop for task assignment - **Auto-Clear Context**: Automatically send /clear when token count exceeds threshold (default 100k) - **Token Tracking**: Real-time input/output token tracking per session - **Background Task Tracking**: Detect and display Claude's background tasks in a tree view +- **Inner Loop Tracking**: Detect Ralph Wiggum loops and todo lists running inside Claude Code sessions - **Timed Runs**: Schedule Claude to work for a specific duration with animated live countdown - **Real-time Output**: Stream Claude's responses in real-time via Server-Sent Events (30 event types) - **Task Queue**: Priority-based task queue with dependency support @@ -319,6 +320,44 @@ When the minimum duration hasn't been reached and all tasks are complete, the Ra - Check for security vulnerabilities - Run linting and fix issues +## Inner Loop Tracking + +When Claude Code runs inside a claudeman session, it may run its own Ralph Wiggum loops or use the TodoWrite tool. Claudeman automatically detects and displays this internal state. + +### What's Detected + +- **Completion Phrases**: `COMPLETE`, `TIME_COMPLETE`, etc. +- **Todo Items**: Checkbox format (`- [ ]`/`- [x]`), indicator icons (`☐`/`◐`/`✓`), status parentheses +- **Loop Status**: Cycle counts, elapsed time, loop start/completion + +### UI Display + +A collapsible panel appears below session tabs when inner state is detected: +- **Collapsed**: Shows loop status and task summary (e.g., "🔄 Loop: TIME_COMPLETE (2.3h) | Tasks: 3/5") +- **Expanded**: Shows full todo list with status indicators + +### API + +```bash +# Get inner state for a session +curl localhost:3000/api/sessions/:id/inner-state +``` + +Returns: +```json +{ + "success": true, + "data": { + "loop": { "active": true, "completionPhrase": "COMPLETE", "cycleCount": 5, "elapsedHours": 2.3 }, + "todos": [ + { "id": "todo-abc", "content": "Research existing code", "status": "completed" }, + { "id": "todo-def", "content": "Implement feature", "status": "in_progress" } + ], + "todoStats": { "total": 5, "pending": 2, "inProgress": 1, "completed": 2 } + } +} +``` + ## Long-Running Sessions Claudeman is optimized for extended autonomous sessions (12-24+ hours): @@ -349,9 +388,14 @@ Each session displays real-time resource usage: - Click `Kill All` button in sessions panel to terminate all at once - Sessions are forcefully killed with SIGKILL after SIGTERM timeout -## State File +## State Files -All state is persisted to `~/.claudeman/state.json`: +State is persisted to `~/.claudeman/`: +- `state.json` - Sessions, tasks, config +- `state-inner.json` - Inner loop/todo state (separate file to reduce write frequency) +- `screens.json` - Screen session metadata + +Main state file structure: ```json {