mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-09-30 12:39:42 +02:00
docs: improve README formatting and structure for GitHub
- 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
@@ -1,368 +1,203 @@
|
||||
# Claudeman
|
||||
<p align="center">
|
||||
<img src="docs/screenshots/logo.png" alt="Claudeman" width="120" />
|
||||
</p>
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://nodejs.org/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](./test)
|
||||
<h1 align="center">Claudeman</h1>
|
||||
|
||||
**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)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Screenshots](#screenshots)
|
||||
- [Features](#features)
|
||||
- [Ralph Loop](#ralph-loop)
|
||||
- [Respawn Controller](#respawn-controller)
|
||||
- [Inner Loop Tracking](#inner-loop-tracking)
|
||||
- [Token Management](#token-management)
|
||||
- [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)
|
||||
You're running Claude Code for a complex refactor. 3 hours in:
|
||||
|
||||
- 💥 **Session crashes** — your context is gone
|
||||
- 🔄 **Token limit hit** — manual `/clear` interrupts flow
|
||||
- 😴 **You went to sleep** — Claude finished at 2am and sat idle for 6 hours
|
||||
- 🤯 **5 parallel sessions** — which one had the auth fix again?
|
||||
|
||||
**Claude Code is powerful. Managing it shouldn't be painful.**
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
## The Solution
|
||||
|
||||
| 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 |
|
||||
```bash
|
||||
npm install && npm run build
|
||||
claudeman web
|
||||
# → http://localhost:3000
|
||||
```
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/screenshots/main-interface.png" alt="Claudeman Interface" width="800" />
|
||||
</p>
|
||||
|
||||
**Claudeman gives you:**
|
||||
|
||||
✨ **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
|
||||
|
||||
### Installation
|
||||
### 1. Install
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/claudeman.git
|
||||
cd claudeman
|
||||
npm install
|
||||
npm run build
|
||||
npm link # Optional: make 'claudeman' globally available
|
||||
npm link # Optional: makes 'claudeman' available globally
|
||||
```
|
||||
|
||||
### Start the Web Interface
|
||||
### 2. Launch
|
||||
|
||||
```bash
|
||||
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`
|
||||
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*
|
||||
1. Open http://localhost:3000
|
||||
2. Press `Ctrl+Enter` or click **"Run Claude"**
|
||||
3. Start coding — your session is now persistent and monitored
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
### 🖥️ Multi-Session Management
|
||||
|
||||
### 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 |
|
||||
|----------|-------------|
|
||||
| `CLAUDEMAN_SCREEN=1` | Indicates running within Claudeman |
|
||||
| `CLAUDEMAN_SESSION_ID` | The session's unique identifier |
|
||||
| `CLAUDEMAN_SCREEN_NAME` | The GNU Screen session name |
|
||||
**Never lose work again.** Every session runs in GNU Screen:
|
||||
|
||||
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
|
||||
- **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
|
||||
# Sessions know they're managed:
|
||||
CLAUDEMAN_SCREEN=1
|
||||
CLAUDEMAN_SESSION_ID=abc-123
|
||||
CLAUDEMAN_SCREEN_NAME=claudeman-myproject
|
||||
```
|
||||
|
||||
### 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
|
||||
### 🔄 Autonomous Respawn
|
||||
|
||||
### 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
|
||||
The **Respawn Controller** keeps Claude productive while you're away:
|
||||
|
||||
```
|
||||
WATCHING → SENDING_UPDATE → WAITING → SENDING_CLEAR → SENDING_INIT → repeat
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
1. **Assign task** → Claude starts working
|
||||
2. **Monitor output** → Detect completion signals
|
||||
3. **Auto-cycle** → Clear context, re-init, continue
|
||||
4. **Time-aware** → Generate follow-up tasks if minimum duration not reached
|
||||
|
||||
### Starting a Ralph Loop
|
||||
### Example: Overnight Code Review
|
||||
|
||||
```bash
|
||||
# Basic Ralph loop
|
||||
claudeman ralph start
|
||||
# Queue your tasks
|
||||
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
|
||||
claudeman ralph start --min-hours 4
|
||||
# Start the loop (run for at least 8 hours)
|
||||
claudeman ralph start --min-hours 8
|
||||
|
||||
# Run for 8 hours without auto-generation
|
||||
claudeman ralph start --min-hours 8 --no-auto-generate
|
||||
# Go to sleep. Wake up to:
|
||||
# - All tasks completed
|
||||
# - Auto-generated follow-ups (optimizations, security checks)
|
||||
# - Full git history of changes
|
||||
```
|
||||
|
||||
### 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:**
|
||||
|
||||
```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` |
|
||||
| Common indicators | "All tasks completed", "✓ Done" |
|
||||
|
||||
---
|
||||
|
||||
@@ -372,99 +207,60 @@ curl -X POST localhost:3000/api/sessions/:id/auto-clear \
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Ctrl+Enter` | Create case and start session |
|
||||
| `Ctrl+Enter` | Create case + start session |
|
||||
| `Ctrl+W` | Close current session |
|
||||
| `Ctrl+Tab` | Switch to next session |
|
||||
| `Ctrl+Tab` | 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
|
||||
Real-time visibility into:
|
||||
- **Screen sessions** — status, uptime, mode
|
||||
- **Background tasks** — Claude's spawned agents in tree view
|
||||
- **Resource usage** — memory with color-coded warnings
|
||||
|
||||
---
|
||||
|
||||
## CLI Commands
|
||||
|
||||
### Sessions
|
||||
|
||||
```bash
|
||||
claudeman start [--dir <path>] # Start session
|
||||
claudeman list # List sessions
|
||||
claudeman session stop <id> # Stop session
|
||||
claudeman session logs <id> # View output
|
||||
```
|
||||
# Sessions
|
||||
claudeman start [--dir <path>] # Start new session
|
||||
claudeman list # List all sessions
|
||||
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
|
||||
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
|
||||
|
||||
```bash
|
||||
claudeman ralph start [--min-hours 4]
|
||||
# Ralph Loop
|
||||
claudeman ralph start [--min-hours 8]
|
||||
claudeman ralph stop
|
||||
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
|
||||
claudeman web [-p 8080]
|
||||
claudeman status
|
||||
claudeman reset --force
|
||||
./scripts/screen-manager.sh # Launch interactive mode
|
||||
```
|
||||
|
||||
### Screen Manager (Interactive TUI)
|
||||
|
||||
```bash
|
||||
./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.
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `↑`/`↓` | Navigate |
|
||||
| `Enter` | Attach to session |
|
||||
| `d` | Delete session |
|
||||
| `D` | Delete ALL |
|
||||
| `q` | Quit |
|
||||
|
||||
---
|
||||
|
||||
@@ -474,95 +270,71 @@ Requires `jq` and `screen` packages.
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `GET` | `/api/sessions` | List sessions |
|
||||
| `POST` | `/api/sessions` | Create session |
|
||||
| `GET` | `/api/sessions/:id` | Get details |
|
||||
| `GET` | `/api/sessions` | List all |
|
||||
| `POST` | `/api/sessions` | Create new |
|
||||
| `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
|
||||
### Respawn Control
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| `POST` | `/api/sessions/:id/respawn/start` | Start |
|
||||
| `POST` | `/api/sessions/:id/respawn/stop` | Stop |
|
||||
| `POST` | `/api/sessions/:id/respawn/start` | Start controller |
|
||||
| `POST` | `/api/sessions/:id/respawn/stop` | Stop controller |
|
||||
| `POST` | `/api/sessions/:id/respawn/enable` | Enable with timer |
|
||||
| `PUT` | `/api/sessions/:id/respawn/config` | Update config |
|
||||
|
||||
### Inner Loop
|
||||
### Token Management
|
||||
|
||||
| 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 |
|
||||
| `POST` | `/api/sessions/:id/auto-compact` | Set compact threshold |
|
||||
| `POST` | `/api/sessions/:id/auto-clear` | Set clear threshold |
|
||||
|
||||
### 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 |
|
||||
| `GET` | `/api/events` | SSE stream (real-time) |
|
||||
| `GET` | `/api/status` | Full app state |
|
||||
| `GET` | `/api/screens` | Screen sessions |
|
||||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
Claudeman is built for **12-24+ hour autonomous runs**.
|
||||
|
||||
### 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
|
||||
| Buffer | Max Size | Auto-Trim To |
|
||||
|--------|----------|--------------|
|
||||
| Terminal | 5MB | 4MB |
|
||||
| Text output | 2MB | 1.5MB |
|
||||
| Messages | 1000 | 800 |
|
||||
| Respawn buffer | 1MB | 512KB |
|
||||
|
||||
### 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
|
||||
1. **Enable auto-compact** at 110k tokens
|
||||
2. **Enable auto-clear** at 140k tokens
|
||||
3. **Use screen sessions** for persistence
|
||||
4. **Commit frequently** in Ralph loops
|
||||
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
|
||||
|
||||
```bash
|
||||
which claude # Check CLI available
|
||||
claude --version # Check version
|
||||
screen -ls # Check screen sessions
|
||||
pkill -f "SCREEN.*claudeman" # Kill stuck screens
|
||||
which claude # Is Claude CLI installed?
|
||||
claude --version # Check version
|
||||
screen -ls # Check for stuck screens
|
||||
pkill -f "SCREEN.*claudeman" # Kill all claudeman screens
|
||||
```
|
||||
|
||||
### High Memory Usage
|
||||
|
||||
```bash
|
||||
curl localhost:3000/api/sessions/:id # Check buffer sizes
|
||||
|
||||
# Lower auto-clear threshold
|
||||
# Lower the 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:
|
||||
|
||||
```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
|
||||
```
|
||||
1. Check session is idle (look for `↵ send` indicator)
|
||||
2. Verify respawn is enabled via API
|
||||
3. Increase `idleTimeoutMs` if detection is too aggressive
|
||||
|
||||
---
|
||||
|
||||
@@ -620,53 +371,30 @@ pkill -f "SCREEN.*claudeman" # Kill all
|
||||
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.
|
||||
A: Yes! Claudeman spawns real Claude CLI processes with full hook support.
|
||||
|
||||
**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").
|
||||
A: Screen sessions persist. Claudeman auto-discovers them on startup.
|
||||
|
||||
**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
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npx tsx src/index.ts web # Dev mode
|
||||
npm run build # Production
|
||||
npx tsc --noEmit # Type check
|
||||
npx tsx src/index.ts web # Dev mode (no build needed)
|
||||
npm run build # Production build
|
||||
npm test # Run 196 tests
|
||||
npx tsc --noEmit # Type check
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```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 |
|
||||
See [CLAUDE.md](./CLAUDE.md) for full development documentation.
|
||||
|
||||
---
|
||||
|
||||
@@ -679,30 +407,15 @@ npx vitest run -t "name" # By pattern
|
||||
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](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
|
||||
MIT License — see [LICENSE](LICENSE) for details.
|
||||
|
||||
---
|
||||
|
||||
<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>
|
||||
|
||||
Reference in New Issue
Block a user