appclone

Turn a Google Play or App Store URL into a complete, AI-readable "clone package" — everything a coding agent needs to functionally re-implement an app: store metadata, real screenshots, a recorded walkthrough, extracted navigation flows, a design-token system, an (optional) API spec, a PRD, a dependency-ordered build plan, and ready-to-use Claude Code skills.

This toolkit prepares documentation; it does not build the clone. With your explicit rights acknowledgment (--i-have-rights) it downloads the app itself — Android via apkeep (APKPure, no account) and iOS via ipatool (your Apple ID) — then, on Android, installs it on an emulator, navigates it, and records the session. It runs as a single npx command so an AI agent (or a human) can invoke it with zero setup. Functional re-implementation only; see Legal.

Requirements

• Node.js ≥ 20 (only hard requirement; the core pipeline runs on Node alone).
• Optional external tools unlock deeper capture; each is probed by doctor and gated per-stage, so anything missing simply reduces coverage — it never blocks a run. See Optional tools.

Run it (no install) — npx

The whole thing is one command — just paste the store URL (the clone subcommand is the default, so you can omit it):

Published as @apptool/appclone on npm:

# Full pipeline: metadata → assets → device capture → docs (writes ./appclone-output/<slug>/)
npx @apptool/appclone "https://play.google.com/store/apps/details?id=com.duolingo"
npx @apptool/appclone "https://apps.apple.com/us/app/id1584095090"

# One command that ALSO installs an app you own and records a live walkthrough:
npx @apptool/appclone "https://play.google.com/store/apps/details?id=com.example" --install ./app.apk

# Probe what tools are available on this machine
npx @apptool/appclone doctor

npx downloads the package, builds it once, and runs the appclone binary. Output is written to appclone-output/ in the current directory (override with APPCLONE_OUTPUT_DIR).

On Android, npx @apptool/appclone "<url>" --i-have-rights downloads the APK (apkeep/APKPure), boots the emulator, installs and launches the app, crawls it, and records the session — all in that single command. Missing tools (apkeep, apktool…) are auto-installed via Homebrew unless you pass --no-auto-install. If the app can't be run, the capture stages skip cleanly and the package is still produced from store data.

You can also run it straight from source without the registry:

npx github:<owner>/appclone "<store-url>"            # from a git remote
# or, from a local checkout:
git clone <repo> && cd appclone && npm install && npx . "<store-url>"

Install globally (optional)

npm install -g @apptool/appclone
appclone "<store-url>"      # the installed command is still `appclone`
appclone doctor

Local development

npm install
npm run appclone -- clone "<store-url>"    # runs TypeScript via tsx, no build
npm run build && node dist/bin/appclone.js doctor
npm run typecheck

Publishing updates

This package is published on npm as @apptool/appclone (public), so anyone can run it with zero setup:

npx @apptool/appclone "https://play.google.com/store/apps/details?id=com.example"

To ship a new version (maintainers of the @apptool org):

1. Log in / have a token with publish rights to @apptool. Publishing requires a one-time password (2FA) unless you use a granular token with "bypass 2FA".
2. Bump the version and republish. The prepare script compiles dist/ automatically first; files in package.json ships dist/, templates/, config/, and python/:

   npm version patch
   npm publish --access public --otp=<code>

Option B — GitHub only (no npm account) → npx github:...

1. Push this repository to GitHub.
2. Anyone runs it straight from the repo — npm clones it, runs prepare (build), then the binary:

   npx github:<your-user>/appclone "https://play.google.com/store/apps/details?id=com.example"

Either way, the bin field (appclone → dist/bin/appclone.js), the prepare build step, and the files allow-list are already configured for publishing.

Commands

Invoke every command as npx @apptool/appclone <command> (zero install). After a global install (npm i -g @apptool/appclone) the binary is simply appclone.

| Command | What it does | |---------|--------------| | npx @apptool/appclone <url> (default) | Run the full 12-stage pipeline for a Play/App Store URL — clone is the default command, so it can be omitted. | | npx @apptool/appclone clone <url> | Same as above, written explicitly. | | npx @apptool/appclone capture <slug\|url> | Re-run only the live device stages (binary → session → explore/record → consolidate) and regenerate the docs. Use after you've provisioned the app on a device. | | npx @apptool/appclone resume <slug> | Continue a previous run from its first unfinished stage (cached stages are skipped). | | npx @apptool/appclone stage <ids> <slug\|url> | Run a subset, e.g. stage 11-12 <slug> to regenerate only synthesis + packaging, or stage 09 <slug> --capture-api. | | npx @apptool/appclone doctor | Print the local toolchain capability matrix. |

Flags (on clone / capture / resume / stage):

| Flag | Effect | |------|--------| | --capture-api | Enable the optional network/API capture stage (off by default). | | --install <path> | Install a local APK / Simulator .app you own, then capture a live walkthrough — the true one-command flow (implies --i-have-rights). | | --i-have-rights | Assert you're entitled to analyze the target binary; gates binary analysis. | | --force | Re-run stages even if already completed (ignore cache). | | --platform android\|ios | Restrict to one platform. | | --log debug\|info\|warn\|error | Log verbosity. |

