From 0d22d196453a7e21fe8119bad7e0f1baf20f85db Mon Sep 17 00:00:00 2001 From: arkon Date: Sun, 25 Jan 2026 18:09:25 +0100 Subject: [PATCH] docs: improve CLAUDE.md structure and discoverability - Move COM shorthand to prominent position after safety warning - Add version sync note (must match package.json) - Consolidate Key Files into 4 logical categories - Clarify next available test port (3128) Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 64 ++++++++++++++++++++++----------------- package.json | 2 +- src/subagent-watcher.ts | 15 ++++++--- src/web/public/app.js | 2 ++ src/web/public/index.html | 16 ++++++++++ src/web/server.ts | 39 ++++++++++++++++++++++-- 6 files changed, 102 insertions(+), 36 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index ac7de25e..55ac3d5e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,11 +13,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co **Why this matters**: Killing your own screen terminates your session mid-work, losing context and potentially corrupting state. +## ⚡ COM Shorthand (Deployment) + +When user says "COM": 1) Increment version in BOTH `package.json` AND `CLAUDE.md`, 2) `git add && git commit && git push && npm run build && systemctl --user restart claudeman-web`. Always bump version on every COM. + ## 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. -**Version**: 0.1356 +**Version**: 0.1357 (must match `package.json`) **Tech Stack**: TypeScript (ES2022/NodeNext, strict mode), Node.js, Fastify, Server-Sent Events, node-pty @@ -39,8 +43,6 @@ npm install **CRITICAL**: `npm run dev` runs CLI help, NOT the web server. Use `npx tsx src/index.ts web` for development. -**COM Shorthand**: When user says "COM": 1) Increment version in BOTH `package.json` AND `CLAUDE.md`, 2) `git add && git commit && git push && npm run build && systemctl --user restart claudeman-web`. Always bump version on every COM. - ### Build & Clean ```bash @@ -100,7 +102,8 @@ npx vitest run -t "should create session" # By pattern | 3120 | session-cleanup.test.ts | | 3125 | ralph-integration.test.ts | | 3127 | respawn-integration.test.ts (reserved) | -| 3128+ | Next available | + +**Next available port**: 3128 Unit tests (no port needed): respawn-controller, ralph-tracker, pty-interactive, task-queue, task, ralph-loop, session-manager, state-store, types, templates, ralph-config, spawn-detector, spawn-types, spawn-orchestrator, hooks-config, ai-idle-checker, ai-plan-checker @@ -196,35 +199,38 @@ claudeman reset # Reset all state ### Key Files +**Core Session Management:** | File | Purpose | |------|---------| | `src/session.ts` | Core PTY wrapper for Claude CLI. Modes: `runPrompt()`, `startInteractive()`, `startShell()` | -| `src/respawn-controller.ts` | State machine for autonomous session cycling | -| `src/ai-idle-checker.ts` | Spawns fresh Claude session to analyze terminal output for IDLE/WORKING verdict | -| `src/ai-plan-checker.ts` | Spawns fresh Claude session to detect plan mode approval prompts for auto-accept | | `src/screen-manager.ts` | GNU screen persistence, ghost discovery, 4-strategy kill | -| `src/ralph-tracker.ts` | Detects `PHRASE`, todos, loop status in output | -| `src/ralph-config.ts` | Parses `.claude/ralph-loop.local.md` and CLAUDE.md for Ralph config | -| `src/task-tracker.ts` | Parses background task output (agent IDs, status) from Claude CLI | -| `src/session-manager.ts` | Manages session lifecycle, task assignment, and cleanup | +| `src/session-manager.ts` | Session lifecycle, task assignment, cleanup | | `src/state-store.ts` | JSON persistence to `~/.claudeman/` with debounced writes | +| `src/types.ts` | All TypeScript interfaces | + +**Autonomous Features:** +| File | Purpose | +|------|---------| +| `src/respawn-controller.ts` | State machine for autonomous session cycling | +| `src/ai-idle-checker.ts` | Spawns Claude to analyze terminal output for IDLE/WORKING verdict | +| `src/ai-plan-checker.ts` | Spawns Claude to detect plan mode prompts for auto-accept | +| `src/ralph-tracker.ts` | Detects `PHRASE`, todos, loop status | +| `src/ralph-config.ts` | Parses `.claude/ralph-loop.local.md` and CLAUDE.md for Ralph config | + +**Spawn Protocol (Autonomous Agents):** +| File | Purpose | +|------|---------| +| `src/spawn-orchestrator.ts` | Full agent lifecycle: spawn, monitor, budget, queue, cleanup | +| `src/mcp-server.ts` | MCP server binary exposing spawn tools to Claude Code | +| `src/subagent-watcher.ts` | Monitors Claude Code background agents in `~/.claude/projects/*/subagents/*.jsonl` | + +**Web & TUI:** +| File | Purpose | +|------|---------| | `src/web/server.ts` | Fastify REST API + SSE at `/api/events` | | `src/web/public/app.js` | Frontend: SSE handling, xterm.js, tab management | -| `src/tui/App.tsx` | TUI main component: tabs, terminal viewport, status bar (Ink/React) | -| `src/tui/components/*.tsx` | TUI components: StartScreen, TabBar, TerminalView, StatusBar, RalphPanel, HelpOverlay | -| `src/tui/hooks/useSessionManager.ts` | TUI session state, screen polling, input handling | -| `src/hooks-config.ts` | Generates .claude/settings.local.json with Claude Code hooks for desktop notifications | -| `src/types.ts` | All TypeScript interfaces | -| `src/templates/claude-md.ts` | CLAUDE.md template generation with placeholder support | -| `src/templates/case-template.md` | Default CLAUDE.md template for new cases (with placeholders) | -| `src/spawn-types.ts` | Types, YAML parser, factory functions for spawn1337 protocol | -| `src/spawn-detector.ts` | Detects `` tags in terminal output (legacy, replaced by MCP) | -| `src/spawn-orchestrator.ts` | Full agent lifecycle: spawn, monitor, budget, queue, cleanup | -| `src/spawn-claude-md.ts` | Generates CLAUDE.md for spawned agent sessions | -| `src/mcp-server.ts` | MCP server binary (`claudeman-mcp`) exposing spawn tools to Claude Code | -| `src/subagent-watcher.ts` | Monitors Claude Code background agents in `~/.claude/projects/*/subagents/*.jsonl` | -| `src/tui/DirectAttach.ts` | Full-screen console attach with tab switching between sessions | -| `scripts/claudeman-web.service` | Systemd user service for `claudeman web --https` (Restart=always) | +| `src/tui/App.tsx` | TUI main component (Ink/React) | +| `src/tui/DirectAttach.ts` | Full-screen console attach with tab switching | ### Data Flow @@ -261,7 +267,9 @@ Monitors Claude Code's internal background agents (the `Task` tool) in real-time **Status lifecycle**: `active` → `idle` (30s no activity) → `completed` (process exited or file stale) -Implementation: `src/subagent-watcher.ts` - singleton `subagentWatcher` started on server boot. +**Settings**: Can be disabled via App Settings → Display → "Enable Subagent Tracking" (default: enabled). Setting is stored in `~/.claudeman/settings.json` as `subagentTrackingEnabled`. + +Implementation: `src/subagent-watcher.ts` - singleton `subagentWatcher` started on server boot (if enabled). ### Session Modes @@ -532,7 +540,7 @@ All routes defined in `server.ts:buildServer()`. Key endpoint groups: | `~/.claudeman/state.json` | Full session state (all settings, tokens, respawn config, Ralph state), tasks, app config | | `~/.claudeman/state-inner.json` | Ralph loop/todo state per session (separate to reduce writes) | | `~/.claudeman/screens.json` | Screen session metadata (for recovery after restart) | -| `~/.claudeman/settings.json` | User preferences (lastUsedCase, custom template path) | +| `~/.claudeman/settings.json` | User preferences (lastUsedCase, custom template path, subagentTrackingEnabled) | | `~/.claudeman/certs/` | Self-signed TLS certificates for `--https` mode | **Recovery**: On restart, sessions restored from `state.json` (primary) with `screens.json` as fallback. All settings re-applied to live sessions. Cases created in `~/claudeman-cases/` by default. diff --git a/package.json b/package.json index 861b1c9c..626c2feb 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claudeman", - "version": "0.1356", + "version": "0.1357", "description": "The missing control plane for Claude Code - run 20 autonomous agents with real-time monitoring and session persistence", "type": "module", "main": "dist/index.js", diff --git a/src/subagent-watcher.ts b/src/subagent-watcher.ts index ea6f4d69..9a5fd392 100644 --- a/src/subagent-watcher.ts +++ b/src/subagent-watcher.ts @@ -102,7 +102,7 @@ export class SubagentWatcher extends EventEmitter { private idleTimers = new Map(); private pollInterval: NodeJS.Timeout | null = null; private livenessInterval: NodeJS.Timeout | null = null; - private isRunning = false; + private _isRunning = false; private knownSubagentDirs = new Set(); constructor() { @@ -115,8 +115,8 @@ export class SubagentWatcher extends EventEmitter { * Start watching for subagent activity */ start(): void { - if (this.isRunning) return; - this.isRunning = true; + if (this._isRunning) return; + this._isRunning = true; // Initial scan this.scanForSubagents(); @@ -177,11 +177,18 @@ export class SubagentWatcher extends EventEmitter { return false; } + /** + * Check if the watcher is currently running + */ + isRunning(): boolean { + return this._isRunning; + } + /** * Stop watching */ stop(): void { - this.isRunning = false; + this._isRunning = false; if (this.pollInterval) { clearInterval(this.pollInterval); diff --git a/src/web/public/app.js b/src/web/public/app.js index 6118373b..8617acd1 100644 --- a/src/web/public/app.js +++ b/src/web/public/app.js @@ -2964,6 +2964,7 @@ class ClaudemanApp { document.getElementById('appSettingsShowSystemStats').checked = settings.showSystemStats ?? true; document.getElementById('appSettingsShowTokenCount').checked = settings.showTokenCount ?? true; document.getElementById('appSettingsShowMonitor').checked = settings.showMonitor ?? true; + document.getElementById('appSettingsSubagentTracking').checked = settings.subagentTrackingEnabled ?? true; // Claude CLI settings const claudeModeSelect = document.getElementById('appSettingsClaudeMode'); const allowedToolsRow = document.getElementById('allowedToolsRow'); @@ -3023,6 +3024,7 @@ class ClaudemanApp { showSystemStats: document.getElementById('appSettingsShowSystemStats').checked, showTokenCount: document.getElementById('appSettingsShowTokenCount').checked, showMonitor: document.getElementById('appSettingsShowMonitor').checked, + subagentTrackingEnabled: document.getElementById('appSettingsSubagentTracking').checked, // Claude CLI settings claudeMode: document.getElementById('appSettingsClaudeMode').value, allowedTools: document.getElementById('appSettingsAllowedTools').value.trim(), diff --git a/src/web/public/index.html b/src/web/public/index.html index 6be125d4..5bd3156a 100644 --- a/src/web/public/index.html +++ b/src/web/public/index.html @@ -536,6 +536,22 @@ Show Monitor panel at bottom right +
+ + + Monitor Claude Code background agents in real-time +
+
+ + + Show the Subagents panel (independent from Monitor) +