AppAgent CLI

AI-powered mobile app generator that turns a natural language description into a fully customized iOS or Android app using Cursor CLI or Claude Code agents and a library of production-ready templates.

How It Works

"A pet grooming appointment     ┌─────────────┐     output/pawspa-ios/
 booking app called PawSpa"  -> │  AppAgent    │ ->  (ready-to-build
                                │  CLI + Agent │      Xcode / Gradle project)
                                └─────────────┘

1. You describe the app you want in plain English
2. AppAgent picks the best template from a catalog of 14 categories + selects a design brand and shared modules
3. An AI agent (Cursor CLI or Claude Code) clones the template, integrates shared modules, and customizes everything -- app name, branding, screens, mock data, navigation, theme
4. Specialized skills verify the build compiles, validate consistency, and UI-test on a simulator
5. Every step writes a structured report to reports/ for full auditability
6. Optionally pushes the finished app to a new GitHub repo

Features

• 14 app templates -- Shop, Track, Book, Social, Finance, Chat, Learn, Health, Task, Media, Map, Dash, Family, Game -- each with 13-17 screens
• 49 shared modules -- reference implementations for auth, payments, push notifications, analytics, and more -- selected by keyword matching and adapted by the agent into each app
• 13 design brands -- Modern Minimal, Vibrant Playful, Corporate Professional, Dark Luxe, Kids Playful, Medical Clinical, and more
• Dual platform -- iOS (Swift/SwiftUI) and Android (Kotlin/Jetpack Compose), with parallel builds via -p both
• AI-driven selection -- the agent picks the best template, design brand, and shared modules for your app
• Deep customization -- renames the entire project, updates AppConfig, rewrites mock data, adjusts navigation, theme, and app icon
• Content generation -- writes all user-facing strings (onboarding, labels, CTAs, errors) with consistent voice
• Self-healing pipeline -- hooks validate output and auto-retry on failure (up to 3 times)
• Security gates -- two-layer prompt validation (regex sanitizer + AI auditor) and post-build code audit
• Live UI testing -- simulator/emulator testing via ai-tester MCP + Maestro regression tests
• Report files -- every step writes a markdown report + machine-readable summary.json
• GitHub integration -- creates a repo and pushes the finished app with one confirmation
• From-scratch mode -- generate apps from scratch using templates as architectural reference, with full creative freedom on architecture
• Quick build mode -- skeleton template + fast inline customization + smoke test, no analysis overhead
• App management -- list all previously built apps and re-launch any of them on a simulator/emulator
• Standalone UI testing -- re-run UI testing on a previously built app without rebuilding from scratch
• Deep testing pipeline -- code-analysis test planning + screenshot/accessibility-driven exploratory testing + structured test execution + detailed bug reports
• Standalone bug fixing -- auto-fix bugs from a previous deep-test run without re-running the full test suite
• Website cloning -- crawl a live website using ai-tester MCP, extract brand/content/structure, and generate a native mobile app that mirrors it

Installation

# Run directly with npx (no install required)
npx @shaykec/app-agent

# Or install globally
npm install -g @shaykec/app-agent
app-agent

Prerequisites

• Node.js 18+
• Agent engine (at least one):
  • Cursor IDE with CLI access (cursor command in PATH) -- default engine
  • Claude Code CLI (claude command in PATH) -- alternative engine, install via curl -fsSL https://claude.ai/install.sh | bash
• Xcode (for iOS builds) and/or Android Studio (for Android builds)
• GitHub CLI (gh) -- optional, for auto-pushing to GitHub

Quick Start

Run with npx (no install required)

# Interactive mode -- prompts for description, platform, engine, model
npx @shaykec/app-agent

# Generate an iOS app directly
npx @shaykec/app-agent -d "A pet grooming booking app called PawSpa"

# Specify platform and engine
npx @shaykec/app-agent -d "A coffee shop app called BrewBar" --platform android --engine claude

When running via npx, AppAgent scaffolds a temporary workspace in your current directory (symlinks for templates, skills, and config files), runs the agent, and cleans up after. The generated app is written to output/ in your current directory.

Install globally

npm install -g @shaykec/app-agent

# Then run from anywhere
app-agent -d "A pet grooming booking app called PawSpa"
app-agent  # interactive mode

Run from source (development)

git clone https://github.com/shaykec/AppAgent.git
cd AppAgent
npm install

# Run in development mode
npm run dev

# Or build and run
npm run build
npm start

The CLI will prompt you for:

1. App description -- describe what your app does

2. Platform -- iOS (default) or Android

3. Agent engine -- Cursor CLI (default) or Claude Code

4. AI model -- which LLM to use (default: sonnet-4.5)

5. Build mode -- Template (default), Quick (fast skeleton-based), or From Scratch

Then it launches the selected agent engine, which takes 3-30 minutes depending on mode.

Non-Interactive (CI/scripting)

# Build with Cursor CLI (default engine, default platform ios)
npx @shaykec/app-agent -d "A pet grooming booking app called PawSpa"

# Explicit platform and engine
npx @shaykec/app-agent -d "A pet grooming booking app called PawSpa" --platform android --engine claude

# Push the finished app to a new private GitHub repo
npx @shaykec/app-agent -d "A pet grooming booking app called PawSpa" --push

# Push with a custom repo name
npx @shaykec/app-agent -d "A pet grooming booking app called PawSpa" --push --repo-name pawspa-ios

# Build both iOS and Android in parallel
npx @shaykec/app-agent -d "A social media app called Chirper" -p both --push

# Or using npm start from source
npm start -- -d "A pet grooming booking app called PawSpa"

