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

Installation

`bash


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

$3

`bash


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.

$3

`bash
npm install -g @shaykec/app-agent

Then run from anywhere


app-agent -d "A pet grooming booking app called PawSpa"
app-agent # interactive mode
`

$3

`bash
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.

$3

`bash


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 | Launch a built app on a simulator/emulator by directory name |
| -t, --test | 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 | Update an existing app from a GitHub URL, local path, or app name. Creates a branch and PR. |

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

$3

| 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-template-selection.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.

$3

`bash
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
`

$3

`bash


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.

$3

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

`bash


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.

$3

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)

`bash


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.

$3

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.

`bash


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:

`bash


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.

$3

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/.

`bash


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)
│
├── 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
│ │ ├── template-selector/ # Step 0: Pick the best template
│ │ ├── design-selector/ # Step 0: Pick the best design brand
│ │ ├── module-selector/ # Step 0: Pick shared modules by keyword
│ │ ├── 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
│ │
│ ├── 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/ # Skills with Claude Code frontmatter
│ └── 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-template-selection.md
│ ├── 02b-module-selection.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.

`mermaid
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"]]
TS[["template-selector"]]
DS[["design-selector"]]
MS[["module-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 + select template + select design + select modules | 4 parallel tasks | prompt-validator, template-selector, design-selector, module-selector | 01-prompt-validation.md, 02-template-selection.md, 03-design-brand.md, 02b-module-selection.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 |

$3

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:

`json
{
"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"
}
`

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.

$3

| 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) |

$3

| 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.

$3

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

`bash


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.

$3

The default engine. Requires Cursor IDE with CLI access.

`bash


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

$3

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.

$3

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.

$3

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.

$3

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

$3

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

`bash


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
`

$3

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

`bash


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