mirror of
https://github.com/leonvanzyl/autocoder.git
synced 2026-01-30 22:32:06 +00:00
143 lines
4.9 KiB
Markdown
143 lines
4.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This is an autonomous coding agent system with a React-based UI. It uses the Claude Agent SDK to build complete applications over multiple sessions using a two-agent pattern:
|
|
|
|
1. **Initializer Agent** - First session reads an app spec and creates features in a SQLite database
|
|
2. **Coding Agent** - Subsequent sessions implement features one by one, marking them as passing
|
|
|
|
## Commands
|
|
|
|
### Quick Start (Recommended)
|
|
|
|
```bash
|
|
# Windows - launches CLI menu
|
|
start.bat
|
|
|
|
# macOS/Linux
|
|
./start.sh
|
|
|
|
# Launch Web UI (serves pre-built React app)
|
|
start_ui.bat # Windows
|
|
./start_ui.sh # macOS/Linux
|
|
```
|
|
|
|
### Python Backend (Manual)
|
|
|
|
```bash
|
|
# Create and activate virtual environment
|
|
python -m venv venv
|
|
venv\Scripts\activate # Windows
|
|
source venv/bin/activate # macOS/Linux
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Run the main CLI launcher
|
|
python start.py
|
|
|
|
# Run agent directly for a specific project
|
|
python autonomous_agent_demo.py --project-dir PROJECT_NAME
|
|
```
|
|
|
|
### React UI (in ui/ directory)
|
|
|
|
```bash
|
|
cd ui
|
|
npm install
|
|
npm run dev # Development server (hot reload)
|
|
npm run build # Production build (required for start_ui.bat)
|
|
npm run lint # Run ESLint
|
|
```
|
|
|
|
**Note:** The `start_ui.bat` script serves the pre-built UI from `ui/dist/`. After making UI changes, run `npm run build` in the `ui/` directory.
|
|
|
|
## Architecture
|
|
|
|
### Core Python Modules
|
|
|
|
- `start.py` - CLI launcher with project creation/selection menu
|
|
- `autonomous_agent_demo.py` - Entry point for running the agent
|
|
- `agent.py` - Agent session loop using Claude Agent SDK
|
|
- `client.py` - ClaudeSDKClient configuration with security hooks and MCP servers
|
|
- `security.py` - Bash command allowlist validation (ALLOWED_COMMANDS whitelist)
|
|
- `prompts.py` - Prompt template loading with project-specific fallback
|
|
- `progress.py` - Progress tracking, database queries, webhook notifications
|
|
|
|
### Feature Management
|
|
|
|
Features are stored in SQLite (`features.db`) via SQLAlchemy. The agent interacts with features through an MCP server:
|
|
|
|
- `mcp_server/feature_mcp.py` - MCP server exposing feature management tools
|
|
- `api/database.py` - SQLAlchemy models (Feature table with priority, category, name, description, steps, passes)
|
|
|
|
MCP tools available to the agent:
|
|
- `feature_get_stats` - Progress statistics
|
|
- `feature_get_next` - Get highest-priority pending feature
|
|
- `feature_get_for_regression` - Random passing features for regression testing
|
|
- `feature_mark_passing` - Mark feature complete
|
|
- `feature_skip` - Move feature to end of queue
|
|
- `feature_create_bulk` - Initialize all features (used by initializer)
|
|
|
|
### React UI (ui/)
|
|
|
|
- Tech stack: React 18, TypeScript, TanStack Query, Tailwind CSS v4, Radix UI
|
|
- `src/App.tsx` - Main app with project selection, kanban board, agent controls
|
|
- `src/hooks/useWebSocket.ts` - Real-time updates via WebSocket
|
|
- `src/hooks/useProjects.ts` - React Query hooks for API calls
|
|
- `src/lib/api.ts` - REST API client
|
|
- `src/lib/types.ts` - TypeScript type definitions
|
|
|
|
### Project Structure for Generated Apps
|
|
|
|
Generated projects are stored in `generations/PROJECT_NAME/` with:
|
|
- `prompts/app_spec.txt` - Application specification (XML format)
|
|
- `prompts/initializer_prompt.md` - First session prompt
|
|
- `prompts/coding_prompt.md` - Continuation session prompt
|
|
- `features.db` - SQLite database with feature test cases
|
|
|
|
### Security Model
|
|
|
|
Defense-in-depth approach configured in `client.py`:
|
|
1. OS-level sandbox for bash commands
|
|
2. Filesystem restricted to project directory only
|
|
3. Bash commands validated against `ALLOWED_COMMANDS` in `security.py`
|
|
|
|
## Claude Code Integration
|
|
|
|
- `.claude/commands/create-spec.md` - `/create-spec` slash command for interactive spec creation
|
|
- `.claude/skills/frontend-design/SKILL.md` - Skill for distinctive UI design
|
|
- `.claude/templates/` - Prompt templates copied to new projects
|
|
|
|
## Key Patterns
|
|
|
|
### Prompt Loading Fallback Chain
|
|
|
|
1. Project-specific: `generations/{project}/prompts/{name}.md`
|
|
2. Base template: `.claude/templates/{name}.template.md`
|
|
|
|
### Agent Session Flow
|
|
|
|
1. Check if `features.db` has features (determines initializer vs coding agent)
|
|
2. Create ClaudeSDKClient with security settings
|
|
3. Send prompt and stream response
|
|
4. Auto-continue with 3-second delay between sessions
|
|
|
|
### Real-time UI Updates
|
|
|
|
The UI receives updates via WebSocket (`/ws/projects/{project_name}`):
|
|
- `progress` - Test pass counts
|
|
- `agent_status` - Running/paused/stopped/crashed
|
|
- `log` - Agent output lines (streamed from subprocess stdout)
|
|
- `feature_update` - Feature status changes
|
|
|
|
### Design System
|
|
|
|
The UI uses a **neobrutalism** design with Tailwind CSS v4:
|
|
- CSS variables defined in `ui/src/styles/globals.css` via `@theme` directive
|
|
- Custom animations: `animate-slide-in`, `animate-pulse-neo`, `animate-shimmer`
|
|
- Color tokens: `--color-neo-pending` (yellow), `--color-neo-progress` (cyan), `--color-neo-done` (green)
|