| Flag | Description | |------|-------------| | -d, --description | App description (required for build) | | -p, --platform | ios (default), android, or both (parallel dual-platform build -- all modes except update) | | -e, --engine | Agent engine: cursor (default) or claude | | --model | AI model to use (default: sonnet-4.5) | | --push | Create a private GitHub repo and push the generated app | | --repo-name | Custom repository name (default: derived from app directory name) | | -l, --list | List all previously built apps in output/ | | -r, --run <name> | Launch a built app on a simulator/emulator by directory name | | -t, --test <name> | Run UI testing on a previously built app (interactive testing + Maestro) | | -s, --scratch | Build from scratch using templates as reference instead of cloning (slower, more flexible) | | -q, --quick | Quick build -- skeleton template, fast inline customization, smoke test only | | -u, --update <source> | Update an existing app from a GitHub URL, local path, or app name. Creates a branch and PR. | | --url <website-url> | Clone a website into a native mobile app (web-clone mode). Combine with -d to focus on specific sections. | | --deep-test <name> | Deep test: code analysis, exploratory + structured testing, bug report | | --deep-test <name> --fix | Deep test + auto-fix discovered bugs | | --fix <name> | Fix bugs from a previous deep-test bug report |

Defaults can also be set via environment variables: APPAGENT_ENGINE=cursor or APPAGENT_PLATFORM=android.

Environment Variables

| Variable | Description | |----------|-------------| | APPAGENT_ENGINE | Default engine (claude or cursor) | | APPAGENT_PLATFORM | Default platform (ios or android; both only via CLI flag) | | CLAUDE_CODE_PATH | Custom path to the claude binary | | CURSOR_CLI_PATH | Custom path to the cursor binary | | AI_TESTER_PATH | Path to the ai-tester installation (for UI testing) | | APPAGENT_MCP_CONFIG | Custom path to .mcp.json for Claude Code |

Usage Example

$ npm run dev

◇  Describe the app you want to build:
│  A vintage vinyl record shop called VinylVault where collectors can browse
│  rare records, check prices, and place orders for delivery

◇  Which platform?
│  iOS (Swift / SwiftUI)

◇  Which agent engine?
│  Cursor CLI

◇  Which AI model?
│  Claude 4.5 Sonnet

◇  Launching Cursor CLI agent...
│
●  [0s]   Model: claude-sonnet-4-5-20250929
●  [3s]   SUBAGENT dispatched: Select best iOS template
●  [3s]   SUBAGENT dispatched: Select best design brand
●  [10s]  Report: 02-catalog-analysis.md
●  [11s]  SHELL: cp -r templates/ios/ShopTemplate/ output/vinylvault-ios/
●  [30s]  Report: 05-content-brief.md
●  [60s]  Progress: 48 tool calls, 15 writes, 28 reads
●  [75s]  SUBAGENT dispatched: Customize iOS features
●  [120s] Progress: 95 tool calls, 38 writes, 52 reads
●  [140s] SUBAGENT dispatched: Build VinylVault iOS app
●  [155s] SHELL: xcodebuild -project VinylVault.xcodeproj -scheme VinylVault...
●  [180s] SUBAGENT dispatched: Security audit of generated code
●  [180s] SUBAGENT dispatched: Validate output completeness
│
┌ Agent Summary ────────────────────────────────┐
│ Completed in 12m 34s                          │
│   Tool calls: 230                             │
│   Files written: 42 | Files read: 128         │
│   Subagents: 6 (template, design, customize,  │
│     build, security, validate)                 │
│   Shell commands: 18                           │
└───────────────────────────────────────────────┘

◇  Push to GitHub? (Y/n)
│  Y

◇  Done! Your app is at: https://github.com/you/vinylvault-ios

Managing Built Apps

All generated apps are preserved in output/. You can list them and re-launch any of them on a simulator without rebuilding.

List all apps

npm start -- --list

Example output:

  Directory              App Name           Platform   Template           Build        Status
  ─────────              ────────           ────────   ────────           ─────        ──────
  vinylvault-ios         VinylVault         ios        ShopTemplate       ✓ SUCCESS    ✓ PASS (runnable)
  pawspa-android         PawSpa             android    BookTemplate       ✓ SUCCESS    ✓ PASS (runnable)
  taskly-ios             Taskly             ios        TrackTemplate      — —          … in-progress

Run a previously built app

# Launch on iOS Simulator
npm start -- --run vinylvault-ios

# Launch on Android emulator
npm start -- --run pawspa-android

The CLI reads the app's summary.json to find the platform, bundle ID, and build artifact, then uses xcrun simctl (iOS) or adb (Android) to install and launch the app on a simulator.

Test a previously built app

Run UI testing independently on an app that's already been built. This is useful when:

• The full pipeline timed out before reaching UI testing
• You want to re-test after making manual code changes
• UI testing failed and you want to retry without rebuilding from scratch
• The build artifact was cleaned and needs to be rebuilt before testing

# Run UI testing with default engine and model
npm start -- --test vinylvault-ios

# Specify engine and model
npm start -- --test vinylvault-ios --engine claude --model sonnet-4.5

# With npx
npx @shaykec/app-agent --test vinylvault-ios

The --test command reads the app's summary.json and customization-manifest.md to understand the app context, then launches an AI agent focused exclusively on:

1. Booting simulators and installing the app
2. Interactive testing of every screen and interactive element
3. Fixing any bugs found (with rebuild if needed, max 3 cycles)
4. Generating Maestro regression tests
5. Running all Maestro tests until they pass

If the build artifact has been cleaned (e.g., DerivedData was deleted), the agent will automatically rebuild the app before testing.

Deep test a previously built app

The --deep-test command runs a comprehensive 4-phase testing pipeline that goes far beyond the standard --test command:

1. Phase 1: Test Plan Generation (offline) -- analyzes source code (Views, ViewModels, AppConfig, MockDataProvider) to build a structured test matrix with per-screen checklists, edge cases, and regression checks
2. Phase 2: Exploratory Testing -- an AI tester explores the app using only screenshots and the accessibility tree (does NOT read source code), finding visual bugs, accessibility issues, UX problems, and template leftovers
3. Phase 3: Structured Testing -- follows the test plan from Phase 1, systematically verifying each test case
4. Phase 4: Auto-Fix (optional) -- reads the bug report and fixes each bug, rebuilds, and verifies

