Codeman/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Claudeman is a Claude Code session manager with a web interface and autonomous Ralph Loop. It spawns Claude CLI processes via PTY, streams output in real-time via SSE, and supports scheduled/timed runs.

Tech Stack: TypeScript, Node.js, Fastify, Server-Sent Events, node-pty

Commands

# Development
npm run build          # Compile TypeScript + copy static files to dist/web/
npm run dev            # Run with tsx (no build needed)

# Production
npm link               # Make 'claudeman' globally available
claudeman web          # Start web interface on port 3000
claudeman web -p 8080  # Custom port

# CLI examples
claudeman status                           # Overall status
claudeman session start --dir /path        # Start Claude session
claudeman task add "Fix bug" --priority 5  # Add task to queue
claudeman ralph start --min-hours 4        # Start autonomous loop

Architecture

Core Data Flow

1. Session (src/session.ts) spawns Claude CLI via node-pty with --dangerously-skip-permissions
2. PTY output is buffered and parsed for JSON messages (types: system, assistant, result)
3. WebServer (src/web/server.ts) broadcasts events to connected SSE clients
4. State persists to ~/.claudeman/state.json via StateStore

Key Components

• Session: Wraps claude -p --output-format stream-json as PTY subprocess. Emits output, terminal, message, completion, exit events.
• WebServer: Fastify server exposing REST API + SSE endpoint at /api/events. Manages ScheduledRuns (timed loops that repeatedly run prompts).
• RespawnController: Manages automatic respawning of interactive Claude sessions. Detects idle state → sends update prompt → /clear → /init → repeats.
• RalphLoop: Autonomous controller that assigns tasks to idle sessions and detects completion via <promise>PHRASE</promise> markers.
• TaskQueue: Priority-based queue with dependency support.

REST API Endpoints

GET  /api/status              # Full state (sessions + scheduled + respawn)
GET  /api/sessions            # List all sessions
POST /api/sessions            # Create session { workingDir }
POST /api/sessions/:id/run    # Run prompt { prompt }
POST /api/sessions/:id/input  # Send input to interactive session
POST /api/sessions/:id/interactive-respawn  # Start interactive + respawn

# Respawn control
GET  /api/sessions/:id/respawn        # Get respawn status
POST /api/sessions/:id/respawn/start  # Start respawn controller
POST /api/sessions/:id/respawn/stop   # Stop respawn controller
PUT  /api/sessions/:id/respawn/config # Update respawn config

GET  /api/scheduled           # List scheduled runs
POST /api/scheduled           # Create { prompt, workingDir, durationMinutes }
POST /api/cases               # Create case directory with CLAUDE.md template

SSE Events

Events broadcast to /api/events clients:

• session:output, session:terminal, session:message
• session:completion, session:exit, session:working, session:idle
• scheduled:created, scheduled:updated, scheduled:log, scheduled:completed
• respawn:started, respawn:stopped, respawn:stateChanged
• respawn:cycleStarted, respawn:cycleCompleted, respawn:stepSent, respawn:stepCompleted, respawn:log

Code Patterns

Claude Message Parsing

Claude CLI outputs newline-delimited JSON. Strip ANSI codes before parsing:

const cleanLine = line.replace(/\x1b\[[0-9;]*m/g, '');
const msg = JSON.parse(cleanLine) as ClaudeMessage;
// msg.type: 'system' | 'assistant' | 'result'
// msg.message?.content: Array<{ type: 'text', text: string }>
// msg.total_cost_usd: number (on result messages)

Idle Detection

Session detects idle state by watching for prompt character (❯ or \u276f) and waiting 2 seconds without activity.

Respawn Controller State Machine

RespawnController (src/respawn-controller.ts) cycles through states to keep Claude productive:

WATCHING → SENDING_UPDATE → WAITING_UPDATE → SENDING_CLEAR → WAITING_CLEAR → SENDING_INIT → WAITING_INIT → WATCHING

Default sequence:

1. Detect idle (5s timeout after prompt with no activity)
2. Send: update all the docs and CLAUDE.md
3. Wait for completion (detects prompt after work stops)
4. Send: /clear
5. Send: /init
6. Return to watching

Configuration options (RespawnConfig):

• idleTimeoutMs: How long to wait after prompt (default: 5000)
• updatePrompt: Custom prompt to send (default: "update all the docs and CLAUDE.md")
• interStepDelayMs: Delay between steps (default: 1000)
• enabled: Toggle respawn on/off

Template Generation

src/templates/claude-md.ts generates CLAUDE.md files for new cases via the /api/cases endpoint.

Session Log

Date	Tasks Completed	Files Changed	Notes
2026-01-18	Initial implementation	All files	Core CLI + web interface
2026-01-18	Add web interface	src/web/*	Fastify + SSE + responsive UI
2026-01-18	Add RespawnController	src/respawn-controller.ts, src/web/server.ts, src/types.ts	Auto-respawn loop with state machine