mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-10-03 14:09:42 +02:00
94 lines
2.9 KiB
Markdown
94 lines
2.9 KiB
Markdown
# 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
|
|
|
|
```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
|
|
|
|
- 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 |
|