Phases 2 and 3 run in parallel on separate simulators -- the exploratory tester discovers issues code analysis can't predict, while the structured tester verifies known requirements.

# Deep test only (generates test plan + bug report)
npm start -- --deep-test vinylvault-ios

# Deep test + auto-fix discovered bugs
npm start -- --deep-test vinylvault-ios --fix

# With npx
npx @shaykec/app-agent --deep-test vinylvault-ios
npx @shaykec/app-agent --deep-test vinylvault-ios --fix

# Specify engine and model
npx @shaykec/app-agent --deep-test vinylvault-ios --engine claude --model sonnet-4.5

Reports generated:

• reports/10-test-plan.md -- structured test matrix with per-screen checklists
• reports/11-bug-report.md -- merged bug report from exploratory + structured testing
• reports/12-fix-report.md -- fix details with root causes and verification results (only with --fix)

How it differs from --test:

• Generates a test plan before testing (visibility into what will be tested)
• Adds exploratory testing driven by screenshots + accessibility tree
• Produces a structured bug report with severity classifications (P0-P3)
• Supports standalone fix mode

Fix bugs from a deep test

The --fix command is a standalone mode that reads an existing bug report from a previous --deep-test run and fixes the documented bugs without re-running the full test suite.

# Fix bugs from a previous deep-test
npm start -- --fix vinylvault-ios

# With npx
npx @shaykec/app-agent --fix vinylvault-ios

The agent reads reports/11-bug-report.md, prioritizes bugs (P0 Critical → P3 Low), applies minimal fixes, rebuilds, and verifies each fix on a simulator. The fix report is written to reports/12-fix-report.md.

Build from scratch

By default, AppAgent clones a template and customizes it. The --scratch flag enables a from-scratch mode where the agent reads templates as architectural reference and writes all code itself. This is useful when:

• Your app is a hybrid of multiple categories (e.g., "a social fitness tracker with marketplace")
• Your app doesn't fit neatly into any single template category
• You want cleaner output without any template artifacts
• You need full architectural freedom (custom screen count, navigation, directory layout)

# From scratch with default engine and model
npm start -- -d "A social fitness tracker with marketplace" --scratch

# From scratch with specific platform
npm start -- -d "A social fitness tracker with marketplace" --scratch --platform android

# With npx
npx @shaykec/app-agent -d "A social fitness tracker with marketplace" --scratch

The from-scratch workflow:

1. Selects 1-3 reference templates and reads them for architectural patterns (MVVM, navigation, theming)
2. Plans the app architecture and content, accounting for which features shared modules provide
3. Scaffolds a new Xcode/Gradle project from scratch
4. Integrates shared modules (before writing custom code, so the agent builds on module APIs)
5. Writes all custom code -- screens, viewmodels, models, mock data, theme
6. Builds, audits, and UI-tests the app (same as template mode)

Note: From-scratch mode takes 2-3x longer than template mode and uses more tokens. Use template mode (the default) when your app fits one of the 14 template categories.

Quick build

The --quick flag (or -q) enables a fast-track mode that skips template selection, design brand matching, shared module integration, and the full planning pipeline. Instead, the orchestrator pre-clones a domain-agnostic Skeleton template before the agent starts, and the agent focuses purely on filling in domain-specific content.

# Quick build (non-interactive)
npx @shaykec/app-agent -q -d "A pet grooming booking app called PawSpa"

# Quick build for Android
npx @shaykec/app-agent --quick -d "Coffee shop ordering app" --platform android

# From source
npm start -- -q -d "A pet grooming booking app called PawSpa"

The quick build workflow:

1. Orchestrator clones templates/{platform}/Skeleton/ into output/{app-name}/ and generates the Xcode project (iOS)
2. Agent fills AppConfig CUSTOMIZE markers with domain values
3. Agent rewrites MockDataProvider with realistic domain data
4. Agent customizes screen Views and ViewModels with domain content
5. Agent adjusts theme colors if the domain implies them
6. Agent builds the app (using the build-tester skill, max 3 rebuild cycles)
7. Agent boots one simulator, installs the app, and smoke tests each tab

What's skipped vs. template mode: no template/brand/module selection, no customization manifest, no parallel subagents, no security audit, no output validation, no Maestro tests. This makes quick builds significantly faster -- typically 3-5 minutes vs. 15-30 minutes for template mode.

The Skeleton template provides:

• 4 tabs (Home, Explore, Favorites, Profile) with working navigation
• 6 screens (Home list, Explore search, Detail, Favorites, Profile, Create form)
• MVVM architecture already wired (Views + ViewModels + Models + MockDataProvider)
• Theme system with centralized colors, typography, spacing
• Accessibility identifiers on all interactive elements
• Compiles out of the box -- the agent starts with a working app

Dual-platform builds (-p both)

You can build both iOS and Android simultaneously by passing -p both. The orchestrator runs two AI agents in parallel -- one for each platform -- and produces a monorepo structure:

# Quick mode (fastest)
npx @shaykec/app-agent -q -d "A Twitter clone called Chirper" -p both

# Template mode
npx @shaykec/app-agent -d "A recipe sharing app called Yumbook" -p both

# From-scratch mode
npx @shaykec/app-agent -s -d "A social fitness tracker" -p both

# With GitHub push
npx @shaykec/app-agent -d "A Twitter clone called Chirper" -p both --push

This creates a monorepo structure:

output/chirper/
├── ios/          # Full iOS project (Swift/SwiftUI)
│   ├── Chirper.xcodeproj
│   ├── Chirper/
│   └── ...
└── android/      # Full Android project (Kotlin/Compose)
    ├── app/
    ├── build.gradle.kts
    └── ...

