How to preview a Claude Code–built Android app

Claude Code is genuinely good at the first 90% of an Android app: the code, the build, even the tests. The last 10% is awkward for everyone — the app exists as an .apk file and nobody in the conversation can see it. This guide wires PreviewAPK into the loop so every build lands on a cloud device that Claude can drive and verify, and that you can open with a link.

What you need

• A PreviewAPK account with a device slot (private beta — join the waitlist on the homepage).
• Your API key, from the portal's Developers card.
• An Android project Claude Code can compile to an APK (debug builds are fine).

Option A: the CLI (two minutes)

Download the CLI once, from any terminal:

curl -o previewapk https://previewapk.siteport.site/cli/previewapk.py && chmod +x previewapk

export PREVIEWAPK_API_KEY=<your key>

Then the whole loop is one command per build:

./previewapk push app/build/outputs/apk/debug/app-debug.apk --run

It prints the session's share link. Poll ./previewapk status until the device is live, then ./previewapk shot screen.jpg saves the current screen — an image Claude can open and inspect like any other file in the project.

Option B: the MCP server (native tools)

If you'd rather Claude have tools than a shell script, register the MCP server once:

curl -o previewapk_mcp.py https://previewapk.siteport.site/mcp/previewapk_mcp.py

claude mcp add previewapk --env PREVIEWAPK_API_KEY=<your key> -- python3 /path/to/previewapk_mcp.py

Claude now has previewapk_push_apk, previewapk_start, previewapk_tap, previewapk_tap_text, previewapk_type_text, previewapk_screenshot (which returns the screen as an image in the conversation), previewapk_hierarchy (the screen as an element tree — cheaper than screenshots for navigation), previewapk_handoff, and friends. The screenshot tool is the one that changes the dynamic: the result comes back inside the session, so verification is part of Claude's normal turn.

The prompt to give your agent

Paste this into your project's CLAUDE.md (or say it once in the session):

That one paragraph is the difference between "the build succeeded" and "I looked at it, and it works."

Driver modes, in this workflow

Claude starts sessions agent-driven: it taps and types through the API while you, in the portal, watch it work in real time — a strange and useful sight the first time. When it's done, handoff passes the same live session to you, no reboot: now your taps count and its input is refused. If you'd rather Claude never drive, have it start sessions user-driven; then it can push builds and open sessions, but every input call it makes is rejected. Full details in the developer & agent guide.

Troubleshooting

• Input returns 409 "device is not running". The session is still booting (in seconds) or idled out after 15 quiet minutes. Poll status; start it again if it stopped.
• Agent input returns 403. The session is user-driven. Either hand it over (previewapk handoff agent) or restart it in agent mode.
• The screenshot is a launcher, not your app. Something pressed Home, or the app crashed to the launcher — which is itself a finding worth reporting. Re-run and screenshot again.
• The preview link shows an old build. It always opens the device's current attachment; a new push replaces it. If the content looks stale, the push didn't happen for this build.

Keep going

• AI agent Android testing — the model behind this workflow: loops, driver modes, honest limits.
• Preview deployments for Android — the same push, automated in CI for human teams.
• Built your app with AI? — the non-developer version of this guide.

FAQ

Does Claude Code need Android Studio for this?

Claude Code needs a way to compile the APK (a JDK and the Android SDK command-line tools are enough). What PreviewAPK removes is the second half: no emulator images, no Android Studio GUI, no physical device needed to see and test the result.

Can Claude verify the UI itself, or does it just start the app?

It can verify. In an agent-driven session Claude can tap, type, and request screenshots — returned as images it can inspect — so it can check that a screen looks right, iterate if it doesn't, and only then hand the session to you.

What exactly gets uploaded — my code?

Only the compiled APK, the same file you'd send a tester. Your source code stays in your repo; PreviewAPK never sees it. The APK lands on your own device slot, and share links from it are view-only.

Which agents does this work with besides Claude Code?

The same three doors — CLI, REST API, MCP — work for Cursor, Codex, and any agent that can run a shell command or speak MCP. Claude Code is the worked example because its MCP and shell support make the loop especially clean.