Instead of parsing terminal output for <spawn1337> tags, spawn capabilities
are now exposed as native MCP tools that Claude Code can call directly.
The MCP server (stdio transport) proxies requests to the existing REST API.
- Add src/mcp-server.ts with 6 tools: spawn_agent, list_agents,
get_agent_status, get_agent_result, send_agent_message, cancel_agent
- Remove src/spawn-detector.ts and all references in session.ts/server.ts
- Add CLAUDEMAN_API_URL env var propagation to sessions and screens
- Write .mcp.json to case directories during creation
- Remove spawn1337 tag documentation from case-template.md
- Add claudeman-mcp bin entry to package.json
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Rename inner-loop-tracker.ts → ralph-tracker.ts throughout codebase
- Add ralph-config.ts for parsing .claude/ralph-loop.local.md config
- Standardize API error responses using createErrorResponse()
- Add input validation for auto-compact/auto-clear thresholds
- Update UI labels to "Ralph / Todo Tracker" consistently
- Add 46 integration tests for Ralph tracking functionality
- Update test badge to 438 total tests
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add PersistedRespawnConfig type and respawnConfig field to ScreenSession
- Add innerLoopEnabled field to ScreenSession for Ralph Wiggum tracking
- Add updateRespawnConfig, clearRespawnConfig, updateInnerLoopEnabled methods to ScreenManager
- Save respawn config when enabled/updated via API endpoints
- Save inner loop enabled state when changed via API
- Restore respawn controllers and inner loop state on server startup
This ensures respawn continues working after claudeman restarts.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add isError() type guard to check if value is Error instance
- Add getErrorMessage() utility for safe error message extraction
in catch blocks (handles TypeScript 4.4+ unknown error type)
- Replace all (err as Error).message patterns with getErrorMessage(err)
across server.ts, cli.ts, ralph-loop.ts, and screen-manager.ts
- Follows TypeScript best practice of treating caught errors as unknown
This improves code safety by properly handling the case where caught
values may not be Error instances (e.g., thrown strings or objects).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
TUI now checks if web server is running on startup and offers to start
it in the background. Added new CLI options: --with-web (auto-start),
--no-web (skip check), -p (port).
TUI feature parity with web interface:
- Shell mode: press 'h' in cases view to start bash instead of Claude
- Multi-start: press 'm' to start 1-20 sessions at once
- Respawn toggle: Ctrl+R to enable/disable respawn on Claude sessions
- Session rename: API support via useSessionManager hook
Security fixes from previous analysis:
- Command injection prevention in screen-manager.ts
- Path traversal protection in server.ts
- Input validation for shell-interpolated values
Also fixes memory leak in session.ts (timer tracking) and flaky test
timeout in session-cleanup.test.ts.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Claude sessions spawned by Claudeman now receive environment variables:
- CLAUDEMAN_SCREEN=1 - Indicates running within Claudeman
- CLAUDEMAN_SESSION_ID - The session's unique identifier
- CLAUDEMAN_SCREEN_NAME - The GNU Screen session name (when applicable)
This helps prevent Claude from attempting to kill its own screen session
and allows sessions to be aware of their managed environment.
Also updated the default CLAUDE.md template to document this behavior.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add comprehensive module-level documentation
- Document main classes with usage examples
- Add parameter and return type documentation to key methods
- Document constants and buffer limits
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Claude CLI (Ink) doesn't process carriage return correctly when sent
together with text via screen -X stuff. Splitting into two separate
commands works reliably:
1. screen -X stuff "text"
2. screen -X stuff "$(printf '\015')"
Also adds writeViaScreen() method to Session for programmatic input
that bypasses PTY and uses screen -X stuff directly.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The bash $'...' escaping wasn't reliably sending carriage return to
Ink/Claude CLI. Using printf with octal '\015' works correctly.
Tested: screen -X stuff "$(printf 'text\015')" successfully triggers
Enter key submission in Claude CLI.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When writing to an attached PTY connected to screen, the input doesn't
reliably reach Claude CLI. This fix uses `screen -X stuff` command to
send input directly to the screen session, bypassing the PTY attachment.
Research findings:
- Claude CLI uses Ink (React for CLI) for terminal UI
- Ink's parseKeypress detects \r as key.return (Enter)
- screen -X stuff with $'...' syntax reliably sends literal characters
Changes:
- Add ScreenManager.sendInput() using screen -X stuff
- Modify Session.write() to prefer screen -X stuff when available
- Keep \r as Enter key (what Ink expects for key.return)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Pre-compile ANSI escape and whitespace regex patterns in respawn controller
- Pre-compile screen pattern regex for screen list parsing
- Batch ps and pgrep calls in getScreensWithStats() for multiple screens
- Reduces subprocess spawns from O(2n) to O(2) for n screens
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- killScreen now uses 4 strategies for reliable cleanup:
1. Kill all child processes recursively (SIGTERM then SIGKILL)
2. Kill entire process group (-PID) to catch orphans
3. Kill screen by name (screen -X quit)
4. Direct SIGKILL as final fallback
- Refresh screen PID from screen -ls before killing (handles stale PIDs)
- reconcileScreens now discovers unknown claudeman screens from screen -ls
This prevents "ghost" screens that persist after screens.json is lost
- restoreScreenSessions handles newly discovered screens
The rapid session creation test now fails because discovery is working -
it finds screens that weren't killed fast enough (test timing issue)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- killScreen now finds and kills all child processes before quitting screen
to prevent claude processes from becoming orphaned (the main bug)
- Add cleanupSession() method for comprehensive resource cleanup:
respawn controllers, timers, batches, event listeners, and sessions
- Fix /api/run endpoint to cleanup sessions after completion
- Fix /api/quick-start error path to cleanup on failure
- Add MAX_CONCURRENT_SESSIONS (50) limit to prevent unbounded growth
- Update CLAUDE.md with improved documentation
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
GNU screen creates blank space at the top when initializing sessions.
This is now handled after attaching to the screen:
- Claude sessions: emit clearTerminal event after 100ms, client clears xterm
- Shell sessions: send 'clear' command after 100ms
Also updates CLAUDE.md with documentation of the fix.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Monitor panel now opens by default on webapp start
- Replace "Reconcile" button with refresh icon (↻)
- Change close button to toggle (▼/▲) for collapse/expand
- Preserve session display names when saving screen info
- Use stored name when restoring sessions (no more "Restored:" prefix)
- Show session name in Monitor panel instead of screen name
- Kill screen session when closing a tab
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add screen session management infrastructure:
- ScreenManager class to create, track, and kill GNU screen sessions
- Persistence of screen sessions to ~/.claudeman/screens.json
- Process stats collection (memory, CPU, child count)
- Reconciliation to detect dead/orphan screens
New API endpoints:
- GET /api/screens - list screens with stats
- DELETE /api/screens/:sessionId - kill screen
- POST /api/screens/reconcile - find dead screens
- POST /api/screens/stats/start|stop - control stats polling
New Process Monitor panel:
- Slide-up panel with real-time stats (2s updates)
- Shows memory, CPU, child processes per screen
- Kill button for each screen session
- Reconcile button to clean up dead screens
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
