BitSquare/Codeman
2
0
Fork 0
mirror of https://github.com/Ark0N/Codeman.git synced 2026-10-07 16:09:43 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: improve README formatting and structure for GitHub

Browse Source 
- Add centered logo, badges, and navigation links
- Restructure with Problem/Solution framing
- Condense content while keeping key information
- Improve readability with better section organization
- Add quick start guide at the top

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
arkon
2026-01-21 05:04:21 +01:00
co-authored by Claude Opus 4.5
parent 344b34d9bf
commit d15cda0042
1 changed files with 225 additions and 512 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+225 -512
View File
@@ -1,368 +1,203 @@
# Claudeman <p align="center">
<img src="docs/screenshots/logo.png" alt="Claudeman" width="120" />
</p>
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) <h1 align="center">Claudeman</h1>
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue)](https://www.typescriptlang.org/)
[![Tests](https://img.shields.io/badge/tests-196%20passing-success)](./test)
**Take full control of your Claude Code sessions like never before.** <p align="center">
<strong>The missing control plane for Claude Code.</strong><br>
Run 20 autonomous agents. Track them in real-time. Never lose work again.
</p>
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. <p align="center">
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js Version"></a>
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.5-blue" alt="TypeScript"></a>
<a href="./test"><img src="https://img.shields.io/badge/tests-196%20passing-success" alt="Tests"></a>
</p>
> 🎯 **Perfect for**: Autonomous coding sprints, overnight refactors, parallel development, long-running code reviews, time-boxed AI tasks <p align="center">
<a href="#quick-start">Quick Start</a> •
<a href="#features">Features</a> •
<a href="#ralph-loop">Ralph Loops</a> •
<a href="#api-reference">API</a> •
<a href="./CLAUDE.md">Full Docs</a>
</p>
--- ---
## Table of Contents ## The Problem
- [Highlights](#highlights) You're running Claude Code for a complex refactor. 3 hours in:
- [Quick Start](#quick-start)
- [Screenshots](#screenshots) - 💥 **Session crashes** — your context is gone
- [Features](#features) - 🔄 **Token limit hit** — manual `/clear` interrupts flow
- [Ralph Loop](#ralph-loop) - 😴 **You went to sleep** — Claude finished at 2am and sat idle for 6 hours
- [Respawn Controller](#respawn-controller) - 🤯 **5 parallel sessions** — which one had the auth fix again?
- [Inner Loop Tracking](#inner-loop-tracking)
- [Token Management](#token-management) **Claude Code is powerful. Managing it shouldn't be painful.**
- [Web Interface](#web-interface)
- [CLI Commands](#cli-commands)
- [Screen Manager TUI](#screen-manager-interactive-tui)
- [API Reference](#api-reference)
- [Long-Running Sessions](#long-running-sessions)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
--- ---
## Highlights ## The Solution
| Feature | Description | ```bash
|---------|-------------| npm install && npm run build
| **Up to 20 Parallel Sessions** | Spawn multiple Claude CLI sessions with full terminal access | claudeman web
| **Session Persistence** | GNU Screen sessions survive server restarts - never lose work | # → http://localhost:3000
| **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") | <p align="center">
| **Auto Context Management** | Automatic `/clear` and `/compact` when tokens get high | <img src="docs/screenshots/main-interface.png" alt="Claudeman Interface" width="800" />
| **Memory Management** | 5MB terminal buffers with automatic trimming for long sessions | </p>
| **Real-time Monitoring** | Track tokens, costs, memory, CPU, and background tasks |
| **Inner Loop Tracking** | Detect Ralph loops and todos running inside Claude Code | **Claudeman gives you:**
| **Screen Manager TUI** | Interactive bash tool for managing screen sessions |
| **60fps Rendering** | Smooth terminal streaming with batched updates | ✨ **20 parallel sessions** with independent terminals and state
🔄 **Autonomous respawn** — sessions restart automatically when idle
📊 **Real-time monitoring** — tokens, costs, memory, all at a glance
💾 **GNU Screen persistence** — survives crashes, restarts, network failures
🎯 **Ralph Loop tracking** — detect `<promise>COMPLETE</promise>` and todos automatically
--- ---
## Quick Start ## Quick Start
### Installation ### 1. Install
```bash ```bash
git clone https://github.com/yourusername/claudeman.git git clone https://github.com/yourusername/claudeman.git
cd claudeman cd claudeman
npm install npm install
npm run build npm run build
npm link # Optional: make 'claudeman' globally available npm link # Optional: makes 'claudeman' available globally
``` ```
### Start the Web Interface ### 2. Launch
```bash ```bash
claudeman web claudeman web
# Open http://localhost:3000 # Or for development: npx tsx src/index.ts web
``` ```
### Your First Session ### 3. Create Your First Session
1. Click **"Run Claude"** or press `Ctrl+Enter` 1. Open http://localhost:3000
2. A case folder is created in `~/claudeman-cases/` 2. Press `Ctrl+Enter` or click **"Run Claude"**
3. An interactive Claude terminal opens 3. Start coding — your session is now persistent and monitored
4. Start working!
---
## Screenshots
### Main Interface
![Main Interface](docs/screenshots/main-interface.png)
*The Claudeman web interface with session tabs, terminal, and control panels*
### Session Running
![Session Running](docs/screenshots/session-running.png)
*An active Claude session with real-time terminal output*
--- ---
## Features ## Features
### Session Management ### 🖥️ Multi-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 Spawn up to **20 parallel Claude sessions**, each with:
- Full xterm.js terminal with resize support
- Independent token tracking and cost monitoring
- One-click kill or bulk session management
- Tab-based navigation with keyboard shortcuts
Every Claude session spawned by Claudeman receives special environment variables: ### 💾 Session Persistence
| Variable | Description | **Never lose work again.** Every session runs in GNU Screen:
|----------|-------------|
| `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. ```bash
# Your session survives:
- Server restarts
- Browser crashes
- Network disconnects
- Machine sleep/wake
### Autonomous Operation # Sessions know they're managed:
- **Respawn Controller**: State machine that cycles sessions (update → /clear → /init) CLAUDEMAN_SCREEN=1
- **Ralph Loop**: Assigns tasks to idle sessions and monitors completion CLAUDEMAN_SESSION_ID=abc-123
- **Time-Aware Loops**: Auto-generate follow-up tasks when minimum duration not reached CLAUDEMAN_SCREEN_NAME=claudeman-myproject
- **Completion Detection**: Detect `<promise>PHRASE</promise>` patterns ```
### Context Management ### 🔄 Autonomous Respawn
- **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 The **Respawn Controller** keeps Claude productive while you're away:
- **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 WATCHING → SENDING_UPDATE → WAITING → SENDING_CLEAR → SENDING_INIT → repeat
- **Resource Monitoring**: Memory usage with color-coded warnings ```
Configure it once, let it run for hours:
```bash
curl -X POST localhost:3000/api/sessions/:id/respawn/enable \
-d '{"config": {"updatePrompt": "continue improving the code"}, "durationMinutes": 480}'
```
### 📊 Smart Token Management
| Threshold | Action | Why |
|-----------|--------|-----|
| 110k tokens | Auto `/compact` | Summarize context before limit |
| 140k tokens | Auto `/clear` | Reset to prevent hard-stop |
No more surprise context exhaustion. No more manual intervention.
### 🎯 Ralph Loop Integration
Claudeman **natively tracks Ralph Wiggum loops** running inside Claude:
```
Detected: <promise>REFACTOR_COMPLETE</promise>
Loop: REFACTOR_COMPLETE (4.2h elapsed)
Tasks: 8/12 complete
```
Auto-enables when it detects:
- `<promise>PHRASE</promise>` completion patterns
- TodoWrite usage (`- [ ]`, `- [x]`)
- Iteration patterns (`[5/50]`, `Iteration 5 of 50`)
- `/ralph-loop:ralph-loop` commands
### ⚡ 60fps Terminal Streaming
- Server batches at 16ms intervals
- Client uses `requestAnimationFrame` for smooth rendering
- No polling — real-time SSE for instant updates
--- ---
## Ralph Loop ## Ralph Loop
The **Ralph Loop** is Claudeman's signature feature - an autonomous control loop that keeps Claude working on tasks continuously. The **Ralph Loop** is Claudeman's killer feature — run Claude autonomously for 24+ hours.
### How It Works ### How It Works
1. **Assign task** to idle session 1. **Assign task** → Claude starts working
2. **Monitor output** for completion signals 2. **Monitor output** → Detect completion signals
3. **Detect completion** via `<promise>COMPLETE</promise>` or indicators 3. **Auto-cycle** → Clear context, re-init, continue
4. **Mark complete**, assign next task 4. **Time-aware** → Generate follow-up tasks if minimum duration not reached
5. **Auto-generate tasks** if min-time not reached and queue empty
6. **Repeat** until all done
### Starting a Ralph Loop ### Example: Overnight Code Review
```bash ```bash
# Basic Ralph loop # Queue your tasks
claudeman ralph start claudeman task add "Review all code in src/ for bugs"
claudeman task add "Add missing test coverage"
claudeman task add "Update documentation"
# Run for at least 4 hours # Start the loop (run for at least 8 hours)
claudeman ralph start --min-hours 4 claudeman ralph start --min-hours 8
# Run for 8 hours without auto-generation # Go to sleep. Wake up to:
claudeman ralph start --min-hours 8 --no-auto-generate # - All tasks completed
# - Auto-generated follow-ups (optimizations, security checks)
# - Full git history of changes
``` ```
### Completion Detection ### Completion Detection
The Ralph Loop detects task completion through several patterns:
| Pattern | Example | | Pattern | Example |
|---------|---------| |---------|---------|
| Promise tags | `<promise>COMPLETE</promise>` | | Promise tags | `<promise>COMPLETE</promise>` |
| Custom phrases | `<promise>AUTH_REFACTOR_DONE</promise>` | | Custom phrases | `<promise>AUTH_REFACTOR_DONE</promise>` |
| Common indicators | "Task completed successfully", "All done" | | Common indicators | "All tasks completed", "✓ Done" |
| Checkmarks | "✓ Complete", "✔ Finished" |
**Custom completion phrase:**
```bash
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**
```bash
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**
```bash
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**
```bash
# 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**
```bash
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
```bash
# 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
```bash
# 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:
```bash
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:
```bash
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` |
--- ---
@@ -372,99 +207,60 @@ curl -X POST localhost:3000/api/sessions/:id/auto-clear \
| Shortcut | Action | | Shortcut | Action |
|----------|--------| |----------|--------|
| `Ctrl+Enter` | Create case and start session | | `Ctrl+Enter` | Create case + start session |
| `Ctrl+W` | Close current session | | `Ctrl+W` | Close current session |
| `Ctrl+Tab` | Switch to next session | | `Ctrl+Tab` | Next session |
| `Ctrl+K` | Kill all sessions | | `Ctrl+K` | Kill all sessions |
| `Ctrl+L` | Clear terminal | | `Ctrl+L` | Clear terminal |
| `Ctrl++/-` | Adjust font size | | `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 ### Monitor Panel
Combined view of: Real-time visibility into:
- **Screen Sessions**: All GNU screen sessions with status - **Screen sessions** — status, uptime, mode
- **Background Tasks**: Tree view of Claude's spawned tasks - **Background tasks** — Claude's spawned agents in tree view
- **Resource usage** — memory with color-coded warnings
### UI Features
- 60fps rendering with batching
- Auto-focus for single sessions
- Scroll preservation when expanding panels
- Toast notifications
- Mobile-responsive design
--- ---
## CLI Commands ## CLI Commands
### Sessions
```bash ```bash
claudeman start [--dir <path>] # Start session # Sessions
claudeman list # List sessions claudeman start [--dir <path>] # Start new session
claudeman session stop <id> # Stop session claudeman list # List all sessions
claudeman session logs <id> # View output claudeman session stop <id> # Stop specific session
```
### Tasks # Tasks
claudeman task add "prompt" # Add to queue
claudeman task list # Show queue
claudeman task clear # Clear completed
```bash # Ralph Loop
claudeman task add "<prompt>" [options] claudeman ralph start [--min-hours 8]
--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
```bash
claudeman ralph start [--min-hours 4]
claudeman ralph stop claudeman ralph stop
claudeman ralph status claudeman ralph status
# Server
claudeman web [-p 8080] # Start web interface
claudeman status # Show overall status
``` ```
### Server ### Screen Manager TUI
Interactive terminal UI for direct screen management:
```bash ```bash
claudeman web [-p 8080] ./scripts/screen-manager.sh # Launch interactive mode
claudeman status
claudeman reset --force
``` ```
### Screen Manager (Interactive TUI) | Key | Action |
|-----|--------|
```bash | `↑`/`↓` | Navigate |
./scripts/screen-manager.sh # Interactive mode with arrow navigation | `Enter` | Attach to session |
./scripts/screen-manager.sh list # List all sessions | `d` | Delete session |
./scripts/screen-manager.sh attach 1 # Attach to session #1 | `D` | Delete ALL |
./scripts/screen-manager.sh kill 2,3 # Kill sessions 2 and 3 | `q` | Quit |
./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.
--- ---
@@ -474,95 +270,71 @@ Requires `jq` and `screen` packages.
| Method | Endpoint | Description | | Method | Endpoint | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `GET` | `/api/sessions` | List sessions | | `GET` | `/api/sessions` | List all |
| `POST` | `/api/sessions` | Create session | | `POST` | `/api/sessions` | Create new |
| `GET` | `/api/sessions/:id` | Get details |
| `DELETE` | `/api/sessions/:id` | Delete | | `DELETE` | `/api/sessions/:id` | Delete |
| `POST` | `/api/sessions/:id/input` | Send input | | `POST` | `/api/sessions/:id/input` | Send input |
| `POST` | `/api/sessions/:id/resize` | Resize terminal | | `POST` | `/api/sessions/:id/resize` | Resize terminal |
| `POST` | `/api/sessions/:id/interactive` | Start interactive |
### Respawn ### Respawn Control
| Method | Endpoint | Description | | Method | Endpoint | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `POST` | `/api/sessions/:id/respawn/start` | Start | | `POST` | `/api/sessions/:id/respawn/start` | Start controller |
| `POST` | `/api/sessions/:id/respawn/stop` | Stop | | `POST` | `/api/sessions/:id/respawn/stop` | Stop controller |
| `POST` | `/api/sessions/:id/respawn/enable` | Enable with timer | | `POST` | `/api/sessions/:id/respawn/enable` | Enable with timer |
| `PUT` | `/api/sessions/:id/respawn/config` | Update config | | `PUT` | `/api/sessions/:id/respawn/config` | Update config |
### Inner Loop ### Token Management
| Method | Endpoint | Description | | Method | Endpoint | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `GET` | `/api/sessions/:id/inner-state` | Get state | | `POST` | `/api/sessions/:id/auto-compact` | Set compact threshold |
| `POST` | `/api/sessions/:id/inner-config` | Configure | | `POST` | `/api/sessions/:id/auto-clear` | Set clear threshold |
### Auto Context
| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/sessions/:id/auto-compact` | Configure |
| `POST` | `/api/sessions/:id/auto-clear` | Configure |
### Monitoring ### Monitoring
| Method | Endpoint | Description | | Method | Endpoint | Description |
|--------|----------|-------------| |--------|----------|-------------|
| `GET` | `/api/events` | SSE stream | | `GET` | `/api/events` | SSE stream (real-time) |
| `GET` | `/api/status` | Full state | | `GET` | `/api/status` | Full app state |
| `GET` | `/api/screens` | Screen list | | `GET` | `/api/screens` | Screen sessions |
### Cases
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/cases` | List cases |
| `POST` | `/api/cases` | Create case |
| `POST` | `/api/quick-start` | Quick start |
--- ---
## Long-Running Sessions ## Long-Running Sessions
Optimized for 12-24+ hour autonomous sessions with intelligent memory management. Claudeman is built for **12-24+ hour autonomous runs**.
### 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 ### Memory Management
Claudeman is designed for stability during extended sessions: | Buffer | Max Size | Auto-Trim To |
|--------|----------|--------------|
- **Automatic buffer trimming**: Keeps the most recent data when limits exceeded | Terminal | 5MB | 4MB |
- **Debounced state saves**: 500ms batching prevents disk I/O storms | Text output | 2MB | 1.5MB |
- **Process cleanup**: Aggressive cleanup of orphaned screen sessions | Messages | 1000 | 800 |
- **Event listener tracking**: Prevents memory leaks from unremoved listeners | Respawn buffer | 1MB | 512KB |
- **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 ### Best Practices
1. Enable auto-compact (threshold below auto-clear) 1. **Enable auto-compact** at 110k tokens
2. Use screen sessions for persistence 2. **Enable auto-clear** at 140k tokens
3. Monitor resource usage indicators 3. **Use screen sessions** for persistence
4. Commit frequently in Ralph loops 4. **Commit frequently** in Ralph loops
5. Plan for periodic breaks 5. **Monitor resource indicators** in the UI
---
## Why Claudeman?
| Challenge | Without Claudeman | With Claudeman |
|-----------|-------------------|----------------|
| Session crashes | Lost context, manual restart | GNU Screen auto-recovery |
| Token limits | Surprise hard-stops | Auto-compact/clear at thresholds |
| Overnight runs | Claude sits idle | Respawn controller keeps working |
| 5+ parallel sessions | Tab hell, lost track | Web UI with real-time monitoring |
| Ralph loop tracking | Manual checking | Automatic detection + UI |
| Cost tracking | Surprise bills | Real-time per-session costs |
--- ---
@@ -571,46 +343,25 @@ Claudeman is designed for stability during extended sessions:
### Session Won't Start ### Session Won't Start
```bash ```bash
which claude # Check CLI available which claude # Is Claude CLI installed?
claude --version # Check version claude --version # Check version
screen -ls # Check screen sessions screen -ls # Check for stuck screens
pkill -f "SCREEN.*claudeman" # Kill stuck screens pkill -f "SCREEN.*claudeman" # Kill all claudeman screens
``` ```
### High Memory Usage ### High Memory Usage
```bash ```bash
curl localhost:3000/api/sessions/:id # Check buffer sizes # Lower the auto-clear threshold
# Lower auto-clear threshold
curl -X POST localhost:3000/api/sessions/:id/auto-clear \ curl -X POST localhost:3000/api/sessions/:id/auto-clear \
-d '{"enabled": true, "threshold": 100000}' -d '{"enabled": true, "threshold": 100000}'
``` ```
### Respawn Not Working ### Respawn Not Working
1. Check for `↵ send` idle indicator 1. Check session is idle (look for `↵ send` indicator)
2. Verify respawn enabled via API 2. Verify respawn is enabled via API
3. Check respawn state is `watching` 3. Increase `idleTimeoutMs` if detection is too aggressive
4. Increase `idleTimeoutMs` if needed
### Screen Issues
Use the interactive screen manager for easy session management:
```bash
./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:
```bash
screen -ls | grep claudeman # List screens
screen -X -S claudeman-<id> quit # Kill specific
pkill -f "SCREEN.*claudeman" # Kill all
```
--- ---
@@ -620,53 +371,30 @@ pkill -f "SCREEN.*claudeman" # Kill all
A: 24+ hours. Buffer management keeps memory stable. A: 24+ hours. Buffer management keeps memory stable.
**Q: Does it work with Claude Code hooks?** **Q: Does it work with Claude Code hooks?**
A: Yes! Claudeman spawns real Claude CLI processes. A: Yes! Claudeman spawns real Claude CLI processes with full hook support.
**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?** **Q: What if the server restarts?**
A: Screen sessions persist and auto-restore. A: Screen sessions persist. Claudeman auto-discovers them on startup.
**Q: How does token counting work?**
A: Parses Claude's status line (e.g., "123.4k tokens").
**Q: Custom completion phrases?** **Q: Custom completion phrases?**
A: Yes! Use `--completion` flag or `<promise>PHRASE</promise>`. A: Yes! Use `<promise>YOUR_PHRASE</promise>` in prompts.
**Q: How many parallel sessions?**
A: Up to 20 in the UI, 50 via API.
--- ---
## Development ## Development
### Setup
```bash ```bash
npm install npm install
npx tsx src/index.ts web # Dev mode npx tsx src/index.ts web # Dev mode (no build needed)
npm run build # Production npm run build # Production build
npx tsc --noEmit # Type check npm test # Run 196 tests
npx tsc --noEmit # Type check
``` ```
### Testing See [CLAUDE.md](./CLAUDE.md) for full development documentation.
```bash
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 |
--- ---
@@ -679,30 +407,15 @@ npx vitest run -t "name" # By pattern
5. Commit with conventional commits (`feat:`, `fix:`, `docs:`) 5. Commit with conventional commits (`feat:`, `fix:`, `docs:`)
6. Open Pull Request 6. Open Pull Request
### Code Style
- TypeScript strict mode
- ES2022 target, NodeNext modules
- Pre-compile regex patterns
--- ---
## License ## License
MIT License - see [LICENSE](LICENSE) for details. MIT License — see [LICENSE](LICENSE) for details.
---
## Acknowledgments
- [Claude Code](https://claude.ai/code) by Anthropic
- [xterm.js](https://xtermjs.org/) for terminal rendering
- [Fastify](https://fastify.io/) for the web server
- [node-pty](https://github.com/microsoft/node-pty) for PTY
- [GNU Screen](https://www.gnu.org/software/screen/) for persistence
--- ---
<p align="center"> <p align="center">
Made with care for autonomous AI development <strong>Stop babysitting Claude. Start shipping.</strong><br>
<sub>Built for developers who want Claude Code to work while they sleep.</sub>
</p> </p>