Claudeman

Take full control of your Claude Code sessions like never before.

Claudeman is the ultimate session manager for Claude Code power users. Spawn up to 20 parallel Claude CLI sessions, run them autonomously for 24+ hours, and never lose work thanks to persistent GNU Screen sessions. Whether you're running overnight code reviews, parallel feature development, or time-boxed sprints - Claudeman keeps your AI assistant productive while you sleep.

🎯 Perfect for: Autonomous coding sprints, overnight refactors, parallel development, long-running code reviews, time-boxed AI tasks

---

Table of Contents

• Highlights
• Quick Start
• Screenshots
• Features
• Ralph Loop
• Respawn Controller
• Inner Loop Tracking
• Token Management
• Web Interface
• CLI Commands
• Screen Manager TUI
• API Reference
• Long-Running Sessions
• Troubleshooting
• FAQ
• Development
• Contributing
• License

---

Highlights

Feature	Description
Up to 20 Parallel Sessions	Spawn multiple Claude CLI sessions with full terminal access
Session Persistence	GNU Screen sessions survive server restarts - never lose work
Screen-Aware Sessions	Claude sessions know they're in Claudeman via CLAUDEMAN_SCREEN env var
Ralph Loop	Autonomous control loop that keeps Claude working 24+ hours
Time-Aware Sessions	Run Claude for specific durations ("work for 8 hours")
Auto Context Management	Automatic /clear and /compact when tokens get high
Memory Management	5MB terminal buffers with automatic trimming for long sessions
Real-time Monitoring	Track tokens, costs, memory, CPU, and background tasks
Inner Loop Tracking	Detect Ralph loops and todos running inside Claude Code
Screen Manager TUI	Interactive bash tool for managing screen sessions
60fps Rendering	Smooth terminal streaming with batched updates

---

Quick Start

Installation

git clone https://github.com/yourusername/claudeman.git
cd claudeman
npm install
npm run build
npm link  # Optional: make 'claudeman' globally available

Start the Web Interface

claudeman web
# Open http://localhost:3000

Your First Session

1. Click "Run Claude" or press Ctrl+Enter
2. A case folder is created in ~/claudeman-cases/
3. An interactive Claude terminal opens
4. Start working!

---

Screenshots

Main Interface

The Claudeman web interface with session tabs, terminal, and control panels

Session Running

An active Claude session with real-time terminal output

---

Features

Session Management

• Spawn up to 20 parallel Claude CLI sessions as PTY subprocesses
• Full terminal access with resize support and buffer persistence
• One-click kill for individual sessions or all at once
• Session restoration after server restarts via GNU Screen
• Screen-aware sessions: Claude knows it's running in Claudeman via environment variables

Screen-Aware Sessions

Every Claude session spawned by Claudeman receives special environment variables:

Variable	Description
CLAUDEMAN_SCREEN=1	Indicates running within Claudeman
CLAUDEMAN_SESSION_ID	The session's unique identifier
CLAUDEMAN_SCREEN_NAME	The GNU Screen session name

This helps prevent Claude from accidentally terminating its own screen session and allows sessions to be aware of their managed environment.

Autonomous Operation

• Respawn Controller: State machine that cycles sessions (update → /clear → /init)
• Ralph Loop: Assigns tasks to idle sessions and monitors completion
• Time-Aware Loops: Auto-generate follow-up tasks when minimum duration not reached
• Completion Detection: Detect <promise>PHRASE</promise> patterns

Context Management

• Token Tracking: Real-time input/output token counts per session
• Auto-Compact: Send /compact when tokens exceed 110k (configurable)
• Auto-Clear: Send /clear when tokens exceed 140k (configurable)
• Buffer Trimming: Automatic memory management for 12-24+ hour sessions

Monitoring

• Inner Loop Tracking: Detect Ralph loops and todos inside Claude Code
• Background Task Tracking: Tree view of Claude's spawned tasks
• Cost Tracking: Total API costs across all sessions
• Resource Monitoring: Memory usage with color-coded warnings

---

Ralph Loop

The Ralph Loop is Claudeman's signature feature - an autonomous control loop that keeps Claude working on tasks continuously.

How It Works

1. Assign task to idle session
2. Monitor output for completion signals
3. Detect completion via <promise>COMPLETE</promise> or indicators
4. Mark complete, assign next task
5. Auto-generate tasks if min-time not reached and queue empty
6. Repeat until all done

