Claudeman

A Claude Code session manager with an autonomous Ralph Loop for task assignment and monitoring.

Features

• Web Interface: Beautiful, responsive web UI with interactive terminal powered by xterm.js and modern gradient styling
• Session Management: Spawn and manage multiple Claude CLI sessions as PTY subprocesses with one-click kill
• Interactive Terminal: Full terminal access with resize support, buffer persistence, and 60fps batched rendering
• Respawn Controller: Autonomous state machine that cycles sessions (update docs → /clear → /init) with configurable prompts
• Enable Respawn on Existing Sessions: Start respawn on already-running sessions without restarting
• Timed Respawn: Set duration limits for respawn loops with countdown timer display
• 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
• 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
• Ralph Loop: Autonomous control loop that assigns tasks to idle sessions and monitors completion
• Time-Aware Loops: Extended work sessions with auto-generated follow-up tasks when minimum duration not reached
• Case Management: Create project workspaces with auto-generated CLAUDE.md templates
• Cost Tracking: Track total API costs across all sessions
• State Persistence: All state persisted to ~/.claudeman/state.json
• Long-Running Support: Optimized for 12-24+ hour sessions with automatic buffer trimming
• Resource Monitoring: Real-time memory/message usage display for each session
• Multi-Tab Sessions: Open 1-10 Claude sessions at once for the same project
• Session Restoration: Automatically restore screen sessions when server restarts
• Monitor Panel: Combined view of screen sessions and background tasks

Installation

npm install
npm run build
npm link  # Optional: make 'claudeman' available globally

Quick Start

Web Interface (Recommended)

# Start the web interface
claudeman web

# Open http://localhost:3000 in your browser

The web interface provides:

• Quick Start Button: One-click to create a case and start an interactive Claude session
• Interactive Terminal: Full xterm.js terminal with resize support and 60fps rendering
• Prompt Input: Enter prompts and optionally set a working directory
• Duration Timer: Set duration in minutes for timed runs (0 = single run)
• Live Output: See Claude's response in real-time as it streams
• Countdown: Animated timer display with shimmer progress bar
• Session Monitoring: View all active sessions with status, resource usage, and cost
• Kill All Button: One-click to terminate all running sessions and their child processes
• Resource Display: Real-time memory usage and message count per session
• Respawn Controls: Start/stop respawn controller with configurable settings
• Case Management: Create new project workspaces with CLAUDE.md templates
• Keyboard Shortcuts: Quick access to common actions (Ctrl+Enter, Ctrl+K, Ctrl+L)
• Toast Notifications: Non-intrusive status updates and alerts
• Mobile Support: Responsive design optimized for tablets and phones
• Modern UI: Gradient backgrounds, smooth animations, and polished styling

Quick Start Button

The Quick Start feature reduces the typical 5-step workflow to just 1-2 steps:

Before (5 steps):

1. Go to Cases tab
2. Create a case
3. Click the case
4. Switch to Run tab
5. Click Interactive

After (1-2 steps):

1. (Optional) Select a case from dropdown
2. Click "Quick Start"

The Quick Start button will:

• Create a case folder in ~/claudeman-cases/ if it doesn't exist
• Generate a CLAUDE.md file for the case
• Create a new session pointed to that case directory
• Start an interactive Claude terminal
• Focus the terminal so you can start working immediately

Keyboard Shortcuts

Shortcut	Action
Ctrl+Enter	Run Claude (create case + interactive session)
Ctrl+W	Close current session
Ctrl+Tab	Switch to next session
Ctrl+K	Kill all sessions
Ctrl+L	Clear terminal
Ctrl++/-	Increase/decrease font size
Ctrl+?	Show keyboard shortcuts help
Escape	Close panels and modals

Additional Features

• Multi-Tab Sessions: Number input (1-10) next to "Run Claude" opens multiple sessions at once, named 1-projectname, 2-projectname, etc.
• Monitor Panel: Combined view of Screen Sessions and Background Tasks in one panel
• Session Restoration: Screen sessions are automatically restored when the server restarts
• Terminal Font Controls: Adjust font size with A+/A- buttons in header or Ctrl++/-
• Copy Terminal Output: Copy all terminal content to clipboard
• Session Duration: View how long each session has been running
• Working Directory Display: See the project folder for each session
• Session Count: Header displays total active sessions
• Toast Notifications: Non-intrusive status updates and alerts
• Mobile Support: Responsive design optimized for tablets and phones
• Help Modal: Press ? button or Ctrl+? for keyboard shortcuts reference
• Reconnect Button: Manually reconnect if connection is lost
• Confirmation Dialogs: Warns before starting long timed runs (30+ minutes)

