Claudeman

A powerful Claude Code session manager with autonomous Ralph Loop for long-running AI tasks

Claudeman transforms Claude Code into an autonomous development powerhouse. Spawn multiple Claude CLI sessions, run them for hours with automatic context management, and let the Ralph Loop keep your AI assistant productive around the clock.

---

Table of Contents

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

---

Highlights

Feature	Description
Web Interface	Beautiful terminal UI with xterm.js, 60fps rendering, multi-tab sessions
Ralph Loop	Autonomous control loop that keeps Claude working continuously
Time-Aware Sessions	Run Claude for specific durations ("work for 8 hours")
Auto Context	Automatic /clear and /compact when tokens get high
Real-time Monitoring	Track tokens, costs, memory, background tasks
Session Persistence	Screen sessions survive server restarts
Inner Loop Tracking	Detect Ralph loops running inside Claude Code

---

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 multiple 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

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-10) in the tab count stepper
2. Click "Run Claude"
3. Sessions named 1-projectname, 2-projectname, etc.

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

---

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.

Buffer Limits

Buffer	Max Size	Trim To
Terminal	5MB	4MB
Text output	2MB	1.5MB
Messages	1000	800
Line buffer	64KB	flush 100ms

Performance

• Server batching at 60fps (16ms)
• Client requestAnimationFrame batching
• Debounced state saves (500ms)
• Aggressive process cleanup

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

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, up to 50 concurrent sessions.

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