Two independent agents run concurrently -- one customizes the iOS project, the other customizes the Android project. Each agent independently selects templates/brands, fills in domain content, builds, and tests. The orchestrator waits for both to finish, validates each platform, and optionally pushes the combined monorepo to GitHub as a single repository. Logs from each agent are prefixed with [ios] / [android] for clarity.

Note: -p both is supported in all build modes (template, quick, from-scratch) but not in update mode, where the platform is auto-detected from the target app.

Update an existing app

The --update flag (or -u) modifies an existing app based on a change description. It can take a GitHub URL, a local path, or an app name from output/.

# Update from a GitHub URL (clones, branches, creates PR)
npx @shaykec/app-agent --update https://github.com/user/my-app -d "add dark mode toggle to settings"

# Update an app previously built by AppAgent
npx @shaykec/app-agent --update pawspa-ios -d "add search feature to explore tab"

# Update a local project
npx @shaykec/app-agent --update ./path/to/my-app -d "fix crash on login screen"

# From source
npm start -- --update https://github.com/user/my-app -d "add push notification support"

The update workflow:

1. Orchestrator resolves the source: clones the repo (GitHub URL) or finds the local directory
2. Orchestrator auto-detects the platform (iOS/Android) from project files
3. Orchestrator creates a git branch: appagent/{slug-from-description}
4. Agent explores the codebase to understand the architecture and code patterns
5. Agent plans and implements the requested changes
6. Agent builds and smoke tests the changes
7. Orchestrator commits the changes on the branch
8. Orchestrator pushes and creates a PR (GitHub sources) or offers to push (local sources)

Two speed tiers:

• AppAgent-generated apps (detected via reports/summary.json) -- agent knows the MVVM architecture, skips codebase exploration
• Unknown repos -- agent explores the codebase first (README, directory structure, architecture patterns)

Project Structure

.
├── src/                          # Orchestrator CLI (TypeScript)
│   ├── index.ts                  # Main entry point
│   ├── cli.ts                    # Interactive user input + arg parsing
│   ├── config.ts                 # Constants, schemas, engine/model config
│   ├── workspace.ts              # Workspace scaffolding for npx execution
│   ├── engines/                  # Agent engine abstraction layer
│   │   ├── types.ts              # AgentEngine interface and shared types
│   │   ├── cursor-engine.ts      # Cursor CLI engine implementation
│   │   ├── claude-engine.ts      # Claude Code engine implementation
│   │   ├── factory.ts            # createEngine() factory
│   │   └── index.ts              # Barrel exports
│   ├── app-manager.ts            # List and run previously built apps
│   ├── prompt-builder.ts         # Builds the agent prompt
│   ├── prompt-sanitizer.ts       # Layer 1 prompt security (regex-based)
│   ├── agent-runner.ts           # Legacy Cursor CLI runner (kept for reference)
│   ├── validator.ts              # Validates generated app output + reports
│   ├── github.ts                 # GitHub repo creation, push, clone, PR
│   └── updater.ts                # Update mode: source resolution, platform detection, branching
│
├── prompts/
│   ├── agent-prompt.md           # Template-mode build prompt (default)
│   ├── scratch-agent-prompt.md   # From-scratch build prompt (used by --scratch)
│   ├── quick-agent-prompt.md     # Quick build prompt (used by --quick)
│   ├── update-agent-prompt.md    # Update mode prompt (used by --update)
│   ├── test-agent-prompt.md      # UI testing prompt template (used by --test)
│   ├── deep-test-agent-prompt.md # Deep testing prompt (used by --deep-test)
│   ├── fix-agent-prompt.md       # Bug fix prompt (used by --fix)
│   └── web-clone-agent-prompt.md # Web clone prompt (used by --url)
│
├── CLAUDE.md                     # Claude Code always-applied rules (workflow + safety)
│
├── .cursor/                      # Cursor CLI engine configuration
│   ├── skills/                   # Skills (step-by-step procedures the agent follows)
│   │   ├── prompt-validator/     # Step 0: Validate prompt for injection/malice
│   │   ├── catalog-analyzer/     # Step 0: Pick the best template + shared modules
│   │   ├── design-selector/      # Step 0: Pick the best design brand
│   │   ├── module-integrator/    # Step 4: Read module references and write adapted code
│   │   ├── app-renaming/         # Step 2: Rename app consistently
│   │   ├── customization-planner/ # Step 3: Produce customization manifest
│   │   ├── design-system/        # Step 4: Apply design tokens
│   │   ├── content-writer/       # Step 4: Generate all user-facing strings
│   │   ├── appconfig-customization/  # Step 4: Update AppConfig markers
│   │   ├── mock-data-update/     # Step 4: Rewrite mock data
│   │   ├── ios-customizer/       # Step 5: SwiftUI/Xcode customization
│   │   ├── android-customizer/   # Step 5: Compose/Gradle customization
│   │   ├── build-tester/         # Step 6: Compile and report errors
│   │   ├── code-auditor/         # Step 7: Security code audit
│   │   ├── output-validator/     # Step 7: Completeness/consistency check
│   │   ├── ui-tester/            # Steps 8-10: Simulator testing + Maestro
│   │   ├── test-planner/         # Deep-test Phase 1: Code analysis → test plan
│   │   ├── exploratory-tester/   # Deep-test Phase 2: Screenshot + a11y testing
│   │   ├── bug-fixer/            # Deep-test Phase 4: Fix bugs from report
│   │   ├── web-crawler/          # Web-clone: Crawl website with ai-tester MCP
│   │   └── web-analyzer/         # Web-clone: Map web pages to mobile screens
│   │
│   ├── agents/                   # Subagent definitions (read inline by Cursor)
│   ├── rules/                    # Agent rules (always-on guardrails)
│   ├── hooks/                    # Lifecycle hooks (shell scripts)
│   ├── hooks.json                # Hook configuration
│   └── mcp.json                  # MCP server config (ai-tester)
│
├── .claude/                      # Claude Code engine configuration
│   ├── agents/                   # Native subagents (spawned as isolated processes)
│   ├── skills/                   # Condensed skills for Claude Code engine (~30% smaller)
│   │   ├── web-crawler/          # Web-clone: Crawl website (condensed)
│   │   ├── web-analyzer/         # Web-clone: Analyze and map pages (condensed)
│   │   └── ...                   # Same skill set as .cursor/skills/
│   └── settings.json             # Hooks and permissions
│
├── designs/                      # Design brand system
│   ├── DESIGN_CATALOG.md         # Brand decision matrix
│   ├── DESIGN_PRINCIPLES.md      # Shared mobile design guidelines
│   └── brands/                   # 13 pre-built design brands
│       ├── modern-minimal.md
│       ├── vibrant-playful.md
│       ├── corporate-professional.md
│       ├── dark-luxe.md
│       ├── soft-gradient.md
│       ├── nature-organic.md
│       ├── neo-brutalist.md
│       ├── tech-dynamic.md
│       ├── kids-playful.md
│       ├── medical-clinical.md
│       ├── retro-vintage.md
│       ├── sport-athletic.md
│       └── accessible-high-contrast.md
│
├── scripts/
│   └── generate-app-icon.swift   # Generates iOS app icons from SF Symbols
│
├── templates/                    # App templates (DO NOT MODIFY)
│   ├── CATALOG.md                # Machine-readable template index
│   ├── ios/                      # 15 iOS templates (Swift/SwiftUI) + Skeleton
│   │   └── Skeleton/             # Domain-agnostic skeleton for quick build mode
│   ├── android/                  # 15 Android templates (Kotlin/Compose) + Skeleton
│   │   ├── Skeleton/             # Domain-agnostic skeleton for quick build mode
│   │   └── ICON_VECTORS.md       # Android adaptive icon vector library (~20 domains)
│   └── shared/                   # Shared modules library
│       ├── MODULES_CATALOG.md    # Module index with tiers and keywords
│       ├── MODULE_CHECKLIST.md   # Integration verification checklist
│       ├── ios/                  # 49 iOS module implementations (SwiftUI)
│       ├── android/              # 49 Android module implementations (Compose)
│       └── tests/                # Unit tests + Maestro tests for all modules
│
└── output/                       # Generated apps land here (preserved across runs, gitignored)
    └── {app-name}/
        ├── {app source files}
        ├── reports/              # Audit trail from each workflow step
        │   ├── 01-prompt-validation.md
        │   ├── 02-catalog-analysis.md
        │   ├── 03-design-brand.md
        │   ├── customization-manifest.md
        │   ├── 04-content-brief.md
        │   ├── 05-customization.md
        │   ├── 06-build.md
        │   ├── 07-security-audit.md
        │   ├── 08-validation.md
        │   ├── 09-ui-testing.md
        │   └── summary.json
        └── tests/                # Maestro regression tests
            └── *.yaml

