droidlens

<p align="center"><img src="apps/desktop/build/icon.png" width="120" alt="DroidLens"></p> <h1 align="center">DroidLens</h1> <p align="center">A lens into Android apps — analysis · debugging · screen flows · scenario verification<br> Inspect <b>any app</b> with just adb, no SDK required, and let Claude Code agents drive the device to verify it.</p> <p align="center"><a href="https://github.com/ESeungJun/droidlens/releases/latest"><b>⬇ Download the latest release</b></a></p> <p align="center"><b>English</b> · <a href="README.ko.md">한국어</a></p> <p align="center"><a href="docs/video/droidlens-demo.mp4"><img src="docs/images/demo.gif" width="100%" alt="DroidLens demo: mirroring, 3D view hierarchy, screen flow, library detection and Claude Code agents"></a><br> _{▶ <a href="docs/video/droidlens-demo.mp4">Watch the full-quality video (MP4, 28s)</a>}</p>

---

DroidLens aims to replace Meta's Flipper (archived in 2025). Without adding anything to your app, you get screen mirroring, the view hierarchy, screen navigation paths, and the libraries an app uses — and the built-in MCP server lets Claude Code agents use the same features.

Screenshots

<p align="center"><img src="docs/images/screen-en.jpg" alt="Screen mirroring and controls" width="100%"></p> <table> <tr> <td align="center" width="50%"><b>3D view hierarchy with class labels</b><br><img src="docs/images/inspect-3d-en.jpg" alt="3D view hierarchy with class labels"></td> <td align="center" width="50%"><b>Screen flow from auto-exploration</b><br><img src="docs/images/flow-en.jpg" alt="Screen flow from auto-exploration"></td> </tr> <tr> <td align="center"><b>Library detection from the APK</b><br><img src="docs/images/libs-en.jpg" alt="Library detection from the APK"></td> <td align="center"><b>App info</b><br><img src="docs/images/info-en.jpg" alt="App info"></td> </tr> </table>

Installation

macOS · Linux — one line in Terminal (installs or updates to the latest version; on macOS it opens without any Gatekeeper warning):

curl -fsSL https://raw.githubusercontent.com/ESeungJun/droidlens/master/scripts/install.sh | bash

Or download just one installer for your OS from Releases. The other files (.zip, .mjs, .apk) are used by in-app updates or optional tools — you don't need them.

| OS | File | | --- | --- | | macOS (Apple silicon, M1+) | DroidLens-x.y.z-mac-arm64.dmg | | macOS (Intel) | DroidLens-x.y.z-mac-x64.dmg | | Windows (x64) | DroidLens-x.y.z-win-x64.exe | | Windows (ARM) | DroidLens-x.y.z-win-arm64.exe | | Linux | DroidLens-x.y.z-linux-x86_64.AppImage |

First launch on macOS (downloaded .dmg): the app is ad-hoc signed but not notarized by Apple, so macOS says it can't verify the developer. Open System Settings → Privacy & Security and click Open Anyway next to DroidLens (once). On versions before 0.5.0 the message was "damaged"; run this once instead:

xattr -dr com.apple.quarantine /Applications/DroidLens.app

First launch on Windows: if SmartScreen warns you, click "More info → Run anyway".

Updates: when a new version is out, an ⬆ Update button appears in the top bar. Click it to download, replace, and restart (you can also check from the Settings & Integrations tab; the macOS log is at ~/.droidlens/update.log).

Prerequisite: adb

If Android Studio is installed, adb is found automatically. Otherwise, install just the platform-tools:

macOS    brew install --cask android-platform-tools
Windows  winget install Google.PlatformTools
Linux    sudo apt install adb

Then enable Developer options → USB debugging on your device and connect it, or start an emulator. Virtual devices (AVDs) on this computer appear in the device list at the top; pick one and DroidLens starts it and selects it once it has booted (there is a stop button too). If you have none, the device setup helper walks you through installing one. You can also set the adb path manually in the app's Settings & Integrations tab.

Features

| Tab | What it does | | --- | --- | | Screen | High-frame-rate mirroring (scrcpy stream + WebCodecs, up to 60fps) or snapshot mode; click = tap · drag = swipe · hold = long press; hardware keys, text input, screenshots, recording (up to 180s) | | View hierarchy | Two-way selection between screenshot and tree, attributes and selectors, node count by depth, Compose detection, 3D exploded view | | Screen flow | A per-app screen map — screens and transitions from auto-exploration, manual use, and scenario runs keep adding up in one map (thumbnails + action labels). Auto-exploration (never taps payment, delete, logout, or send buttons), pick buttons, long presses, or swipes on a screenshot and explore only the flows they open, tapped-button coverage per screen, path from the first screen, auto-navigate to a screen along the recorded path, map export/import (merge) | | Logs | Live logcat (app PID filter, level, search), recent crashes | | Network ¹ | OkHttp requests and responses (headers, pretty-printed JSON bodies, image preview, timing), failure filter, copy as cURL | | App data ¹ | View and edit SharedPreferences, SQLite/Room DB browser with SQL execution, custom events | | Libraries | Detects 100+ libraries and frameworks from the APK's DEX and native libs, estimates obfuscation | | App info | Version, SDK, permissions, activities; launch / restart / kill; deep links | | Scenarios | Verification reports (per-step screenshots and verdicts), write and run YAML scripts, run the full regression suite | | Settings & Integrations | adb path, one-click Claude Code MCP registration, install bundled agents | | 💬 Agent chat | Chat panel opened from the top bar. Ask the verifier or analyst agent while watching the mirror (uses this computer's Claude Code login — no API key needed) |

