CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Automaker is an autonomous AI development studio that orchestrates AI agents to build software. Users describe features on a Kanban board, and AI agents powered by Claude Code automatically implement them.

Architecture

This is a monorepo with npm workspaces containing two main applications:

Apps Structure

apps/app - Next.js 16 + Electron desktop application (frontend)
- React 19 with Zustand for state management
- Radix UI components with Tailwind CSS 4
- dnd-kit for drag-and-drop Kanban board
- xterm.js for integrated terminal
- Playwright for E2E testing
apps/server - Express.js backend server (TypeScript, ES modules)
- Uses @anthropic-ai/claude-agent-sdk for AI agent orchestration
- WebSocket support for real-time events and terminal communication
- node-pty for terminal sessions
- Vitest for testing

Communication

Frontend communicates with backend via HTTP API (port 3008) and WebSocket
In Electron mode, the backend server is spawned as a child process
In web mode, both run independently

Key Server Services (`apps/server/src/services/`)

AgentService - Manages Claude agent sessions and conversations
AutoModeService - Orchestrates concurrent feature implementation
FeatureLoader - Persists feature/task data to .automaker/ directory
TerminalService - Manages PTY terminal sessions

Key Frontend State (`apps/app/src/store/`)

app-store.ts - Main Zustand store with persisted state (projects, features, settings, themes)
Features flow: backlog → in_progress → waiting_approval → verified → completed

Development Commands

# Install dependencies
npm install

# Development (prompts for mode selection)
npm run dev

# Specific development modes
npm run dev:electron       # Desktop app with Electron
npm run dev:web            # Web browser mode (frontend + backend)
npm run dev:server         # Backend server only

# Testing
npm run test               # E2E tests (Playwright, headless)
npm run test:headed        # E2E tests with browser visible
npm run test:server        # Server unit tests (Vitest)
npm run test:server:coverage  # Server tests with coverage

# Linting
npm run lint               # ESLint on frontend

# Building
npm run build              # Build Next.js app
npm run build:electron     # Build Electron distributable

Running a Single Test

# Frontend E2E (from apps/app)
npx playwright test tests/specific-test.spec.ts

# Server unit tests (from apps/server)
npx vitest run tests/unit/specific.test.ts
npx vitest watch tests/unit/specific.test.ts  # Watch mode

Code Conventions

Never use any for type declarations - create proper interfaces or use existing types
Server uses ES modules ("type": "module") - use .js extensions in imports
Frontend components in src/components/, organized by feature in views/
UI primitives in src/components/ui/ following shadcn/ui patterns

Environment Variables

ANTHROPIC_API_KEY - Required for Claude agent functionality
PORT - Backend server port (default: 3008)
AUTOMAKER_MOCK_AGENT=true - Enable mock agent for testing without API calls

Project Data Storage

Features and project state are stored in .automaker/ directory within each project:

features.json - Kanban features/tasks
context/ - Context files for AI agents
Background images and other project-specific data

3.5 KiB Raw Blame History