Agent Pipeline

The agent (Cursor CLI or Claude Code) follows an 11-step workflow with 5 parallel execution groups. Each step uses a specialized skill and writes a report.

Steps marked Subagent are dispatched as isolated child processes via the Task tool (can run in parallel). Steps marked Inline are executed directly by the main agent using skills.

flowchart TD
    Start(["User App Description + Platform"]) --> Step0

    CATALOG["CATALOG.md — 14 Templates"] -.-> TS
    DESIGNCAT["DESIGN_CATALOG.md — 13 Brands"] -.-> DS
    MODULESCAT["MODULES_CATALOG.md — 49 Modules"] -.-> MS

    subgraph Step0 ["Step 0 PARALLEL — 4 Subagents"]
        PV[["prompt-validator"]]
        CA[["catalog-analyzer"]]
        DS[["design-selector"]]
    end

    Step0 -->|"Validation FAIL"| Abort(["ABORT"])
    Step0 -->|"PASS + Selections"| Clone

    Clone["Step 1 INLINE: Clone Template"] --> Rename
    Rename["Step 2 INLINE: app-renaming skill"] --> Plan
    Plan["Step 3 INLINE: customization-planner skill"] --> Manifest["customization-manifest.md"]
    Manifest --> SharedFiles

    subgraph SharedFiles ["Step 4 INLINE — 5 Sequential Skills"]
        DesignSys["design-system"]
        ContentW["content-writer"]
        AppConf["appconfig-customization"]
        MockData["mock-data-update"]
        ModInt["module-integrator"]
        DesignSys --> ContentW --> AppConf --> MockData --> ModInt
    end

    SharedFiles --> ScreenCust

    subgraph ScreenCust ["Step 5 PARALLEL — 2-3 Subagents"]
        B1[["ios/android-customizer Batch 1"]]
        B2[["ios/android-customizer Batch 2"]]
        B3[["ios/android-customizer Batch 3"]]
    end

    ScreenCust --> Build
    Build[["Step 6 SUBAGENT: build-tester"]] -->|"Build fails"| FixBuild["Fix Errors"]
    FixBuild -->|"max 3 retries"| Build
    Build -->|"Build succeeds"| PostBuild

    subgraph PostBuild ["Step 7 PARALLEL — 2 Subagents"]
        CodeAud[["code-auditor"]]
        OutVal[["output-validator"]]
    end

    PostBuild --> BootSim["Step 8: Boot 2-3 Simulators"]
    BootSim --> UITesting

    subgraph UITesting ["Steps 9-10 PARALLEL — 2-3 Subagents"]
        Interactive[["Step 9: Interactive Testing"]]
        FixBugs["Fix Bugs + Rebuild"]
        MaestroT[["Step 10: Maestro Regression Tests"]]
        Interactive -->|"Bugs found"| FixBugs
        FixBugs -->|"max 3 cycles"| Interactive
        Interactive -->|"All pass"| MaestroT
    end

    UITesting --> Screenshots["Step 11 INLINE: Screenshot Collection"]
    Screenshots --> Done(["App + Reports in output/"])

