mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-09-30 12:39:42 +02:00
docs: update CLAUDE.md with project documentation
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
arkon
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user