¹ Requires the DroidLens SDK in your app's debug build.

App SDK (optional)

Information that only lives inside the app — network traffic, storage — is visible only in your own app's debug build with the SDK added. Release builds get a no-op implementation of the same API (sdk-noop).

// settings.gradle.kts
dependencyResolutionManagement {
    repositories { maven { url = uri("https://jitpack.io") } }
}

// app/build.gradle.kts
dependencies {
    debugImplementation("com.github.ESeungJun.droidlens:sdk:v0.5.0")
    releaseImplementation("com.github.ESeungJun.droidlens:sdk-noop:v0.5.0")
}

// Network inspector (if you use OkHttp)
val client = OkHttpClient.Builder()
    .addInterceptor(DroidLensInterceptor())
    .build()

// Custom events (optional)
DroidLens.event("purchase_clicked", JSONObject().put("itemId", 42))

• No initialization code needed (starts automatically via a ContentProvider)
• Communicates only over an in-app Unix socket (localabstract:droidlens_sdk_<package>), so no INTERNET permission is required; it checks the peer UID and rejects any connection other than adb and the app itself (e.g. other apps on the same device)
• Request and response bodies are capped at 256KB each; the latest 500 entries are kept in memory only
• Sensitive values are masked on the device, before they are stored — in headers, URL queries, Location redirects, JSON bodies (including nested objects/arrays and JSON inside strings), GraphQL arguments, form, multipart and XML bodies, error messages and custom events. Keys match regardless of case and separators, and common words match anywhere in the name (newPassword, fcmToken, X-Refresh-Token); short ones like jwt, otp, pin match exactly. Add your own with DroidLens.redactHeaders("X-Session") / DroidLens.redactKeys("phone"), or call DroidLens.clearDefaultRedaction() to use only your list. Compressed bodies the app requested itself (Content-Encoding) are not recorded
• DB write SQL runs only when explicitly allowed

Claude Code integration

Just press two buttons in the app's Settings & Integrations tab.

1. Register MCP — registers the app's built-in MCP server (44 tools) with claude mcp add --scope user. No separate Node install needed.
2. Install agents — copies the bundled agents to ~/.claude/agents/.

| Agent | What it does | | --- | --- | | droidlens-verifier | Verifies natural-language scenarios step by step on a real device and leaves an HTML report with screenshots | | droidlens-analyst | Analyzes the tech stack, UI structure (View/Compose), and screen map. With REA installed, it traces down to the code level |

Restart Claude Code, then ask:

Use droidlens-verifier to verify the search → product detail → add to wishlist scenario in the shopping app

Use droidlens-analyst to analyze this app's tech stack and screen structure

To use only the MCP server without the app, download droidlens-mcp.mjs (Node 20+) from Releases and register it with claude mcp add --scope user droidlens -- node /path/to/droidlens-mcp.mjs.

Scenario scripts (regression tests)

Save verified flows as YAML and replay them anytime. When an agent passes a scenario with droidlens-verifier, its actions and checks are recorded automatically and saved to ~/.droidlens/scripts/. You can also write or edit scripts by hand.

name: Product search
app: com.example.shop
setup: { restart: true }          # clearData and prefs (SDK) can also set up the initial state
steps:
  - tap: { text: Search }
  - type: { text: sneakers, into: { className: EditText } }
  - enter                          # one-word shorthands: back / home / enter / launch / screenshot
  - wait: { id: result_list, timeout: 8000 }
  - swipe: { direction: up, until: { textContains: Air Max } }
  - tap: { textContains: Air Max }
  - assert: { activity: ProductDetailActivity }
  - assert: { network: { url: /api/products, method: GET, status: 200 } }   # SDK
  - assert: { event: product_viewed }                                        # SDK
  - assert: { noCrash: true }

| Step | Description | | --- | --- | | tap / longPress | Waits for the element matching a selector (id · text · textContains · desc · descContains · className · index), then presses it. With optional: true, skipped if absent | | type | Text input (into targets an input field, clear replaces). Supports non-ASCII text (e.g. Korean) when the agent is running | | swipe | up/down/left/right; with until, scrolls until the element appears | | wait | Until an element appears (with gone: true, until it disappears) | | assert | visible · notVisible · text · activity · package · network · pref · db · event · noCrash | | Other | key, tapAt, sleep, launch, deeplink, screenshot |

How to run:

• Desktop: Scenarios → Scripts tab to edit, run, and run the full regression suite
• Claude Code: script_run, suite_run, script_write
• CI/terminal: node droidlens-mcp.mjs run <file|folder> [--serial <device>] (exit code 1 on failure)

See examples/scripts for examples.

Outputs

Everything is saved under ~/.droidlens/ (override with DROIDLENS_HOME).

| Folder | Contents | | --- | --- | | screenshots/, recordings/ | Screenshot PNGs, recorded mp4s | | graphs/<package>/ | App screen map graph.json, graph.mmd (mermaid), per-screen screenshots. 'Export' in the Screen flow tab saves a single *.droidlens-map.json with screenshots | | scenarios/<id>/ | Scenario verification report.html, scenario.json, recorded script.yaml, per-step screenshots | | scripts/ | Regression test scripts (YAML) | | apks/<package>/ | APKs pulled for analysis |

On-device agent

When a device is connected, DroidLens automatically installs and starts a small agent app (`io.github.eseungjun.droidlens.ag