| Step | Action | Parallelism | Skill | Report | |------|--------|-------------|-------|--------| | 0 | Validate prompt + catalog analysis + select design | 3 parallel tasks | prompt-validator, catalog-analyzer, design-selector | 01-prompt-validation.md, 02-catalog-analysis.md, 03-design-brand.md | | 1 | Clone template to output/ | -- | -- | -- | | 4 | Integrate shared modules | -- | module-integrator | -- | | 2 | Rename the app | -- | app-renaming | -- | | 3 | Plan customization (produce manifest) | -- | customization-planner | customization-manifest.md | | 4 | Apply design tokens, content, AppConfig, mock data | -- | design-system, content-writer, appconfig-customization, mock-data-update | 04-content-brief.md, 05-customization.md | | 5 | Customize screens and navigation | 2-3 parallel subagents | ios-customizer / android-customizer | -- | | 6 | Build the app | -- | build-tester | 06-build.md | | 7 | Security audit + validate output | 2 parallel tasks | code-auditor, output-validator | 07-security-audit.md, 08-validation.md | | 8-9 | Interactive UI testing + fix bugs | 2-3 parallel simulators | ui-tester | 09-ui-testing.md | | 10 | Run Maestro regression tests | 2-3 parallel simulators | ui-tester | 09-ui-testing.md |

Report Files

Every skill writes a markdown report to output/{app-name}/reports/. A summary.json file provides a machine-readable rollup that the orchestrator reads after the agent finishes:

{
  "appName": "VinylVault",
  "platform": "ios",
  "template": "ShopTemplate",
  "designBrand": "DarkLuxe",
  "steps": [
    { "step": 0, "name": "prompt-validation", "result": "PASS" },
    { "step": 1, "name": "template-selection", "result": "PASS", "template": "ShopTemplate" },
    { "step": 9, "name": "build", "result": "SUCCESS", "artifactPath": "..." },
    { "step": 12, "name": "ui-testing", "result": "PASS", "maestroTests": { "total": 6, "passed": 6 } }
  ],
  "overallResult": "PASS"
}

The --deep-test pipeline generates additional reports:

| Report | Generated By | Description | |--------|-------------|-------------| | 10-test-plan.md | test-planner skill | Structured test matrix with per-screen checklists, edge cases, regression checks | | 11-bug-report.md | exploratory-tester + ui-tester | Merged bug report with severity (P0-P3) and category tags | | 12-fix-report.md | bug-fixer skill | Fix details, root causes, files modified, verification results (only with --fix) |

Template Catalog

14 production-ready templates, each available for both iOS (Swift/SwiftUI) and Android (Kotlin/Jetpack Compose):

| Template | Category | Best For | Screens | |----------|----------|----------|---------| | ShopTemplate | E-commerce | Product browsing, cart, checkout, orders, payments, wishlist | 15+ | | TrackTemplate | Habit Tracker | Daily habits, streaks, achievements, heatmap, statistics | 13 | | BookTemplate | Booking | Service discovery, calendar scheduling, appointment management | 16 | | SocialTemplate | Social Media | Feed, stories, profiles, messaging, search, notifications | 17 | | FinanceTemplate | Finance | Accounts, transactions, budgets, goals, spending insights | 15 | | ChatTemplate | Messaging | Real-time messaging, group chats, voice messages, calls | 14 | | LearnTemplate | Education | Courses, lessons, quizzes, flashcards, progress tracking | 15 | | HealthTemplate | Health/Fitness | Workouts, nutrition, health metrics, progress tracking | 15 | | TaskTemplate | Productivity | Tasks, projects, kanban, calendar view, tags | 14 | | MediaTemplate | Content/Media | Audio/video player, playlists, downloads, mini-player | 14 | | MapTemplate | Location | Map interface, place discovery, directions, favorites | 14 | | DashTemplate | Dashboard | Widget grid, charts, real-time metrics, alerts | 13 | | FamilyTemplate | Family | Member profiles, chores, shared calendar, rewards | 14 | | GameTemplate | Casual Game | Scoring, levels, achievements, leaderboard, shop | 13 |

A 15th template (ReferenceTemplate) is included as an internal integration reference for shared modules.

Shared Modules

49 reference implementation modules that the agent selects by keyword matching and adapts into each app. Each module includes screens, managers, models, string resources, unit tests, and Maestro tests. The agent reads modules from templates/shared/ and writes adapted code into the target app -- no blind copying.

| Category | Modules | |----------|---------| | Privacy & Compliance | ConsentPrivacy, AccountDeletion | | UX Infrastructure | EmptyStates, ErrorHandling, SkeletonLoading, NetworkBanner, ForceUpdate | | Monetization | Paywall, PaymentMethods | | Auth & Security | BiometricAuth, SocialLogin, TwoFactorAuth, PinLock | | Media & Input | MediaPicker, Camera, VoiceRecording, DrawingCanvas, RichTextEditor | | Communication | PushNotifications, NotificationCenter, ShareSheet | | Navigation & Discovery | DeepLinking, FiltersSortSheet, SpotlightIndexing, QRCode | | Data & Sync | CloudSync, RealTimeSyncEngine, ImportExport, DownloadManager | | Engagement | GamificationKit, ReviewsRatings, ReferralInvite, AppRatingPrompt, OnboardingCoachMarks | | Scheduling | CalendarDateRange, MultiStepWizard | | Visualization | ChartsLibrary | | Platform Features | Widgets, LiveActivities, SiriShortcuts, AppClips, WatchCompanion | | Settings & Preferences | ThemeSwitcher, LanguagePicker, WhatsNew, FeedbackSupport | | Social | ContentModeration, AnalyticsAbstraction |

