Codeman/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

• Project Name: Claudeman
• Description: Claude Code session manager with web interface and autonomous Ralph Loop
• Tech Stack: TypeScript, Node.js, Fastify, Server-Sent Events
• Last Updated: 2026-01-18

Architecture

claudeman/
├── src/
│   ├── index.ts           # CLI entry point
│   ├── cli.ts             # Commander.js CLI commands
│   ├── types.ts           # TypeScript type definitions
│   ├── session.ts         # Claude CLI subprocess wrapper
│   ├── session-manager.ts # Session registry and lifecycle
│   ├── task.ts            # Task definitions
│   ├── task-queue.ts      # Priority queue with dependencies
│   ├── ralph-loop.ts      # Autonomous loop controller
│   ├── state-store.ts     # JSON persistence (~/.claudeman/state.json)
│   └── web/
│       ├── server.ts      # Fastify server with SSE
│       └── public/        # Static frontend files
│           ├── index.html
│           ├── styles.css
│           └── app.js
├── dist/                  # Compiled output
├── package.json
└── tsconfig.json

Key Commands

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

# Usage
claudeman web          # Start web interface on port 3000
claudeman web -p 8080  # Custom port

# CLI commands
claudeman status       # Show overall status
claudeman task add "<prompt>" --priority N
claudeman ralph start --min-hours 4

How It Works

1. Session: Wraps claude -p --output-format stream-json subprocess
2. Web Server: Fastify serves static files + REST API + SSE for real-time
3. Timed Runs: Loop that repeatedly runs prompts until duration expires
4. State: Persisted to ~/.claudeman/state.json

Code Patterns

Session JSON Parsing

Claude CLI outputs newline-delimited JSON with types: system, assistant, result

// Parse streaming JSON lines
const msg = JSON.parse(line) as ClaudeMessage;
if (msg.type === 'assistant' && msg.message?.content) {
  // Extract text from content blocks
}

SSE Broadcasting

private broadcast(event: string, data: unknown): void {
  for (const client of this.sseClients) {
    client.raw.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
  }
}

Work Principles

• Full permissions granted via .claude/settings.json
• Commit after every meaningful change
• Use conventional commits: feat:, fix:, docs:, refactor:

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