From 294ca4fdf8e1250ac309c932fcd63e85013ebd05 Mon Sep 17 00:00:00 2001 From: arkon Date: Wed, 21 Jan 2026 04:44:19 +0100 Subject: [PATCH] docs: add critical screen session safety warning to CLAUDE.md Prevent Claude instances from accidentally killing their own screen session by adding prominent warning at top of file. Also documents CLAUDEMAN_SCREEN environment variable and safe debugging practices. Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 531588a8..c68dcc7e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +## ⚠️ CRITICAL: Screen Session Safety + +**You may be running inside a Claudeman-managed screen session.** Before killing ANY screen or Claude process: + +1. **Check environment**: `echo $CLAUDEMAN_SCREEN` - if it returns `1`, you're in a managed session +2. **NEVER run** `screen -X quit`, `pkill screen`, or `pkill claude` without first confirming you're not killing yourself +3. **Safe debugging**: Use `screen -ls` to LIST sessions, but don't kill them blindly +4. **If you need to kill screens**: Use the web UI or `./scripts/screen-manager.sh` instead of direct commands + +**Why this matters**: Killing your own screen terminates your session mid-work, losing context and potentially corrupting state. + ## Project Overview Claudeman is a Claude Code session manager with a web interface and autonomous Ralph Loop. It spawns Claude CLI processes via PTY, streams output in real-time via SSE, and supports scheduled/timed runs. @@ -119,6 +130,20 @@ Sessions have a `mode` property (`SessionMode` type): - **`'claude'`**: Runs Claude CLI for AI interactions (default) - **`'shell'`**: Runs a plain bash shell for debugging/testing +### Screen-Aware Sessions + +All Claude sessions spawned by Claudeman receive environment variables indicating they're running in a managed screen: + +| Variable | Value | Purpose | +|----------|-------|---------| +| `CLAUDEMAN_SCREEN` | `1` | Indicates session is managed by Claudeman | +| `CLAUDEMAN_SESSION_ID` | `` | Unique session identifier | +| `CLAUDEMAN_SCREEN_NAME` | `claudeman-` | GNU screen session name | + +This prevents Claude from accidentally killing its own screen session. The default CLAUDE.md template includes guidance about this. + +**Implementation**: Set in `screen-manager.ts:createScreen()` for screen-based sessions and `session.ts:startInteractive()`/`startShell()` for PTY-only sessions. + ## Code Patterns ### Pre-compiled Regex Patterns @@ -328,7 +353,7 @@ Use `createErrorResponse(code, details?)` from `types.ts`: ## Session Lifecycle & Cleanup -- **Limit**: Web server: `MAX_CONCURRENT_SESSIONS = 50` (`server.ts:56`), CLI default: 5 (`types.ts:DEFAULT_CONFIG`) +- **Limit**: Web server: `MAX_CONCURRENT_SESSIONS = 50` (`server.ts:56`), UI tab limit: 20, CLI default: 5 (`types.ts:DEFAULT_CONFIG`) - **Kill** (`killScreen()`): child PIDs → process group → screen quit → SIGKILL - **Ghost discovery**: `reconcileScreens()` finds orphaned screens on startup - **Cleanup** (`cleanupSession()`): stops respawn, clears buffers/timers, kills screen @@ -457,3 +482,16 @@ Extended documentation is available in the `docs/` directory: **Claudeman Implementation**: The `InnerLoopTracker` class (`src/inner-loop-tracker.ts`) detects Ralph patterns in Claude output and tracks loop state, todos, and completion phrases. It auto-enables when Ralph-related patterns are detected. See [`docs/ralph-wiggum-guide.md`](docs/ralph-wiggum-guide.md) for full documentation on best practices, prompt templates, and troubleshooting. + +## Optimization Roadmap + +Future optimizations are documented in `.claude/optimization-todos.md`. Key areas: + +| Priority | Area | Files | +|----------|------|-------| +| High | Buffer management | `session.ts`, `respawn-controller.ts` | +| High | Pre-compiled regex | `session.ts`, `inner-loop-tracker.ts` | +| Medium | Event listener cleanup | `session.ts`, `respawn-controller.ts` | +| Medium | Debounce batching | `state-store.ts`, `session.ts` | + +Run `cat .claude/optimization-todos.md` for the full list with file:line references.