Design Brands

13 pre-built design brands, each with a complete color palette, typography scale, spacing tokens, component styles, and icon guidance:

| Brand | Tone | Best For | |-------|------|----------| | Modern Minimal | Clean, spacious | Productivity, utilities, tools, SaaS | | Vibrant Playful | Colorful, energetic | Fun, social, entertainment | | Corporate Professional | Trustworthy, structured | Finance, legal, medical, enterprise | | Dark Luxe | Premium, sophisticated | Fashion, food, nightlife, luxury | | Soft Gradient | Warm, approachable | Wellness, lifestyle, meditation, self-care | | Nature Organic | Earthy, sustainable | Eco, gardening, outdoor, sustainability | | Neo Brutalist | Bold, raw | Creative, media, agency, art | | Tech Dynamic | Futuristic, data-rich | Fitness, sport, automotive, gaming | | Kids Playful | Fun, rounded | Children ages 3-12, education, COPPA-compliant | | Medical Clinical | Clinical, trustworthy | Health, telemedicine, patient portals, HIPAA | | Retro Vintage | Nostalgic, warm | Vintage, coffee, artisan, handmade | | Sport Athletic | Energetic, bold | Athletic, training, competition, performance | | Accessible High Contrast | Inclusive, clear | WCAG AAA, elderly, vision-impaired users |

App Icons

Every template ships with a domain-specific app launcher icon, and generated apps get a custom icon matched to their domain and brand colors.

iOS: Each template includes a pre-rendered 1024x1024 PNG in Assets.xcassets/AppIcon.appiconset/. During customization, the ios-customizer runs scripts/generate-app-icon.swift to regenerate the icon with the app's chosen SF Symbol and primary color.

Android: Each template includes an XML adaptive icon (ic_launcher_foreground.xml vector + ic_launcher_background color). During customization, the android-customizer selects a domain-matched vector from templates/android/ICON_VECTORS.md and updates the background to the app's primary color.

| Template | Icon | iOS SF Symbol | Android Vector | |----------|------|---------------|----------------| | ShopTemplate | Shopping bag | bag.fill | shopping | | TaskTemplate | Checkmark | checkmark.circle.fill | task | | HealthTemplate | Heart | heart.fill | health | | ChatTemplate | Chat bubble | bubble.left.fill | chat | | MapTemplate | Map pin | mappin.circle.fill | map | | MediaTemplate | Play button | play.circle.fill | media | | FinanceTemplate | Dollar sign | dollarsign.circle.fill | finance | | SocialTemplate | Two people | person.2.fill | social | | BookTemplate | Open book | book.fill | book | | GameTemplate | Gamepad | gamecontroller.fill | game | | TrackTemplate | Bar chart | chart.bar.fill | tracking | | DashTemplate | Grid | square.grid.2x2.fill | dashboard | | LearnTemplate | Graduation cap | graduationcap.fill | education | | FamilyTemplate | House | house.fill | house | | ReferenceTemplate | Star | star.fill | star |

The Android vector library (ICON_VECTORS.md) includes additional domains beyond the templates: food, camera, music, fitness, travel, pet, and weather.

Architecture: How It Steers the Agent

AppAgent supports two agent engines that share the same prompt, skills, and workflow. The orchestrator (src/) abstracts the engine behind an AgentEngine interface so the rest of the pipeline is engine-agnostic.

Engine Comparison

| Feature | Cursor CLI | Claude Code | |---------|-----------|-------------| | Command | cursor agent -p | claude -p | | Configuration | .cursor/ directory | .claude/ directory + CLAUDE.md | | Rules | .cursor/rules/*.mdc (auto-applied) | CLAUDE.md at project root (auto-applied) | | Skills | .cursor/skills/*/SKILL.md (read inline) | .claude/skills/*/SKILL.md (YAML frontmatter) | | Subagents | Markdown instruction files | Native child processes with isolated context | | Hooks | .cursor/hooks.json + shell scripts | .claude/settings.json (PreToolUse/PostToolUse/Stop) | | MCP | .cursor/mcp.json | .claude/settings.json mcpServers section | | Output format | --output-format stream-json | --output-format stream-json | | Model mapping | Uses model name directly | Maps to Claude Code aliases (see CLAUDE_MODEL_MAP) |

Steering Mechanisms

| Mechanism | Cursor CLI | Claude Code | Purpose | |-----------|-----------|-------------|---------| | Prompt | prompts/agent-prompt.md | prompts/agent-prompt.md | Primary task instructions | | Rules | .cursor/rules/*.mdc | CLAUDE.md | Always-on guardrails | | Skills | .cursor/skills/*/SKILL.md | .claude/skills/*/SKILL.md | Step-by-step procedures | | Hooks | .cursor/hooks/*.sh | .claude/settings.json | Quality gates (lint, validate, retry) | | MCP | .cursor/mcp.json | .claude/settings.json | Device interaction via ai-tester | | Orchestrator | src/engines/cursor-engine.ts | src/engines/claude-engine.ts | CLI invocation and stream parsing |

Skills are the primary mechanism for guiding the agent. Each skill is a self-contained procedure with instructions, output format, and rules. The agent reads them inline and follows them step by step. Both engines use the same set of skills; the Claude Code versions add YAML frontmatter for native tool/permission/model configuration.

Agent Engines

AppAgent supports two interchangeable agent engines. You can select the engine per invocation via --engine flag, the interactive prompt, or the APPAGENT_ENGINE environment variable.

Claude Code (alternative)

Claude Code is Anthropic's agentic coding CLI. It supports native subagents, skills, hooks, and MCP out of the box.

# Install Claude Code
curl -fsSL https://claude.ai/install.sh | bash
# -- or update to latest --
claude update

# Verify installation and authentication
claude --version
claude auth status

# Run with Claude Code
npm start -- -d "A habit tracker app called Streaky" --engine claude

Claude Code reads its configuration from:

• CLAUDE.md at the project root -- always-applied rules (workflow + safety guardrails)
• .claude/settings.json -- hooks (PreToolUse, PostToolUse, Stop) and permissions
• .claude/agents/*.md -- subagent definitions with YAML frontmatter
• .claude/skills/*/SKILL.md -- skills with tool restrictions and context modes