Starting a Ralph Loop

# Basic Ralph loop
claudeman ralph start

# Run for at least 4 hours
claudeman ralph start --min-hours 4

# Run for 8 hours without auto-generation
claudeman ralph start --min-hours 8 --no-auto-generate

Completion Detection

The Ralph Loop detects task completion through several patterns:

Pattern	Example
Promise tags	<promise>COMPLETE</promise>
Custom phrases	<promise>AUTH_REFACTOR_DONE</promise>
Common indicators	"Task completed successfully", "All done"
Checkmarks	"✓ Complete", "✔ Finished"

Custom completion phrase:

claudeman task add "Refactor the auth module" --completion "AUTH_DONE"
# Claude outputs: <promise>AUTH_DONE</promise> when finished

Time-Aware Loops

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

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

Use Cases

Overnight Code Review

claudeman ralph start --min-hours 8
claudeman task add "Review all code in src/ for bugs and improvements"
claudeman task add "Add missing tests for edge cases"
# Let it run overnight

Feature Implementation Sprint

claudeman task add "Implement user authentication with JWT" --completion "AUTH_DONE"
claudeman task add "Add login/logout endpoints" --completion "ENDPOINTS_DONE"
claudeman task add "Write integration tests" --completion "TESTS_DONE"
claudeman ralph start --min-hours 4

Continuous Documentation

# Start a session and enable respawn
claudeman web
# In web UI: Start session, enable respawn with prompt:
# "Update documentation for any changed files, then update CLAUDE.md"

Parallel Development

claudeman web
# Create 3 sessions working on different modules
# Session 1: Frontend components
# Session 2: Backend API
# Session 3: Database migrations

---

Respawn Controller

The Respawn Controller keeps interactive sessions productive by automatically cycling through update prompts.

State Flow

WATCHING → SENDING_UPDATE → WAITING_UPDATE → SENDING_CLEAR → WAITING_CLEAR → SENDING_INIT → WAITING_INIT → MONITORING_INIT → back to WATCHING

Optional: SENDING_KICKSTART → WAITING_KICKSTART if /init doesn't trigger work

States Explained

State	Description
WATCHING	Monitoring session for idle state
SENDING_UPDATE	Sending the update prompt
WAITING_UPDATE	Waiting for Claude to process
SENDING_CLEAR	Sending /clear command
WAITING_CLEAR	Waiting for context to clear
SENDING_INIT	Sending /init command
WAITING_INIT	Waiting for initialization
MONITORING_INIT	Checking if work started

Configuration

# Start respawn with config
curl -X POST localhost:3000/api/sessions/:id/respawn/start \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "idleTimeoutMs": 5000,
      "updatePrompt": "continue working on the current task",
      "sendClear": true,
      "sendInit": true
    }
  }'

# Enable with timed duration (120 minutes)
curl -X POST localhost:3000/api/sessions/:id/respawn/enable \
  -H "Content-Type: application/json" \
  -d '{
    "config": {"updatePrompt": "keep improving the code"},
    "durationMinutes": 120
  }'

Options

Option	Default	Description
idleTimeoutMs	5000	Time to wait after idle before cycling
updatePrompt	"update all docs..."	Prompt sent when session goes idle
sendClear	true	Whether to send /clear after update
sendInit	true	Whether to send /init after clear
kickstartPrompt	null	Optional prompt if /init doesn't trigger work

---

Inner Loop Tracking

Claudeman detects when Claude Code runs its own Ralph Wiggum loops or uses TodoWrite internally.

Detected Patterns

Pattern	Example
Completion phrases	<promise>COMPLETE</promise>
Todo checkboxes	- [ ] Task, - [x] Done
Todo indicators	☐ Pending, ◐ In Progress, ✓ Complete
Iteration patterns	Iteration 5/50, [5/50]
Loop commands	/ralph-loop:ralph-loop
Completion messages	"All tasks completed"

Session-Scoped

Each session has its own independent tracker:

• New session → Fresh tracker
• Close tab → Tracker state cleared
• Switch tabs → Panel shows tracker for active session

UI Display

A collapsible panel shows:

• Collapsed: Summary like "Loop: TIME_COMPLETE (2.3h) | Tasks: 3/5"
• Expanded: Full todo list with progress ring

API

# Get inner state
curl localhost:3000/api/sessions/:id/inner-state

