automaker/CLAUDE.md

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 built as an npm workspace monorepo. It provides a Kanban-based workflow where AI agents (powered by Claude Agent SDK) implement features in isolated git worktrees.

Common Commands

# Development
npm run dev                 # Interactive launcher (choose web or electron)
npm run dev:web             # Web browser mode (localhost:3007)
npm run dev:electron        # Desktop app mode
npm run dev:electron:debug  # Desktop with DevTools open

# Building
npm run build               # Build web application
npm run build:packages      # Build all shared packages (required before other builds)
npm run build:electron      # Build desktop app for current platform
npm run build:server        # Build 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:packages       # All shared package tests
npm run test:all            # All tests (packages + server)

# Single test file
npm run test:server -- tests/unit/specific.test.ts

# Linting and formatting
npm run lint                # ESLint
npm run format              # Prettier write
npm run format:check        # Prettier check

Architecture

Monorepo Structure

automaker/
├── apps/
│   ├── ui/           # React + Vite + Electron frontend (port 3007)
│   └── server/       # Express + WebSocket backend (port 3008)
└── libs/             # Shared packages (@automaker/*)
    ├── types/        # Core TypeScript definitions (no dependencies)
    ├── utils/        # Logging, errors, image processing, context loading
    ├── prompts/      # AI prompt templates
    ├── platform/     # Path management, security, process spawning
    ├── model-resolver/    # Claude model alias resolution
    ├── dependency-resolver/  # Feature dependency ordering
    └── git-utils/    # Git operations & worktree management

Package Dependency Chain

Packages can only depend on packages above them:

@automaker/types (no dependencies)
    ↓
@automaker/utils, @automaker/prompts, @automaker/platform, @automaker/model-resolver, @automaker/dependency-resolver
    ↓
@automaker/git-utils
    ↓
@automaker/server, @automaker/ui

Key Technologies

• Frontend: React 19, Vite 7, Electron 39, TanStack Router, Zustand 5, Tailwind CSS 4
• Backend: Express 5, WebSocket (ws), Claude Agent SDK, node-pty
• Testing: Playwright (E2E), Vitest (unit)

Server Architecture

The server (apps/server/src/) follows a modular pattern:

• routes/ - Express route handlers organized by feature (agent, features, auto-mode, worktree, etc.)
• services/ - Business logic (AgentService, AutoModeService, FeatureLoader, TerminalService)
• providers/ - AI provider abstraction (currently Claude via Claude Agent SDK)
• lib/ - Utilities (events, auth, worktree metadata)

Frontend Architecture

The UI (apps/ui/src/) uses:

• routes/ - TanStack Router file-based routing
• components/views/ - Main view components (board, settings, terminal, etc.)
• store/ - Zustand stores with persistence (app-store.ts, setup-store.ts)
• hooks/ - Custom React hooks
• lib/ - Utilities and API client

Data Storage

Per-Project Data (.automaker/)

.automaker/
├── features/              # Feature JSON files and images
│   └── {featureId}/
│       ├── feature.json
│       ├── agent-output.md
│       └── images/
├── context/               # Context files for AI agents (CLAUDE.md, etc.)
├── settings.json          # Project-specific settings
├── spec.md               # Project specification
└── analysis.json         # Project structure analysis

Global Data (DATA_DIR, default ./data)

data/
├── settings.json          # Global settings, profiles, shortcuts
├── credentials.json       # API keys
├── sessions-metadata.json # Chat session metadata
└── agent-sessions/        # Conversation histories

Import Conventions

Always import from shared packages, never from old paths:

// ✅ Correct
import type { Feature, ExecuteOptions } from '@automaker/types';
import { createLogger, classifyError } from '@automaker/utils';
import { getEnhancementPrompt } from '@automaker/prompts';
import { getFeatureDir, ensureAutomakerDir } from '@automaker/platform';
import { resolveModelString } from '@automaker/model-resolver';
import { resolveDependencies } from '@automaker/dependency-resolver';
import { getGitRepositoryDiffs } from '@automaker/git-utils';

// ❌ Never import from old paths
import { Feature } from '../services/feature-loader'; // Wrong
import { createLogger } from '../lib/logger'; // Wrong

Key Patterns

Event-Driven Architecture

All server operations emit events that stream to the frontend via WebSocket. Events are created using createEventEmitter() from lib/events.ts.

Git Worktree Isolation

Each feature executes in an isolated git worktree, created via @automaker/git-utils. This protects the main branch during AI agent execution.

Context Files

Project-specific rules are stored in .automaker/context/ and automatically loaded into agent prompts via loadContextFiles() from @automaker/utils.

Model Resolution

Use resolveModelString() from @automaker/model-resolver to convert model aliases:

• haiku → claude-haiku-4-5
• sonnet → claude-sonnet-4-20250514
• opus → claude-opus-4-5-20251101

Environment Variables

• ANTHROPIC_API_KEY - Anthropic API key (or use Claude Code CLI auth)
• PORT - Server port (default: 3008)
• DATA_DIR - Data storage directory (default: ./data)
• ALLOWED_ROOT_DIRECTORY - Restrict file operations to specific directory
• AUTOMAKER_MOCK_AGENT=true - Enable mock agent mode for CI testing
• ENABLE_DEBUG_PANEL=true - Enable debug panel in non-development builds

Debug System (Development Only)

The debug system provides real-time monitoring of server performance. Toggle with Cmd/Ctrl+Shift+D.

Debug Services (apps/server/src/services/)

• PerformanceMonitorService - Collects memory/CPU metrics, detects leaks via linear regression
• ProcessRegistryService - Tracks spawned agents, terminals, CLIs with lifecycle events

Debug API (apps/server/src/routes/debug/)

• GET /api/debug/metrics - Current metrics snapshot
• POST /api/debug/metrics/start - Start collection with optional config
• POST /api/debug/metrics/stop - Stop collection
• GET /api/debug/processes - List tracked processes with filters

Debug Types (libs/types/src/debug.ts)

All debug types are exported from @automaker/types:

import type {
  DebugMetricsSnapshot,
  TrackedProcess,
  MemoryTrend,
  ProcessSummary,
} from '@automaker/types';
import { formatBytes, formatDuration } from '@automaker/types';

UI Components (apps/ui/src/components/debug/)

• DebugPanel - Main draggable container with tabs
• MemoryMonitor - Heap usage charts and leak indicators
• CPUMonitor - CPU gauge and event loop lag display
• ProcessKanban - Visual board of tracked processes
• RenderTracker - React component render statistics

See docs/server/debug-api.md for full API documentation.