๐ค Claudeman
Track Claude Code Sessions Better Than Ever
Run 20 agents in parallel. Track them in real-time. The Respawn Controller keeps them working while you sleep.
Problem โข
Solution โข
Quick Start โข
Features โข
Ralph Loops โข
API
---
---
## ๐จ The Problem
You're running Claude Code on a complex refactor. **Three hours in:**
| Issue | Impact |
|-------|--------|
| ๐ฅ **Session crashes** | All your context is gone. Start over. |
| ๐ **Token limit hit** | Forced to manually `/clear` โ breaks your flow |
| ๐ด **You went to sleep** | Claude finished at 2am, sat idle for 6 hours |
| ๐คฏ **5 parallel sessions** | Which one had the auth fix? Where's the API changes? |
| ๐ธ **Surprise costs** | No visibility into token usage until the bill arrives |
**Claude Code is incredibly powerful.**
**Now you can track and manage it like never before.**
---
## โจ The Solution
```bash
git clone https://github.com/Ark0N/claudeman.git && cd claudeman
npm install && npm run build
claudeman web
```
**Open http://localhost:3000** and you get:
|
### ๐ฅ๏ธ Multi-Session Dashboard
- **20 parallel sessions** with real-time terminals
- Tab-based navigation with keyboard shortcuts
- Per-session token tracking and cost monitoring
- One-click bulk operations
|
### ๐พ Crash-Proof Persistence
- Every session runs in **GNU Screen**
- Survives server restarts, network drops, machine sleep
- Auto-discovery of orphaned sessions on startup
- Never lose work again
|
|
### ๐ Respawn Controller
- **The key to autonomous work while you sleep**
- Detects when Claude becomes idle and restarts work
- Auto-cycles `/clear` โ `/init` to continue fresh
- Keeps going even if Ralph Wiggum loops stop
- Run for **24+ hours** completely unattended
|
### ๐ฏ Ralph Loop Tracking
- Detects `COMPLETE` patterns
- Tracks TodoWrite progress (`- [x]`, `- [ ]`)
- Shows iteration count (`[5/50]`)
- Real-time progress visualization
|
---
## ๐ Quick Start
### Prerequisites
| Requirement | Why |
|-------------|-----|
| **Node.js 18+** | ES2022 module syntax |
| **Claude CLI** | `claude` command in PATH ([Install](https://claude.ai/code)) |
| **GNU Screen** | Session persistence (`apt install screen` / `brew install screen`) |
### Installation
```bash
# Clone and install
git clone https://github.com/Ark0N/claudeman.git
cd claudeman
npm install
npm run build
# Make 'claudeman' available globally (optional)
npm link
```
### Launch
```bash
# Production
claudeman web
# Development (no build required)
npx tsx src/index.ts web
# Custom port
claudeman web -p 8080
```
### Your First Session
1. Open **http://localhost:3000**
2. Press **`Ctrl+Enter`** or click **"Run Claude"**
3. Your session is now:
- โ
Running in GNU Screen (persistent)
- โ
Tracking tokens and costs
- โ
Ready for Ralph Loop detection
---
## ๐ฎ Features
### Real-Time Terminal Streaming
- **60fps rendering** โ Server batches at 16ms, client uses `requestAnimationFrame`
- **Full xterm.js** โ Colors, cursor, resize, selection, everything works
- **No polling** โ Real-time SSE for instant updates
### Smart Token Management
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ TOKEN LIFECYCLE โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ 0k โโโโโโโโโโโ 110k โโโโโโโโโโโ 140k โโโโโโโโโโโ 200k โ
โ โ โ โ
โ โผ โผ โ
โ Auto-Compact Auto-Clear โ
โ (/compact) (/clear) โ
โ โ โ โ
โ โโโ Summarize โโโโดโโ Reset & Continue โโบ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
| Threshold | Action | What Happens |
|-----------|--------|--------------|
| **110k tokens** | Auto `/compact` | Context is summarized, work continues |
| **140k tokens** | Auto `/clear` | Full reset with `/init`, fresh start |
**Configure per-session:**
```bash
curl -X POST localhost:3000/api/sessions/:id/auto-compact \
-d '{"enabled": true, "threshold": 100000}'
```
### Session Persistence
Every Claude session runs inside GNU Screen with environment awareness:
```bash
# Inside every Claudeman session:
CLAUDEMAN_SCREEN=1
CLAUDEMAN_SESSION_ID=abc-123-def
CLAUDEMAN_SCREEN_NAME=claudeman-myproject
```
**Why this matters:**
- Claude knows it's in a managed session
- Won't accidentally kill its own screen
- The default CLAUDE.md template includes safety instructions
### Resource Monitoring
The dashboard shows real-time resource usage:
| Metric | Location | Warning Threshold |
|--------|----------|-------------------|
| Memory per session | Monitor panel | Yellow at 500MB, Red at 1GB |
| Total screen count | Status bar | Shown with uptime |
| Token usage | Per-session | Color-coded by threshold |
| Cost tracking | Per-session | Running USD total |
---
## ๐ Ralph Wiggum Loops
The **Ralph Loop** is Claudeman's killer feature: **run Claude autonomously for 24+ hours**.
### How It Works
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ RALPH LOOP CYCLE โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ
โ โโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโโ โ
โ โ WATCH โโโโโบโ DETECT โโโโโบโ RESPAWN โโโโโบโ CONTINUEโ โ
โ โ (idle) โ โ complete โ โ cycle โ โ work โ โ
โ โโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโ โโโโโโฌโโโโโ โ
โ โฒ โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
### Detection Patterns
Claudeman automatically detects Ralph loops when it sees:
| Pattern | Example | Auto-Enables |
|---------|---------|--------------|
| Promise tags | `COMPLETE` | โ
|
| Custom phrases | `AUTH_REFACTOR_DONE` | โ
|
| TodoWrite | `- [ ] Task`, `- [x] Done` | โ
|
| Iterations | `[5/50]`, `Iteration 5 of 50` | โ
|
| Skill command | `/ralph-loop:ralph-loop` | โ
|
### Running a Ralph Loop
**Via CLI:**
```bash
# Queue tasks
claudeman task add "Review all files in src/ for security issues"
claudeman task add "Add comprehensive test coverage"
claudeman task add "Update all documentation"
# Start loop (minimum 8 hours)
claudeman ralph start --min-hours 8
# Check status
claudeman ralph status
```
**Via API:**
```bash
# Enable respawn with timer
curl -X POST localhost:3000/api/sessions/:id/respawn/enable \
-H "Content-Type: application/json" \
-d '{
"config": {
"updatePrompt": "continue improving the codebase",
"idleTimeoutMs": 5000
},
"durationMinutes": 480
}'
```
### Time-Aware Loops
When you specify a minimum duration, Claudeman:
1. Completes all primary tasks
2. Checks elapsed time
3. **If minimum not reached:** Generates follow-up tasks
- Code optimization
- Test coverage improvements
- Security hardening
- Documentation gaps
4. Only outputs completion phrase when time is met
---
## โจ๏ธ Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `Ctrl+Enter` | Quick-start: Create case + start session |
| `Ctrl+W` | Close current session |
| `Ctrl+Tab` | Switch to next session |
| `Ctrl+Shift+Tab` | Switch to previous session |
| `Ctrl+K` | Kill all sessions |
| `Ctrl+L` | Clear terminal |
| `Ctrl++` / `Ctrl+-` | Increase/decrease font size |
| `Ctrl+?` | Show help overlay |
| `Escape` | Close panels and modals |
---
## ๐ก API Reference
### Session Management
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/sessions` | List all sessions |
| `POST` | `/api/sessions` | Create new session |
| `GET` | `/api/sessions/:id` | Get session details |
| `DELETE` | `/api/sessions/:id` | Delete session |
| `POST` | `/api/sessions/:id/input` | Send terminal input |
| `POST` | `/api/sessions/:id/resize` | Resize terminal |
| `POST` | `/api/sessions/:id/interactive` | Start interactive mode |
### Respawn Control
| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/sessions/:id/respawn/start` | Start respawn controller |
| `POST` | `/api/sessions/:id/respawn/stop` | Stop respawn controller |
| `POST` | `/api/sessions/:id/respawn/enable` | Enable with config + timer |
| `PUT` | `/api/sessions/:id/respawn/config` | Update running config |
### Token Management
| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/sessions/:id/auto-compact` | Configure auto-compact |
| `POST` | `/api/sessions/:id/auto-clear` | Configure auto-clear |
### Ralph Loop Tracking
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/sessions/:id/inner-state` | Get loop state + todos |
| `POST` | `/api/sessions/:id/inner-config` | Configure tracking |
### Real-Time Events
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/events` | SSE stream for all updates |
| `GET` | `/api/status` | Full application state |
| `GET` | `/api/screens` | Screen session list |
### Quick Start
| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/quick-start` | Create case + start session |
| `GET` | `/api/cases` | List available cases |
| `POST` | `/api/cases` | Create new case |
---
## ๐๏ธ Architecture
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ CLAUDEMAN โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ
โ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Web UI โ โ REST API โ โ SSE Events โ โ
โ โ (xterm.js) โโโโค (Fastify) โโโโค (/api/events) โ โ
โ โโโโโโโโโโโโโโโโ โโโโโโโโฌโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Session Manager โ โ
โ โ โโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โ โ
โ โ โSession 1โ โSession 2โ โSession Nโ โ RespawnControllerโ โ โ
โ โ โ (PTY) โ โ (PTY) โ โ (PTY) โ โ (per-session) โ โ โ
โ โ โโโโโโฌโโโโโ โโโโโโฌโโโโโ โโโโโโฌโโโโโ โโโโโโโโโโโโโโโโโโโ โ โ
โ โโโโโโโโโผโโโโโโโโโโโโผโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ โ โ
โ โโโโโโโโโดโโโโโโโโโโโโดโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ GNU Screen Manager โ โ
โ โ claudeman-abc claudeman-def claudeman-xyz โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Claude CLI โ โ
โ โ claude --dangerously-skip-permissions โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
### Key Components
| Component | File | Purpose |
|-----------|------|---------|
| **Session** | `src/session.ts` | PTY wrapper for Claude CLI |
| **RespawnController** | `src/respawn-controller.ts` | Autonomous cycling state machine |
| **ScreenManager** | `src/screen-manager.ts` | GNU Screen lifecycle management |
| **InnerLoopTracker** | `src/inner-loop-tracker.ts` | Ralph loop detection |
| **TaskTracker** | `src/task-tracker.ts` | Background task parsing |
| **WebServer** | `src/web/server.ts` | Fastify REST + SSE |
| **StateStore** | `src/state-store.ts` | JSON persistence |
---
## ๐งช Development
```bash
# Install dependencies
npm install
# Run in development mode (no build needed)
npx tsx src/index.ts web
# Type checking
npm run typecheck
# Run tests
npm test # All tests
npm run test:watch # Watch mode
npx vitest run test/session.test.ts # Single file
# Build for production
npm run build
```
### Test Structure
```
test/
โโโ unit/
โ โโโ respawn-controller.test.ts
โ โโโ inner-loop-tracker.test.ts
โ โโโ ralph-loop.test.ts
โ โโโ session-manager.test.ts
โ โโโ ...
โโโ integration/
โโโ session.test.ts
โโโ quick-start.test.ts
โโโ ...
```
---
## ๐ Performance
Built for **24+ hour autonomous runs** with multiple sessions:
| Optimization | Implementation |
|--------------|----------------|
| **60fps streaming** | 16ms server batching, `requestAnimationFrame` client |
| **Memory management** | Auto-trimming buffers (5MB โ 4MB on overflow) |
| **Event debouncing** | 50-500ms debounce on rapid state changes |
| **CSS containment** | Isolated paint operations per component |
| **Incremental DOM** | Only changed elements re-render |
### Buffer Limits
| Buffer | Max Size | Trim To |
|--------|----------|---------|
| Terminal | 5MB | 4MB |
| Text output | 2MB | 1.5MB |
| Messages | 1000 | 800 |
| Respawn | 1MB | 512KB |
---
## โ FAQ
**Q: How long can sessions run?**
A: 24+ hours. Automatic buffer management keeps memory stable.
**Q: Does it work with Claude Code hooks?**
A: Yes! Claudeman spawns real Claude CLI processes with full hook support.
**Q: What if the server restarts?**
A: Screen sessions persist. Claudeman auto-discovers them on startup.
**Q: Can I use custom completion phrases?**
A: Yes! Use `YOUR_PHRASE` in your prompts.
**Q: Maximum parallel sessions?**
A: 20 in the UI, 50 via API.
**Q: Does it work on macOS/Linux/Windows?**
A: macOS and Linux fully supported. Windows requires WSL2.
---
## ๐ค 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
See [CLAUDE.md](./CLAUDE.md) for detailed development documentation.
---
## ๐ License
MIT License โ see [LICENSE](LICENSE) for details.
---
Track sessions. Control respawn. Ship while you sleep.
Built for developers running serious autonomous Claude Code sessions.