diff --git a/README.md b/README.md index d3c639de..894ab855 100644 --- a/README.md +++ b/README.md @@ -1,368 +1,203 @@ -# Claudeman +

+ Claudeman +

-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![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) +

Claudeman

-**Take full control of your Claude Code sessions like never before.** +

+ The missing control plane for Claude Code.
+ Run 20 autonomous agents. Track them in real-time. Never lose work again. +

-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. +

+ License: MIT + Node.js Version + TypeScript + Tests +

-> 🎯 **Perfect for**: Autonomous coding sprints, overnight refactors, parallel development, long-running code reviews, time-boxed AI tasks +

+ Quick Start • + Features • + Ralph Loops • + API • + Full Docs +

--- -## 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 +``` + +

+ Claudeman Interface +

+ +**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 `COMPLETE` 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 - -![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* +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 `PHRASE` 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: REFACTOR_COMPLETE +Loop: REFACTOR_COMPLETE (4.2h elapsed) +Tasks: 8/12 complete +``` + +Auto-enables when it detects: +- `PHRASE` 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 `COMPLETE` 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 | `COMPLETE` | | Custom phrases | `AUTH_REFACTOR_DONE` | -| 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: AUTH_DONE 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 | `COMPLETE` | -| 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 ] # Start session -claudeman list # List sessions -claudeman session stop # Stop session -claudeman session logs # View output -``` +# Sessions +claudeman start [--dir ] # Start new session +claudeman list # List all sessions +claudeman session stop # 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 "" [options] - --dir # Working directory - --priority # Priority (higher = first) - --completion # Completion phrase - --timeout # Timeout - -claudeman task list [--status pending] -claudeman task remove -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- 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 `PHRASE`. +A: Yes! Use `YOUR_PHRASE` 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. ---

- Made with care for autonomous AI development + Stop babysitting Claude. Start shipping.
+ Built for developers who want Claude Code to work while they sleep.