2026-01-18 04:50:46 +01:00
# CLAUDE.md
2026-01-18 07:31:19 +01:00
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
2026-01-18 04:50:46 +01:00
## Project Overview
2026-01-18 05:17:06 +01:00
2026-01-18 07:31:19 +01:00
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.
2026-01-18 04:50:46 +01:00
2026-01-19 11:19:13 +01:00
**Tech Stack** : TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, Server-Sent Events, node-pty
2026-01-18 05:17:06 +01:00
2026-01-19 02:06:37 +01:00
**Requirements** : Node.js 18+, Claude CLI (`claude` ) installed and available in PATH
2026-01-18 07:31:19 +01:00
## Commands
2026-01-18 05:17:06 +01:00
```bash
2026-01-18 07:31:19 +01:00
npm run build # Compile TypeScript + copy static files to dist/web/
2026-01-18 07:38:19 +01:00
npm run clean # Remove dist/
2026-01-18 05:17:06 +01:00
2026-01-19 03:43:59 +01:00
# Start web server (pick one):
npx tsx src/index.ts web # Dev mode - no build needed (RECOMMENDED)
npx tsx src/index.ts web -p 8080 # Dev mode with custom port
node dist/index.js web # After npm run build
claudeman web # After npm link
2026-01-19 11:19:13 +01:00
# GOTCHA: `npm run dev` runs CLI help, NOT the web server
2026-01-19 07:33:33 +01:00
# Always use `npx tsx src/index.ts web` for development
2026-01-19 05:28:45 +01:00
2026-01-19 11:19:13 +01:00
# Testing (vitest with vi.mock() - no real Claude CLI spawned)
2026-01-19 05:28:45 +01:00
npm run test # Run all tests once
npm run test:watch # Watch mode
npm run test:coverage # With coverage report
npx vitest run test/session.test.ts # Single file
npx vitest run -t "should create session" # By pattern
2026-01-19 11:19:13 +01:00
# Debugging
screen -ls # List GNU screen sessions
screen -r <name> # Attach to screen session
curl localhost:3000/api/sessions # Check active sessions
2026-01-18 05:17:06 +01:00
```
2026-01-18 07:31:19 +01:00
## Architecture
2026-01-18 05:17:06 +01:00
2026-01-18 07:38:19 +01:00
```
src/
2026-01-19 11:19:13 +01:00
├── index.ts # CLI entry (commander)
├── cli.ts # CLI commands
2026-01-19 00:49:30 +01:00
├── session.ts # Core: PTY wrapper for Claude CLI + token tracking
2026-01-18 07:38:19 +01:00
├── session-manager.ts # Manages multiple sessions
2026-01-19 11:19:13 +01:00
├── screen-manager.ts # GNU screen persistence + process stats
2026-01-18 07:38:19 +01:00
├── respawn-controller.ts # Auto-respawn state machine
├── ralph-loop.ts # Autonomous task assignment
2026-01-19 11:19:13 +01:00
├── task-queue.ts # Priority queue with dependencies
2026-01-18 07:38:19 +01:00
├── state-store.ts # Persistence to ~/.claudeman/state.json
├── types.ts # All TypeScript interfaces
├── web/
2026-01-19 03:02:04 +01:00
│ ├── server.ts # Fastify REST API + SSE + session restoration
2026-01-19 11:19:13 +01:00
│ └── public/ # Vanilla JS frontend (xterm.js, no bundler)
│ ├── app.js # Main app logic, SSE handling, tab management
│ ├── styles.css # All styles including responsive/mobile
│ └── index.html # Single page with modal templates
2026-01-18 07:38:19 +01:00
└── templates/
└── claude-md.ts # CLAUDE.md generator for new cases
```
2026-01-18 07:31:19 +01:00
2026-01-18 07:38:19 +01:00
### Data Flow
1. **Session** spawns `claude -p --dangerously-skip-permissions` via `node-pty`
2. PTY output is buffered, ANSI stripped, and parsed for JSON messages
3. **WebServer** broadcasts events to SSE clients at `/api/events`
2026-01-18 07:31:19 +01:00
4. State persists to `~/.claudeman/state.json` via **StateStore**
### Key Components
2026-01-19 11:19:13 +01:00
- **Session** (`src/session.ts` ): Wraps Claude CLI as PTY subprocess. Two modes: `runPrompt(prompt)` for one-shot, `startInteractive()` for persistent terminal. Emits events: `output` , `terminal` , `message` , `completion` , `exit` , `idle` , `working` , `autoClear` , `clearTerminal` .
2026-01-18 07:31:19 +01:00
2026-01-19 11:19:13 +01:00
- **RespawnController** (`src/respawn-controller.ts` ): State machine that keeps sessions productive. Detects idle → sends update prompt → optionally `/clear` → optionally `/init` → repeats. State flow: `WATCHING → SENDING_UPDATE → WAITING_UPDATE → SENDING_CLEAR → WAITING_CLEAR → SENDING_INIT → WAITING_INIT → WATCHING`
2026-01-19 00:49:30 +01:00
2026-01-19 11:19:13 +01:00
- **ScreenManager** (`src/screen-manager.ts` ): Wraps sessions in GNU screen for persistence across server restarts. On startup, reconciles with `screen -ls` to restore sessions.
2026-01-18 07:31:19 +01:00
2026-01-19 11:19:13 +01:00
- **WebServer** (`src/web/server.ts` ): Fastify server with REST API (`/api/*` ) + SSE (`/api/events` ). Wires session events to SSE broadcast.
2026-01-19 02:07:46 +01:00
2026-01-18 07:38:19 +01:00
### Session Modes
2026-01-18 07:31:19 +01:00
2026-01-19 11:19:13 +01:00
- **One-Shot** (`runPrompt(prompt)` ): Single prompt execution, emits completion, exits
- **Interactive** (`startInteractive()` ): Persistent PTY terminal with resize support
2026-01-19 10:36:30 +01:00
- **Shell** (`startShell()` ): Plain bash/zsh terminal without Claude
2026-01-19 01:42:47 +01:00
2026-01-18 05:17:06 +01:00
## Code Patterns
2026-01-18 07:31:19 +01:00
### Claude Message Parsing
Claude CLI outputs newline-delimited JSON. Strip ANSI codes before parsing:
2026-01-18 05:17:06 +01:00
```typescript
2026-01-18 07:31:19 +01:00
const cleanLine = line . replace ( /\x1b\[[0-9;]*m/g , '' );
const msg = JSON . parse ( cleanLine ) as ClaudeMessage ;
2026-01-18 21:37:03 +01:00
// msg.type: 'system' | 'assistant' | 'user' | 'result'
2026-01-18 07:31:19 +01:00
// msg.message?.content: Array<{ type: 'text', text: string }>
// msg.total_cost_usd: number (on result messages)
2026-01-18 05:17:06 +01:00
```
2026-01-18 21:37:03 +01:00
### PTY Spawn Modes
```typescript
2026-01-19 10:36:30 +01:00
// One-shot mode (JSON output for token tracking)
2026-01-19 04:45:51 +01:00
pty . spawn ( 'claude' , [ '-p' , '--dangerously-skip-permissions' , '--output-format' , 'stream-json' , prompt ], { ... })
2026-01-18 21:37:03 +01:00
2026-01-19 10:36:30 +01:00
// Interactive mode (tokens parsed from status line)
2026-01-18 21:37:03 +01:00
pty . spawn ( 'claude' , [ '--dangerously-skip-permissions' ], { ... })
```
2026-01-18 07:31:19 +01:00
### Idle Detection
2026-01-19 11:19:13 +01:00
Session detects idle by watching for prompt character (`❯ ` or `\u276f` ) and waiting 2 seconds without activity.
2026-01-18 07:31:19 +01:00
2026-01-19 10:36:30 +01:00
### Token Tracking
2026-01-18 21:37:03 +01:00
2026-01-19 10:36:30 +01:00
- **One-shot mode**: Uses `--output-format stream-json` for detailed token usage from JSON
- **Interactive mode**: Parses tokens from Claude's status line (e.g., "123.4k tokens"), estimates 60/40 input/output split
2026-01-18 21:37:03 +01:00
2026-01-19 11:19:13 +01:00
### Terminal Display Fix (Tab Switch & New Session)
2026-01-18 07:31:19 +01:00
2026-01-19 11:19:13 +01:00
When switching tabs or creating new sessions, terminal may be rendered at wrong size. Fix sequence:
2026-01-19 07:54:56 +01:00
1. Clear and reset xterm
2026-01-19 10:36:30 +01:00
2. Write terminal buffer
2026-01-19 07:54:56 +01:00
3. Send resize to update PTY dimensions
2026-01-19 10:36:30 +01:00
4. Send Ctrl+L (`\x0c` ) to trigger Claude CLI redraw
2026-01-19 07:54:56 +01:00
2026-01-19 11:19:13 +01:00
Uses `pendingCtrlL` Set to track sessions needing the fix. Waits for `session:idle` or `session:working` SSE event before sending resize + Ctrl+L.
2026-01-19 05:28:45 +01:00
### SSE Events
2026-01-18 07:31:19 +01:00
2026-01-19 05:28:45 +01:00
All events broadcast to `/api/events` with format: `{ type: string, sessionId?: string, data: any }` .
2026-01-18 07:31:19 +01:00
2026-01-19 11:19:13 +01:00
Event prefixes: `session:` , `task:` , `respawn:` , `scheduled:` , `case:` , `init` . Key events: `session:idle` , `session:working` , `session:terminal` , `session:clearTerminal` , `session:completion` .
### Frontend (app.js)
The frontend uses vanilla JS with xterm.js. Key patterns:
- **SSE handling**: `handleSSEEvent()` switch statement dispatches all event types
- **Tab management**: `switchToSession()` handles terminal buffer restore + resize
- **60fps rendering**: Server batches at 16ms intervals, client uses `requestAnimationFrame`
2026-01-19 05:28:45 +01:00
2026-01-19 07:33:33 +01:00
## Adding New Features
### New API Endpoint
2026-01-19 10:36:30 +01:00
1. Add types to `src/types.ts`
2. Add route in `src/web/server.ts` within `buildServer()`
3. Use `createErrorResponse()` for errors
2026-01-19 07:33:33 +01:00
### New SSE Event
2026-01-19 10:36:30 +01:00
1. Emit from component via `broadcast()` in server.ts
2. Handle in `src/web/public/app.js` `handleSSEEvent()` switch
2026-01-19 07:33:33 +01:00
### New Session Event
1. Add to `SessionEvents` interface in `src/session.ts`
2026-01-19 10:36:30 +01:00
2. Emit via `this.emit()`
2026-01-19 07:33:33 +01:00
3. Subscribe in `src/web/server.ts` when wiring session to SSE
2026-01-19 10:36:30 +01:00
4. Handle in frontend SSE listener
2026-01-19 07:33:33 +01:00
2026-01-19 04:55:51 +01:00
## Notes
2026-01-19 01:42:47 +01:00
2026-01-19 04:55:51 +01:00
- State persists to `~/.claudeman/state.json` and `~/.claudeman/screens.json`
2026-01-19 10:36:30 +01:00
- Cases created in `~/claudeman-cases/` by default
2026-01-19 11:19:13 +01:00
- Kill All works on restored sessions: `Session.stop()` checks screenManager directly by session ID
- Long-running sessions (12-24+ hours) supported with automatic buffer trimming (5MB terminal, 2MB text, 1000 messages max)
2026-01-19 10:36:30 +01:00
- E2E testing available via agent-browser (see `.claude/skills/e2e-test.md` )