DOCSEARCHbyAlgolia
Submit Docs

automaker

repository·main·Indexed 25 days ago

https://github.com/automaker-org/automaker

An autonomous AI development studio for orchestrating AI agents to build software features via a Kanban-style interface. It utilizes the Claude Agent SDK and provides a suite of libraries including @automaker/dependency-resolver for feature ordering using Kahn's algorithm, @automaker/git-utils for repository management and diff generation, @automaker/model-resolver for Claude model mapping, @automaker/platform for secure file system operations and subprocess handling, and @automaker/prompts for AI text enhancement templates.

Tokens
69.3K
Snippets
163
Records
388
Agent score
84%

What's inside automaker

  1. Overview of Custom Terminal Configurations

    main

    Automaker provides an opt-in feature to implement custom shell configuration files (.bashrc, .zshrc) that automatically synchronize with Automaker's 40 themes. This ensures terminal prompt colors match the application theme.

    Key behavior:

    • Configurations are created in the .automaker/terminal/ directory.
    • Existing user RC files are not modified.
    • The feature is opt-in via settings.

  2. Overview of Automaker

    main
    Automaker is an autonomous AI development studio designed for agentic coding. Instead of manual coding, users describe features on a Kanban board, and AI agents (powered by Claude Agent SDK) automatically implement them. The platform provides a complete workflow including real-time streaming, git worktree isolation, plan approval, and multi-agent task execution via a desktop application or web browser.

  3. Follow package dependency rules

    main

    To prevent circular dependencies, follow the established dependency chain. Packages can only depend on packages positioned above them in the hierarchy.

    Dependency Chain:

    1. @automaker/types (Base - no dependencies)
    2. @automaker/utils, @automaker/prompts, @automaker/platform, @automaker/model-resolver, @automaker/dependency-resolver
    3. @automaker/git-utils
    4. @automaker/server, @automaker/ui

  4. Understand the Settings API-First Migration

    main

    Automaker has migrated from localStorage-based persistence to an API-first approach. The server's settings.json is now the single source of truth. This ensures settings remain consistent between Electron and web modes, preventing settings drift.

    Key Changes:

    • Settings are fetched from the server API on app startup.
    • Settings are synced back to the server API when changed (with a 1000ms debounce).
    • localStorage is no longer used for persistent settings (Zustand persist middleware has been removed).

  5. Understand the Automaker Architecture

    main

    Automaker is an npm workspace monorepo consisting of two main applications and seven shared libraries. It uses an event-driven architecture where server operations stream to the frontend via WebSockets. The system is designed around a provider pattern for AI (currently Claude) and uses file-based storage instead of a database.

    Core Applications:

    • apps/ui: React + Vite + Electron frontend.
    • apps/server: Express + WebSocket backend.

    Shared Libraries (libs/):

    • @automaker/types: Core TypeScript definitions.
    • @automaker/utils: Logging, errors, and utilities.
    • @automaker/prompts: AI prompt templates.
    • @automaker/platform: Path management and security.
    • @automaker/model-resolver: Claude model aliasing.
    • @automaker/dependency-resolver: Feature dependency ordering.
    • @automaker/git-utils: Git operations and worktree management.

  6. Improve code reusability with generics and composition

    main

    Write code that can be used in multiple contexts. Prefer generic, parameterized functions over specific ones, and use composition over inheritance. Design functions to be pure (no side effects) where possible and use dependency injection to make components reusable.

    // Good: Using generics for a reusable calculation function
function calculateTotal<T extends { price: number }>(items: T[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}

function calculateUserTotal(userId: string) {
  const user = getUser(userId);
  return calculateTotal(user.items);
}

  7. Quick Start: Converting PRD to Automaker Features

    main

    To begin using Automaker to execute features derived from a Product Requirements Document (PRD), follow these steps:

    1. Place your PRD file in the project (e.g., PRD.md or .automaker/context/PRD.md).
    2. Create the .automaker/features/ directory.
    3. Generate feature.json files for each feature phase using the Automaker feature schema.
    4. Organize features into directories where the directory name matches the feature id.
    5. Run features in Automaker sequentially or in parallel based on their defined dependencies.
    .automaker/
└── features/
    ├── phase-1-foundation/
    │   └── feature.json
    ├── phase-2-backend/
    │   └── feature.json
    ├── phase-3-api/
    │   └── feature.json
    └── phase-4-frontend/
        └── feature.json

  8. Run Automaker in Development Mode

    main

    You can start Automaker in development mode using npm run dev. This will prompt you to choose a run mode. Alternatively, you can specify a mode directly using the following commands:

    Electron Desktop App

    • Standard mode: npm run dev:electron
    • With DevTools open: npm run dev:electron:debug
    • For WSL (Windows Subsystem for Linux): npm run dev:electron:wsl
    • For WSL with GPU acceleration: npm run dev:electron:wsl:gpu

    Web Browser Mode

    npm run dev
# or
npm run dev:electron
npm run dev:web

  9. Migrate existing routes to the Route Organization Pattern

    main

    To improve maintainability and follow the recommended architecture, migrate monolithic route files into a structured module. Follow these steps:

    1. Analyze current structure: Identify all endpoints, shared state/utilities, and large functions (>150 lines).
    2. Create directory structure: Use mkdir -p routes/{module-name}/routes.
    3. Extract common utilities: Move shared state and utility functions to a common.ts file.
    4. Extract business logic: Move complex logic into dedicated {function-name}.ts files.
    5. Create route handlers: Create a file for each endpoint in the routes/ subdirectory (e.g., routes/{endpoint-name}.ts). Keep these handlers thin and focused on HTTP concerns.
    6. Create index.ts: Import the handlers, register the routes, and export a router creation function.
    7. Update main routes file: Import the new module's index.ts and update registration.
    8. Test: Verify endpoints, error handling, and shared state management.
    mkdir -p routes/{module-name}/routes

  10. Workflow for the PR Comment Fix Agent

    main

    The PR Comment Fix Agent is designed to automatically review GitHub Pull Requests, analyze comments, and implement code changes to address them. The workflow follows these six steps:

    1. Fetch PR Information: Retrieve PR details and comments using the GitHub CLI.
    2. Analyze Comments: Categorize comments by type (Review, Inline, General), file path, line number, intent, and priority.
    3. Checkout PR Branch: Fetch and switch to the PR's head branch.
    4. Address Comments Systematically: For each comment, read the relevant files, understand the request, implement the fix, and verify the change.
    5. Document Changes: Reference the specific PR comments in commit messages.
    6. Commit Changes: Stage, commit, and push the fixes back to the origin.

  12. Use shared packages instead of local imports

    main

    When developing features or refactoring server code, always use the official shared packages instead of importing from internal source paths or legacy directories.

    Correct Import Patterns:

    • Use @automaker/types for Feature and ExecuteOptions types.
    • Use @automaker/utils for logging and error handling.
    • Use @automaker/prompts for prompt templates.
    • Use @automaker/platform for path operations.
    • Use @automaker/model-resolver for model resolution.
    • Use @automaker/dependency-resolver for dependency checks.
    • Use @automaker/git-utils for git operations.

    Forbidden Imports (Do NOT use):

    • lib/* paths
    • services/feature-loader (for types)
    • providers/types
    • routes/common
    • Direct imports from src/ paths (e.g., import { Feature } from '../../../src/...')
    // ✅ Correct: Import from packages
import type { Feature } from '@automaker/types';
import { createLogger } from '@automaker/utils';

// ❌ Incorrect: Don't import from src
import { Feature } from '../../../src/services/feature-loader';