CLI Usage

# Start a Claude session
claudeman start --dir /path/to/project

# Add tasks to the queue
claudeman task add "Fix the bug in auth.ts"
claudeman task add "Add tests for the API" --priority 5

# Start the Ralph loop to process tasks
claudeman ralph start

# Check status
claudeman status

Commands

Web Interface

# Start web interface on default port (3000)
claudeman web

# Use a different port
claudeman web --port 8080

Session Management

# Start a new session
claudeman session start [--dir <path>]
claudeman start [--dir <path>]  # shorthand

# Stop a session
claudeman session stop <session-id>

# List sessions
claudeman session list
claudeman list  # shorthand

# View session output
claudeman session logs <session-id>
claudeman session logs <session-id> --errors  # stderr

Task Management

# Add a task
claudeman task add "<prompt>" [options]
  --dir <path>           Working directory
  --priority <n>         Priority (higher = processed first)
  --completion <phrase>  Custom completion phrase to detect
  --timeout <ms>         Task timeout in milliseconds

# List tasks
claudeman task list
claudeman task list --status pending

# View task details
claudeman task status <task-id>

# Remove a task
claudeman task remove <task-id>

# Clear tasks
claudeman task clear              # completed tasks
claudeman task clear --failed     # failed tasks
claudeman task clear --all        # all tasks

Ralph Loop

# Start the autonomous loop
claudeman ralph start
claudeman ralph start --min-hours 4      # run for at least 4 hours
claudeman ralph start --no-auto-generate # disable auto task generation

# Stop the loop
claudeman ralph stop

# Check loop status
claudeman ralph status

Respawn Controller (Web Interface)

The respawn controller keeps interactive sessions productive by automatically cycling through update prompts:

1. Detects when session goes idle (prompt character visible, no activity)
2. Sends configured update prompt (default: "update all the docs and CLAUDE.md")
3. Optionally sends /clear command to reset context
4. Optionally sends /init to reinitialize
5. Repeats

New Features:

• Enable on Existing Sessions: Start respawn on already-running sessions
• Timed Duration: Set a duration limit (e.g., 30 minutes) after which respawn automatically stops
• Auto-Clear: Automatically send /clear when token count exceeds threshold (default 100k)
• Configurable Steps: Toggle /clear and /init steps independently

Configuration via API:

# Start respawn with custom config
curl -X POST localhost:3000/api/sessions/:id/respawn/start \
  -H "Content-Type: application/json" \
  -d '{"config": {"idleTimeoutMs": 10000, "updatePrompt": "run tests and fix issues"}}'

# Enable respawn on an existing running session with duration
curl -X POST localhost:3000/api/sessions/:id/respawn/enable \
  -H "Content-Type: application/json" \
  -d '{"config": {"updatePrompt": "continue working"}, "durationMinutes": 60}'

# Enable auto-clear at 100k tokens
curl -X POST localhost:3000/api/sessions/:id/auto-clear \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "threshold": 100000}'

# Update config on running respawn
curl -X PUT localhost:3000/api/sessions/:id/respawn/config \
  -H "Content-Type: application/json" \
  -d '{"updatePrompt": "refactor the API layer", "sendClear": true, "sendInit": false}'

State Machine:

WATCHING → SENDING_UPDATE → WAITING_UPDATE → SENDING_CLEAR → WAITING_CLEAR → SENDING_INIT → WAITING_INIT → WATCHING

Respawn Config Options:

Option	Default	Description
idleTimeoutMs	5000	Time to wait after idle before sending update
updatePrompt	"update all docs..."	Prompt to send when idle
interStepDelayMs	1000	Delay between respawn steps
sendClear	true	Send /clear after update prompt
sendInit	true	Send /init after /clear

Utility

# Overall status
claudeman status

# Reset all state (stops sessions, clears tasks)
claudeman reset --force

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Claudeman CLI                        │
├─────────────────────────────────────────────────────────┤
│  Ralph Loop Controller                                  │
│  - Monitors all sessions                                │
│  - Assigns tasks from queue                             │
│  - Detects completion/failure                           │
│  - Self-generates follow-up tasks                       │
├─────────────────────────────────────────────────────────┤
│  Session Manager              │  Task Queue             │
│  - Spawn claude processes     │  - Priority queue       │
│  - Track stdin/stdout/stderr  │  - Task definitions     │
│  - Health monitoring          │  - Dependencies         │
│  - Graceful shutdown          │  - Status tracking      │
├─────────────────────────────────────────────────────────┤
│  State Store (JSON file persistence)                    │
│  - Sessions, tasks, logs                                │
└─────────────────────────────────────────────────────────┘

