diff --git a/README.md b/README.md
index 2f1457d4..15e3c22d 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,11 @@
-
๐ค 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.
+ Persistent sessions. Ralph Loop tracking. Respawn agents. Autonomous work while you sleep.
@@ -18,15 +16,6 @@
-
- Problem โข
- Solution โข
- Quick Start โข
- Features โข
- Ralph Loops โข
- API
-
-
---
@@ -35,250 +24,43 @@
---
-## ๐จ The Problem
+## What Claudeman Does
-You're running Claude Code on a complex refactor. **Three hours in:**
+### ๐พ Persistent Screen Sessions
-| 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
+Every Claude session runs inside **GNU Screen** โ sessions survive server restarts, network drops, and machine sleep.
```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:
+# Your sessions are always recoverable
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 |
+- Sessions auto-recover on startup
+- Ghost session discovery finds orphaned screens
+- Claude knows it's managed (won't kill its own screen)
---
-## ๐ Ralph Wiggum Loops
+### ๐ Respawn Controller
-The **Ralph Loop** is Claudeman's killer feature: **run Claude autonomously for 24+ hours**.
-
-
- 
-
-
-### How It Works
+**The core of autonomous work.** When Claude becomes idle, the Respawn Controller kicks in:
```
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-โ RALPH LOOP CYCLE โ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
-โ โ
-โ โโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโโ โ
-โ โ WATCH โโโโโบโ DETECT โโโโโบโ RESPAWN โโโโโบโ CONTINUEโ โ
-โ โ (idle) โ โ complete โ โ cycle โ โ work โ โ
-โ โโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโ โโโโโโฌโโโโโ โ
-โ โฒ โ โ
-โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
-โ โ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
+WATCHING โ IDLE DETECTED โ SEND UPDATE โ CLEAR โ INIT โ CONTINUE
+ โ โ
+ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
-### Detection Patterns
+- Detects idle state via prompt indicators (`โต send`, `โฏ`)
+- Sends configurable update prompts to continue work
+- Auto-cycles `/clear` โ `/init` for fresh context
+- **Keeps working even when Ralph Wiggum loops stop**
+- Run for **24+ hours** completely unattended
-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
+# Enable respawn with 8-hour timer
curl -X POST localhost:3000/api/sessions/:id/respawn/enable \
-H "Content-Type: application/json" \
-d '{
@@ -290,99 +72,135 @@ curl -X POST localhost:3000/api/sessions/:id/respawn/enable \
}'
```
-### Time-Aware Loops
+---
-When you specify a minimum duration, Claudeman:
+### ๐ฏ Ralph Wiggum Loop Tracking
-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
+Claudeman detects and tracks Ralph loops running inside Claude Code:
+
+
+
+
+
+**Auto-detects:**
+| Pattern | Example |
+|---------|---------|
+| Promise tags | `COMPLETE` |
+| Custom phrases | `AUTH_REFACTOR_DONE` |
+| TodoWrite | `- [ ] Task`, `- [x] Done` |
+| Iterations | `[5/50]`, `Iteration 5 of 50` |
+
+**Tracks in real-time:**
+- Completion phrase detection
+- Todo progress (`8/12 complete`)
+- Iteration count
+- Elapsed time
---
-## โจ๏ธ Keyboard Shortcuts
+### ๐ Smart Token Management
+
+Never hit token limits unexpectedly:
+
+| Threshold | Action | Result |
+|-----------|--------|--------|
+| **110k tokens** | Auto `/compact` | Context summarized, work continues |
+| **140k tokens** | Auto `/clear` | Fresh start with `/init` |
+
+```bash
+# Configure per-session
+curl -X POST localhost:3000/api/sessions/:id/auto-compact \
+ -d '{"enabled": true, "threshold": 100000}'
+```
+
+---
+
+### ๐ฅ๏ธ Multi-Session Dashboard
+
+Run **20 parallel sessions** with full visibility:
+
+- Real-time xterm.js terminals (60fps streaming)
+- Per-session token and cost tracking
+- Tab-based navigation
+- One-click session management
+
+
+
+
+
+---
+
+## Quick Start
+
+```bash
+# Clone and build
+git clone https://github.com/Ark0N/claudeman.git
+cd claudeman
+npm install && npm run build
+
+# Start the web interface
+claudeman web
+
+# Open http://localhost:3000
+# Press Ctrl+Enter to start your first session
+```
+
+**Requirements:**
+- Node.js 18+
+- Claude CLI in PATH
+- GNU Screen (`apt install screen` / `brew install screen`)
+
+---
+
+## 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+Enter` | Quick-start session |
+| `Ctrl+W` | Close session |
+| `Ctrl+Tab` | Next 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
+## API
+### Sessions
| Method | Endpoint | Description |
|--------|----------|-------------|
-| `GET` | `/api/sessions` | List all sessions |
-| `POST` | `/api/sessions` | Create new session |
-| `GET` | `/api/sessions/:id` | Get session details |
+| `GET` | `/api/sessions` | List all |
+| `POST` | `/api/quick-start` | Create case + start session |
| `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
+| `POST` | `/api/sessions/:id/input` | Send input |
+### Respawn
| 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
+| `POST` | `/api/sessions/:id/respawn/stop` | Stop controller |
+| `PUT` | `/api/sessions/:id/respawn/config` | Update config |
+### Ralph 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
-
+### Real-Time
| 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 |
+| `GET` | `/api/events` | SSE stream |
+| `GET` | `/api/status` | Full app state |
---
-## ๐๏ธ Architecture
+## Architecture
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ CLAUDEMAN โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
-โ โ
โ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Web UI โ โ REST API โ โ SSE Events โ โ
โ โ (xterm.js) โโโโค (Fastify) โโโโค (/api/events) โ โ
@@ -390,144 +208,55 @@ When you specify a minimum duration, Claudeman:
โ โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Session Manager โ โ
-โ โ โโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โ โ
-โ โ โSession 1โ โSession 2โ โSession Nโ โ RespawnControllerโ โ โ
-โ โ โ (PTY) โ โ (PTY) โ โ (PTY) โ โ (per-session) โ โ โ
-โ โ โโโโโโฌโโโโโ โโโโโโฌโโโโโ โโโโโโฌโโโโโ โโโโโโโโโโโโโโโโโโโ โ โ
-โ โโโโโโโโโผโโโโโโโโโโโโผโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
-โ โ โ โ โ
-โ โโโโโโโโโดโโโโโโโโโโโโดโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
-โ โ GNU Screen Manager โ โ
-โ โ claudeman-abc claudeman-def claudeman-xyz โ โ
-โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
+โ โ โโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ
+โ โ โ Session โ โ Session โ โ RespawnController โ โ โ
+โ โ โ (PTY) โ โ (PTY) โ โ (per-session autonomous) โ โ โ
+โ โ โโโโโโฌโโโโโ โโโโโโฌโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ
+โ โโโโโโโโโผโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
+โ โ โ โ
+โ โโโโโโโโโดโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
+โ โ GNU Screen Manager (Persistence) โ โ
+โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ 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 |
+## Performance
+
+Optimized for long-running autonomous sessions:
+
+| Feature | Implementation |
+|---------|----------------|
+| **60fps terminal** | 16ms server batching, `requestAnimationFrame` client |
+| **Memory management** | Auto-trimming buffers (5MB max) |
+| **Event debouncing** | 50-500ms on rapid state changes |
---
-## ๐งช Development
+## 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
+npx tsx src/index.ts web # Dev mode
+npm run build # Production build
+npm test # Run tests
```
-### 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
- โโโ ...
-```
+See [CLAUDE.md](./CLAUDE.md) for full documentation.
---
-## ๐ Performance
+## License
-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.
+MIT โ see [LICENSE](LICENSE)
---
Track sessions. Control respawn. Ship while you sleep.
-
- Built for developers running serious autonomous Claude Code sessions.