Model mapping is handled automatically. The orchestrator translates model names (e.g., sonnet-4.5) to Claude Code aliases (e.g., sonnet). See CLAUDE_MODEL_MAP in src/config.ts.

Subagent Delegation

When using Claude Code, heavy workflow steps are delegated to native subagents via the Task tool. Each subagent runs in an isolated context with focused instructions, improving reliability and enabling parallel execution.

| Step | Mode | Subagent Model | Description | |------|------|---------------|-------------| | 0 | 4 parallel subagents | haiku | Prompt validation, template selection, design brand selection, module selection | | 1-2 | Inline | -- | Clone + integrate modules + rename | | 3 | Inline | -- | Customization planning (produce manifest) | | 4 | Inline | -- | Design, content, config, mock data | | 5 | 2-3 parallel subagents | sonnet | Screen customization (batch mode) | | 6 | Subagent | sonnet | Build | | 7 | 2 parallel subagents | haiku | Security audit + validation | | 8-10 | 2-3 parallel subagents | sonnet | Interactive UI testing + Maestro tests |

Step 0 runs 4 tasks in parallel (prompt validation + template + design + modules). Step 5 distributes screen files across 2-3 subagents. Step 7 runs security audit + validation concurrently. Steps 8-10 test across 2-3 simulators in parallel.

Cursor CLI (default)

The default engine. Requires Cursor IDE with CLI access.

# Verify installation
cursor --version

# Run with Cursor (default -- no --engine flag needed)
npm start -- -d "A habit tracker app called Streaky"

# Explicit engine flag
npm start -- -d "A habit tracker app called Streaky" --platform ios --engine cursor

Cursor reads configuration from .cursor/ -- rules, skills, hooks, and MCP config are all picked up automatically when the agent runs in the workspace.

Configuration

AI Models

Available models (configured in src/config.ts):

| Model | Description | |-------|-------------| | sonnet-4.5 | Default -- good balance of speed and quality | | sonnet-4.5-thinking | Sonnet with extended thinking | | opus-4.5 | High quality | | opus-4.5-thinking | Opus with extended thinking | | opus-4.6 | Latest Opus | | opus-4.6-thinking | Highest quality, slower, reasoning model | | gpt-5.2-codex | OpenAI alternative (Cursor engine only) | | gemini-3-pro | Google alternative (Cursor engine only) | | auto | Let the engine choose |

When using Claude Code, model names are mapped automatically (e.g., sonnet-4.5 becomes sonnet). Non-Claude models (GPT, Gemini) are only supported with the Cursor engine.

MCP Servers

The .cursor/mcp.json (Cursor) and .claude/settings.json (Claude Code) configure the ai-tester MCP server for live UI testing. The agent can boot simulators, install apps, tap through screens, and generate Maestro regression tests.

Progress Logging

Both engines provide real-time persistent progress output during builds. Instead of just a spinner, you'll see:

• Timestamped milestones -- subagent dispatches, build commands, report writes
• Periodic summaries -- tool call counts, file read/write counts (every 60 seconds)
• Final summary box -- total duration, tool calls, subagent count, MCP calls, Maestro test results

Progress is logged to stdout. A detailed debug log of all tool calls is also written to output/.agent-debug-claude.jsonl (Claude) or output/.agent-debug.jsonl (Cursor) for post-run analysis. When running dual-platform builds (-p both), each agent writes to a separate debug log with a platform suffix (e.g., .agent-debug-claude-ios.jsonl).

npx Distribution

When installed via npx (or npm install -g), AppAgent automatically detects that it's running outside the source repo and scaffolds a temporary workspace in the user's current directory.

How it works

1. Detection -- IS_INSTALLED flag checks whether src/ exists alongside dist/. If not, we're running as an installed package.
2. Scaffolding -- Before the agent engine starts, scaffoldWorkspace() creates:
   • Symlinks for large directories: templates/, designs/, scripts/ (pointing to the npm package)
   • Selective .claude/ structure: symlinks for skills/ and agents/, copied settings.json
   • Selective .cursor/ structure: symlinks for rules/, skills/, agents/, hooks/, copied config files
   • Root config files: CLAUDE.md, AGENTS.md (copied)
   • Portable .mcp.json: generated with a dynamically resolved ai-tester path
3. Engine runs -- with cwd set to the user's directory, so the agent finds all config via standard discovery
4. Output -- the generated app is written to output/ in the user's current directory
5. Cleanup -- after the run, scaffolded symlinks and copies are removed

ai-tester MCP resolution

For UI testing (Steps 8-10), AppAgent needs the ai-tester MCP server. The path is resolved in this order:

1. AI_TESTER_PATH environment variable (directory or direct path to the entry point)
2. Global npm modules (npm root -g)
3. Local node_modules/ in the package

If not found, a warning is shown and UI testing is skipped.

Development

# Install dependencies
npm install

# Run in dev mode (uses tsx for direct TypeScript execution)
npm run dev

# Build to dist/
npm run build

# Run built version
npm start

Publishing

The package is published as @shaykec/app-agent on npm.

# Build is run automatically via prepublishOnly
npm publish --access public

The files field in package.json ensures dist/, templates/, .cursor/, .claude/, designs/, prompts/, scripts/, CLAUDE.md, and AGENTS.md are included in the published package.

License

MIT