Completion Detection

The Ralph Loop detects task completion by looking for:

1. Promise tags: <promise>COMPLETE</promise> or custom phrases
2. Common indicators: "Task completed successfully", "All tasks done", "✓ Complete"

When creating tasks, you can specify a custom completion phrase:

claudeman task add "Refactor the auth module" --completion "AUTH_REFACTOR_DONE"

The session output will be scanned for <promise>AUTH_REFACTOR_DONE</promise>.

Time-Aware Loops

For extended autonomous work sessions:

claudeman ralph start --min-hours 8

When the minimum duration hasn't been reached and all tasks are complete, the Ralph Loop will auto-generate follow-up tasks like:

• Review and optimize recently changed code
• Add tests for uncovered code paths
• Update documentation
• Check for security vulnerabilities
• Run linting and fix issues

Long-Running Sessions

Claudeman is optimized for extended autonomous sessions (12-24+ hours):

Buffer Management

To prevent memory issues during long runs, buffers are automatically managed:

• Terminal buffer: Max 5MB, trims to 4MB when exceeded
• Text output: Max 2MB, trims to 1.5MB when exceeded
• Messages: Max 1000, keeps most recent 800 when exceeded

Performance Optimizations

• Server-side batching: Terminal data batched at 60fps (16ms intervals)
• Client-side batching: requestAnimationFrame for smooth rendering
• Aggressive process cleanup: SIGKILL with process group termination

Resource Monitoring

Each session displays real-time resource usage:

• Memory usage (terminal + text buffers)
• Message count
• Color-coded warnings (green/yellow/red based on usage)

Kill Sessions

• Click ✕ on individual session cards to terminate
• Click Kill All button in sessions panel to terminate all at once
• Sessions are forcefully killed with SIGKILL after SIGTERM timeout

State File

All state is persisted to ~/.claudeman/state.json:

{
  "sessions": { ... },
  "tasks": { ... },
  "ralphLoop": {
    "status": "running",
    "startedAt": 1234567890,
    "minDurationMs": 14400000,
    "tasksCompleted": 5,
    "tasksGenerated": 2
  },
  "config": {
    "pollIntervalMs": 1000,
    "defaultTimeoutMs": 300000,
    "maxConcurrentSessions": 5
  }
}

Development

# Run in development mode
npm run dev -- start

# Build
npm run build

# Clean build artifacts
npm run clean

Testing

Unit Tests

npm run test                              # Run all tests once
npm run test:watch                        # Watch mode
npm run test:coverage                     # With coverage report
npx vitest run test/session.test.ts       # Single file
npx vitest run -t "should create session" # By pattern

E2E Testing with agent-browser

The project uses agent-browser for end-to-end testing of the web interface. This tool provides browser automation via accessibility tree snapshots and element references.

Installation

npm install -g agent-browser

Running E2E Tests

1. Start the web server:

npm run dev
# or
claudeman web

2. Kill any existing screen sessions (clean slate):

screen -ls | grep -oP '\d+\.\S+' | xargs -I{} screen -X -S {} quit 2>/dev/null || true

3. Run tests with agent-browser:

# Open the app and take initial snapshot
npx agent-browser open http://localhost:3000
npx agent-browser wait --load networkidle
npx agent-browser snapshot
npx agent-browser screenshot /tmp/claudeman-test-initial.png

# Test font controls
npx agent-browser find text "A-" click
npx agent-browser find text "A+" click

# Test tab count stepper
npx agent-browser find text "+" click    # Increment
npx agent-browser find text "−" click    # Decrement

# Test session creation
npx agent-browser find text "Run Claude" click
npx agent-browser wait 2000
npx agent-browser snapshot

# Test Monitor panel
npx agent-browser find text "Monitor" click
npx agent-browser wait 500
npx agent-browser snapshot

# Cleanup
npx agent-browser close

E2E Test Skill

A skill is available at .claude/skills/e2e-test.md that documents the complete test plan with all test cases and expected results. Run it with Claude Code:

/e2e-test

Key Test Areas

Area	What to Test
Initial Load	Header, tabs, font controls, connection status
Font Controls	A-/A+ buttons positioned left of connection
Tab Count	Stepper with −/number/+ buttons
Session Creation	Tab appears, terminal shows Claude starting
Session Options	Modal with respawn settings
Monitor Panel	Screen sessions and background tasks display

Requirements

• Node.js 18+
• Claude CLI (claude) installed and available in PATH