# Reset tracker
curl -X POST localhost:3000/api/sessions/:id/inner-config \
  -H "Content-Type: application/json" \
  -d '{"reset": true}'

---

Token Management

Token Tracking

• Interactive mode: Parses tokens from Claude's status line
• One-shot mode: Uses --output-format stream-json
• Estimation: 60/40 input/output split for interactive

Auto-Compact

Automatically sends /compact when tokens exceed threshold:

curl -X POST localhost:3000/api/sessions/:id/auto-compact \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "threshold": 110000}'

Auto-Clear

Automatically sends /clear when tokens exceed threshold:

curl -X POST localhost:3000/api/sessions/:id/auto-clear \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "threshold": 140000}'

Feature	Default Threshold	Action
Auto-Compact	110k tokens	/compact
Auto-Clear	140k tokens	/clear

---

Web Interface

Keyboard Shortcuts

Shortcut	Action
Ctrl+Enter	Create case and start session
Ctrl+W	Close current session
Ctrl+Tab	Switch to next session
Ctrl+K	Kill all sessions
Ctrl+L	Clear terminal
Ctrl++/-	Adjust font size
Escape	Close panels

Multi-Tab Sessions

1. Set the number (1-20) in the tab count stepper
2. Click "Run Claude"
3. Sessions named w1-projectname, w2-projectname, etc.
4. Tabs wrap nicely into multiple rows for easy navigation

Monitor Panel

Combined view of:

• Screen Sessions: All GNU screen sessions with status
• Background Tasks: Tree view of Claude's spawned tasks

UI Features

• 60fps rendering with batching
• Auto-focus for single sessions
• Scroll preservation when expanding panels
• Toast notifications
• Mobile-responsive design

---

CLI Commands

Sessions

claudeman start [--dir <path>]       # Start session
claudeman list                       # List sessions
claudeman session stop <id>          # Stop session
claudeman session logs <id>          # View output

Tasks

claudeman task add "<prompt>" [options]
  --dir <path>           # Working directory
  --priority <n>         # Priority (higher = first)
  --completion <phrase>  # Completion phrase
  --timeout <ms>         # Timeout

claudeman task list [--status pending]
claudeman task remove <id>
claudeman task clear [--all|--failed]

Ralph Loop

claudeman ralph start [--min-hours 4]
claudeman ralph stop
claudeman ralph status

Server

claudeman web [-p 8080]
claudeman status
claudeman reset --force

Screen Manager (Interactive TUI)

./scripts/screen-manager.sh           # Interactive mode with arrow navigation
./scripts/screen-manager.sh list      # List all sessions
./scripts/screen-manager.sh attach 1  # Attach to session #1
./scripts/screen-manager.sh kill 2,3  # Kill sessions 2 and 3
./scripts/screen-manager.sh kill 1-5  # Kill sessions 1 through 5
./scripts/screen-manager.sh kill-all  # Kill all sessions
./scripts/screen-manager.sh info 1    # Show session #1 details

Interactive Controls:

• ↑/↓ or j/k - Navigate sessions
• Enter - Attach to selected session (Ctrl+A D to detach)
• d - Delete selected session
• D - Delete ALL sessions
• i - Show session info
• q/Esc - Quit

Requires jq and screen packages.

---

API Reference

Sessions

Method	Endpoint	Description
GET	/api/sessions	List sessions
POST	/api/sessions	Create session
GET	/api/sessions/:id	Get details
DELETE	/api/sessions/:id	Delete
POST	/api/sessions/:id/input	Send input
POST	/api/sessions/:id/resize	Resize terminal
POST	/api/sessions/:id/interactive	Start interactive

Respawn

Method	Endpoint	Description
POST	/api/sessions/:id/respawn/start	Start
POST	/api/sessions/:id/respawn/stop	Stop
POST	/api/sessions/:id/respawn/enable	Enable with timer
PUT	/api/sessions/:id/respawn/config	Update config

Inner Loop

Method	Endpoint	Description
GET	/api/sessions/:id/inner-state	Get state
POST	/api/sessions/:id/inner-config	Configure

Auto Context

Method	Endpoint	Description
POST	/api/sessions/:id/auto-compact	Configure
POST	/api/sessions/:id/auto-clear	Configure

Monitoring

Method	Endpoint	Description
GET	/api/events	SSE stream
GET	/api/status	Full state
GET	/api/screens	Screen list

Cases

