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

docs: rewrite README focused on core capabilities

Browse Source 
- Persistent Screen Sessions
- Respawn Controller (autonomous work while you sleep)
- Ralph Wiggum Loop Tracking
- Smart Token Management
- Multi-Session Dashboard

Removed problem/solution framing, now focused purely on features.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
arkon
2026-01-21 14:24:21 +01:00
co-authored by Claude Opus 4.5
parent d726d2f661
commit 2eaa7dfed3
1 changed files with 137 additions and 408 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+137 -408
View File
@@ -1,13 +1,11 @@
<h1 align="center">
<br>
🤖 Claudeman
<br>
</h1>
<h3 align="center">Track Claude Code Sessions Better Than Ever</h3>
<p align="center">
<em>Run 20 agents in parallel. Track them in real-time. The Respawn Controller keeps them working while you sleep.</em>
<em>Persistent sessions. Ralph Loop tracking. Respawn agents. Autonomous work while you sleep.</em>
</p>
<p align="center">
@@ -18,15 +16,6 @@
<img src="https://img.shields.io/badge/Tests-258%20passing-22c55e?style=flat-square" alt="Tests">
</p>
<p align="center">
<a href="#-the-problem">Problem</a> •
<a href="#-the-solution">Solution</a> •
<a href="#-quick-start">Quick Start</a> •
<a href="#-features">Features</a> •
<a href="#-ralph-wiggum-loops">Ralph Loops</a> •
<a href="#-api">API</a>
</p>
---
<p align="center">
@@ -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:
<table>
<tr>
<td width="50%">
### 🖥️ 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
</td>
<td width="50%">
### 💾 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
</td>
</tr>
<tr>
<td width="50%">
### 🔄 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
</td>
<td width="50%">
### 🎯 Ralph Loop Tracking
- Detects `<promise>COMPLETE</promise>` patterns
- Tracks TodoWrite progress (`- [x]`, `- [ ]`)
- Shows iteration count (`[5/50]`)
- Real-time progress visualization
</td>
</tr>
</table>
---
## 🚀 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
<p align="center">
<img src="docs/screenshots/session-running.png" alt="Terminal Streaming" width="800">
</p>
- **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**.
<p align="center">
<img src="docs/images/ralph-tracker-16tasks.png" alt="Ralph Loop Tracking" width="800">
</p>
### 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 | `<promise>COMPLETE</promise>` | ✅ |
| Custom phrases | `<promise>AUTH_REFACTOR_DONE</promise>` | ✅ |
| 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:
<p align="center">
<img src="docs/images/ralph-tracker-16tasks.png" alt="Ralph Loop Tracking" width="800">
</p>
**Auto-detects:**
| Pattern | Example |
|---------|---------|
| Promise tags | `<promise>COMPLETE</promise>` |
| Custom phrases | `<promise>AUTH_REFACTOR_DONE</promise>` |
| 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
<p align="center">
<img src="docs/screenshots/session-running.png" alt="Session Running" width="800">
</p>
---
## 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 `<promise>YOUR_PHRASE</promise>` 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)
---
<p align="center">
<strong>Track sessions. Control respawn. Ship while you sleep.</strong>
<br>
<sub>Built for developers running serious autonomous Claude Code sessions.</sub>
</p>