Environment: APPCLONE_OUTPUT_DIR overrides the output location; APPCLONE_LOG sets the default log level.

The pipeline (12 resumable stages)

doctor → resolve → metadata → store-assets → binary → static-RE → session → explore → capture → network(optional) → design-tokens → synthesis → package

Each stage is content-addressed (resumable) and degrades gracefully: a missing tool, binary, device, or capture becomes a recorded skipped/partial gap — the package is always produced. Raw per-stage evidence lives in appclone-output/<slug>/<NN-stage>/; the deliverable an agent reads is appclone-output/<slug>/clone-package/.

Output: the clone package

appclone-output/<slug>/clone-package/
  README.md  PRD.md  CLONE_PLAN.md  ARCHITECTURE.md  DESIGN_SYSTEM.md
  FEATURES.md  DATA_MODEL.md  NAVIGATION.md  COVERAGE.md  GAPS_AND_ASSUMPTIONS.md  LEGAL.md
  clone-manifest.json          # machine index; stable IDs join every file
  SCREENS/  FLOWS/  API/  DESIGN/  ASSETS/  I18N/  STORE/
  .claude/skills/
     clone-<app>/  acquire-and-run/  design-system/  api-integration/
     screen-builder/  verify-clone/

Every fact is stored once as machine-readable JSON/YAML and narrated in Markdown that references it. Every screen, flow, feature, endpoint, and component gets a stable ID (SCR-…, FLOW-…, FEAT-…, EP-…, CMP-…) so cross-references never break. COVERAGE.md + GAPS_AND_ASSUMPTIONS.md state exactly what was captured vs. inferred, with a confidence level on every item.

For AI agents: how to use a clone package

1. Read clone-manifest.json (the index), then PRD.md, then CLONE_PLAN.md.

2. Follow CLONE_PLAN.md phase by phase; invoke the bundled skills in .claude/skills/ (clone-<app> orchestrates; design-system, api-integration, screen-builder, verify-clone specialize).

3. Want live in-app evidence? The package ships an acquire-and-run skill with exact, platform-specific instructions for provisioning the app in your own environment and then running:

   npx @apptool/appclone capture <slug> --i-have-rights

   This downloads/installs the app (or uses one you supplied), launches it, runs a bounded automated crawl, records the session, and regenerates the docs with real screens, UI hierarchy, a navigation graph, and ASSETS/recordings/.

The toolkit never fakes captures: when the app isn't actually running, capture stages skip rather than grab an unrelated screen.

Platform support

| Capability | Android | iOS | |---|---|---| | Store metadata + assets | ✅ full | ✅ full (App Store web fallback recovers screenshots the iTunes API omits) | | Binary acquisition | ✅ auto-download (apkeep / APKPure, no account) | ✅ auto-download (ipatool, your Apple ID) — encrypted IPA, static-only | | Static RE (resources, strings, SDKs, deep links) | ✅ apktool + jadx | ✅ IPA unzip: Info.plist, URL schemes, permissions, locales, frameworks (no decryption) | | Live install → navigate → record | ✅ fully automated (emulator + adb crawler) | ✅ Simulator build + Maestro auto-crawl; ⚠️ App Store IPAs can't run on Simulator (supply a .app via --install), real-device deep capture via WebDriverAgent (see acquire-and-run) | | Design tokens | static + CV | CV from screenshots | | API capture (optional) | ✅ mitmproxy | ⚠️ device-proxy + pinning |

On iOS the automated crawl is driven by Maestro (XCUITest under the hood — the only reliable way to inject taps and read the UI tree on a Simulator; simctl can't). Install it with curl -Ls https://get.maestro.mobile.dev | bash; without it, iOS degrades to a launch-screen capture.

The behavioral spec is anchored on the Android capture; iOS contributes real store UI, tokens, and docs even without a runnable binary.

Optional tools (for deeper capture)

Install any subset; npx @apptool/appclone doctor shows what's active. macOS examples:

brew install apktool jadx android-platform-tools    # static RE + adb
brew install mitmproxy                               # optional API capture
curl -Ls https://get.maestro.mobile.dev | bash       # iOS Simulator auto-crawl + UI flows
npm i -g appium                                       # deep hierarchy dumps

Python sidecar (design-token color extraction, OpenAPI conversion):

python3 -m venv python/.venv
python/.venv/bin/pip install -r python/requirements.txt

Architecture

Two-tier: a TypeScript/Node orchestrator (src/orchestrator/) drives stages (src/stages/) that call thin adapters (src/adapters/) wrapping best-of-breed external CLIs (apktool, jadx, adb, xcrun, maestro, mitmproxy). The device crawler lives in src/explore/; docs are rendered from templates/ by src/synthesis/. Tunables are in config/default.yaml.

Legal

Output is for functional re-implementation only. Captured screenshots, icon, copy, brand, and any decompiled code are reference evidence — do not ship them. Each package includes a LEGAL.md restating these rules for the cloning agent. Binary acquisition and any SSL-pinning bypass require --i-have-rights. This tool does not provide legal clearance.