Method	Endpoint	Description
GET	/api/cases	List cases
POST	/api/cases	Create case
POST	/api/quick-start	Quick start

---

Long-Running Sessions

Optimized for 12-24+ hour autonomous sessions with intelligent memory management.

Buffer Limits

Automatic trimming prevents memory exhaustion during long sessions:

Buffer	Max Size	Trim To	Purpose
Terminal	5MB	4MB	Raw PTY output with ANSI codes
Text output	2MB	1.5MB	ANSI-stripped text for processing
Messages	1000	800	Parsed Claude JSON messages
Line buffer	64KB	flush 100ms	Line-by-line processing buffer
Respawn buffer	1MB	512KB	Terminal data for respawn controller

Memory Management

Claudeman is designed for stability during extended sessions:

• Automatic buffer trimming: Keeps the most recent data when limits exceeded
• Debounced state saves: 500ms batching prevents disk I/O storms
• Process cleanup: Aggressive cleanup of orphaned screen sessions
• Event listener tracking: Prevents memory leaks from unremoved listeners
• Separate state files: Inner loop state in separate file to reduce write frequency

Performance

• Server batching at 60fps (16ms) for smooth terminal streaming
• Client requestAnimationFrame batching for smooth rendering
• Pre-compiled regex patterns (avoid recompilation in hot loops)
• Child process resource monitoring with color-coded warnings

Best Practices

1. Enable auto-compact (threshold below auto-clear)
2. Use screen sessions for persistence
3. Monitor resource usage indicators
4. Commit frequently in Ralph loops
5. Plan for periodic breaks

---

Troubleshooting

Session Won't Start

which claude                     # Check CLI available
claude --version                 # Check version
screen -ls                       # Check screen sessions
pkill -f "SCREEN.*claudeman"     # Kill stuck screens

High Memory Usage

curl localhost:3000/api/sessions/:id  # Check buffer sizes

# Lower auto-clear threshold
curl -X POST localhost:3000/api/sessions/:id/auto-clear \
  -d '{"enabled": true, "threshold": 100000}'

Respawn Not Working

1. Check for ↵ send idle indicator
2. Verify respawn enabled via API
3. Check respawn state is watching
4. Increase idleTimeoutMs if needed

Screen Issues

Use the interactive screen manager for easy session management:

./scripts/screen-manager.sh           # Interactive TUI
./scripts/screen-manager.sh list      # List all sessions
./scripts/screen-manager.sh kill-all  # Kill all sessions

Or use raw commands:

screen -ls | grep claudeman           # List screens
screen -X -S claudeman-<id> quit      # Kill specific
pkill -f "SCREEN.*claudeman"          # Kill all

---

FAQ

Q: How long can sessions run? A: 24+ hours. Buffer management keeps memory stable.

Q: Does it work with Claude Code hooks? A: Yes! Claudeman spawns real Claude CLI processes.

Q: Can I run multiple sessions? A: Yes, the web UI supports up to 20 concurrent sessions per case. The API supports up to 50.

Q: What if the server restarts? A: Screen sessions persist and auto-restore.

Q: How does token counting work? A: Parses Claude's status line (e.g., "123.4k tokens").

Q: Custom completion phrases? A: Yes! Use --completion flag or <promise>PHRASE</promise>.

---

Development

Setup

npm install
npx tsx src/index.ts web    # Dev mode
npm run build               # Production
npx tsc --noEmit            # Type check

Testing

npm run test                # All tests (195)
npm run test:watch          # Watch mode
npm run test:coverage       # Coverage
npx vitest run -t "name"    # By pattern

Test Ports

Port	Test File
3099	quick-start.test.ts
3102	session.test.ts
3105	scheduled-runs.test.ts
3107	sse-events.test.ts
3110	edge-cases.test.ts
3115	integration-flows.test.ts
3120	session-cleanup.test.ts

---

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing)
3. Write tests for new functionality
4. Ensure tests pass (npm test)
5. Commit with conventional commits (feat:, fix:, docs:)
6. Open Pull Request

Code Style

• TypeScript strict mode
• ES2022 target, NodeNext modules
• Pre-compile regex patterns

---

License

MIT License - see LICENSE for details.

---

Acknowledgments

• Claude Code by Anthropic
• xterm.js for terminal rendering
• Fastify for the web server
• node-pty for PTY
• GNU Screen for persistence

---

Made with care for autonomous AI development