From 46f97becc91cdbd1c5e2efcf21c4c80ce2efaa40 Mon Sep 17 00:00:00 2001
From: arkon <arkon.85@hotmail.com>
Date: Sun, 18 Jan 2026 05:17:06 +0100
Subject: [PATCH] docs: update CLAUDE.md with project documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 130 +++++++++++++++++++++++++++++++++---------------------
 1 file changed, 79 insertions(+), 51 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 57cbbaf0..01c6d95e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,65 +1,93 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## What This Repository Is
-
-This is a **Claude Code configuration template** containing reusable CLAUDE.md and settings files. Copy these to new projects to bootstrap Claude Code configuration.
-
-### Files to Copy
-- `CLAUDE.md` → project root (then customize the Project Overview section)
-- `.claude/settings.json` → `.claude/settings.json`
-
----
+This file provides guidance to Claude Code when working with this repository.
 
 ## Project Overview
-<!-- Customize this section when using in a real project -->
-- **Project Name**: claudeman (Claude Code config template)
-- **Description**: Reusable Claude Code configuration files
+
+- **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
+
+```bash
+# 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`
+```typescript
+// 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
+```typescript
+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
 
-### Autonomy
-Full permissions granted via `.claude/settings.json`. Act decisively - read, write, edit, execute freely.
-
-### Git Discipline
-- Commit after every meaningful change - never batch unrelated work
-- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
-- Commit message = what changed + why (not how)
-
-### Planning Mode
-**Automatically enter planning mode** when:
-- Multi-file changes (3+ files)
-- Architectural decisions
-- New feature implementation
-- Refactoring existing functionality
-
-**Skip planning mode** for: single-file fixes, typo corrections, simple config changes.
-
----
-
-## Ralph Loop (Autonomous Work)
-
-Start with `/ralph-loop`, cancel with `/cancel-ralph`.
-
-Ralph loops enable persistent autonomous work. When active, continue iterating until completion criteria are met.
-
-### Core Behaviors
-1. Work incrementally - one sub-task at a time
-2. Commit after each completion
-3. Self-correct: implement → test → fix failures → lint → fix errors → commit
-4. Only output completion phrase when ALL requirements done AND tests pass
-
-### Time-Aware Loops
-When given a minimum duration, track elapsed time and self-generate additional tasks if primary work completes early. Only output completion phrase when both tasks AND time requirements are met.
-
----
+- 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 | Improve CLAUDE.md template | CLAUDE.md | Made more concise |
+| 2026-01-18 | Initial implementation | All files | Core CLI + web interface |
+| 2026-01-18 | Add web interface | src/web/* | Fastify + SSE + responsive UI |