DroidPath
Provides deterministic UI automation for Android devices by streaming live Shadow DOM state from Android Accessibility and Window APIs, building a persistent spatial graph, and executing multi-screen workflows and gestures with A* pathfinding, without screenshots, companion APKs, or root.
DroidPath
Cross-Platform Persistent A* Symbolic UI Router, Headless Kotlin Shadow DOM Daemon, Native Rust MCP CLI & Tauri v2 Agentic HUD for Android (Windows · Linux · macOS)
English | Русская версия (Russian) · Security Policy · Changelog

DroidPath eliminates slow, token-heavy VLM screenshot-think-tap loops for Android automation. Instead of asking an LLM to inspect screenshots at every step, DroidPath streams a live Shadow DOM directly from Android Accessibility & Window APIs, compiles UI transitions into a persistent Spatial Graph, and navigates multi-screen workflows deterministically with A* pathfinding in sub-second hops — with zero intermediate LLM roundtrips.
Powered by a zero-JVM cross-platform Rust core (droidpath-core), a ~2.0 MB native MCP CLI (droidpath-mcp), a Tauri v2 Desktop HUD (~3 MB installer) with built-in H.264 WebCodecs mirroring (Windows, Linux Wayland/X11, macOS), and 1-click SHA-256 verified native installers (install.sh / install.ps1). Fully 100% shadow_graph.json compatible with native macOS AndOnMac.
Prerequisites
Android 8.0+ (API 26+) device with USB Debugging or Wireless Debugging enabled (no companion APK install and no root required).
Android Platform Tools (
adb) installed on the host:macOS:
brew install android-platform-toolsWindows:
winget install Google.PlatformToolsLinux (Debian/Ubuntu):
sudo apt install adb
Related MCP server: oswright
Quick Start (1-Click Native Installation)
Option A: Native Installers (install.sh / install.ps1 — Recommended, Zero Node.js Required)
Downloads the prebuilt native droidpath-mcp binary and android-daemon.jar directly from GitHub Releases, pins the release tag across CDN redirects, verifies SHA-256 against checksums.txt fail-closed, deploys the daemon over ADB, and auto-configures your MCP clients (cursor, claude, gemini, antigravity, or all):
macOS & Linux:
# Install droidpath-mcp + android-daemon.jar and auto-configure Cursor, Claude Desktop, Gemini CLI & Antigravity:
curl -fsSL https://raw.githubusercontent.com/V0val0x/DroidPath/main/scripts/install.sh | bash -s -- --configure-mcp all
# If an Android device is already connected over USB/Wi-Fi, also deploy the daemon immediately:
curl -fsSL https://raw.githubusercontent.com/V0val0x/DroidPath/main/scripts/install.sh | bash -s -- --configure-mcp all --deployWindows (PowerShell):
# Install droidpath-mcp.exe + android-daemon.jar, add ~/.droidpath/bin to User PATH & auto-configure MCP clients:
$env:DROIDPATH_CONFIGURE_MCP="all"; irm https://raw.githubusercontent.com/V0val0x/DroidPath/main/scripts/install.ps1 | iex
# If an Android device is already connected over USB/Wi-Fi, also deploy the daemon immediately:
$env:DROIDPATH_DEPLOY="1"; $env:DROIDPATH_CONFIGURE_MCP="all"; irm https://raw.githubusercontent.com/V0val0x/DroidPath/main/scripts/install.ps1 | iex
# Or run from a local checkout with explicit flags:
.\scripts\install.ps1 -ConfigureMcp all -DeployAfter installation, droidpath-mcp is installed to ~/.droidpath/bin/droidpath-mcp (Windows: %USERPROFILE%\.droidpath\bin\droidpath-mcp.exe) alongside ~/.droidpath/share/android-daemon.jar:
droidpath-mcp doctor # Full ADB, device, daemon JAR, :27189 & graph health check
droidpath-mcp deploy # SHA-256 cached adb push + adb forward + app_process launch
droidpath-mcp --stdio # Run stdio JSON-RPC 2.0 MCP server
droidpath-mcp --http --port 8766 # Run loopback HTTP + SSE MCP server (127.0.0.1:8766/sse)Desktop HUD Installers: Prebuilt Tauri v2 Desktop HUD installers (
.dmg,.deb,.AppImage,.msi,.exe) are also attached to every GitHub Release with SHA-256 digests inchecksums.txt.
Option B: Copy-Paste MCP Client Configurations
Once installed via Option A (or built from source), add droidpath-mcp to any MCP client:
Claude Desktop & Cursor (stdio)
Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json(macOS),%APPDATA%\Claude\claude_desktop_config.json(Windows),~/.config/Claude/claude_desktop_config.json(Linux)Cursor:
~/.cursor/mcp.json
{
"mcpServers": {
"droidpath": {
"command": "/Users/<you>/.droidpath/bin/droidpath-mcp",
"args": ["--stdio", "--daemon-jar", "/Users/<you>/.droidpath/share/android-daemon.jar"]
}
}
}On Windows, use
"command": "C:\\Users\\<you>\\.droidpath\\bin\\droidpath-mcp.exe"and"C:\\Users\\<you>\\.droidpath\\share\\android-daemon.jar". If~/.droidpath/binis already on yourPATH,"command": "droidpath-mcp"with"args": ["--stdio"]automatically discovers../share/android-daemon.jar.
Claude Code
claude mcp add droidpath -- ~/.droidpath/bin/droidpath-mcp --stdio --daemon-jar ~/.droidpath/share/android-daemon.jarVS Code / GitHub Copilot (.vscode/mcp.json)
{
"servers": {
"droidpath": {
"type": "stdio",
"command": "droidpath-mcp",
"args": ["--stdio"]
}
}
}Gemini CLI (~/.gemini/settings.json) & Antigravity (~/.gemini/antigravity/mcp_config.json)
{
"mcpServers": {
"droidpath": {
"command": "droidpath-mcp",
"args": ["--stdio"]
}
}
}LM Studio / OpenWebUI / MCP Inspector / Local AI (Loopback HTTP + SSE)
droidpath-mcp --http --port 8766
# Optional Bearer auth: droidpath-mcp --http --port 8766 --auth-token "<your-secret>"{
"mcpServers": {
"droidpath": {
"url": "http://127.0.0.1:8766/sse"
}
}
}Strictly binds to
127.0.0.1with RFC 6454 loopbackOrigin/Hostvalidation andContent-Lengthenforcement.
Option C: Node.js Zero-Friction CLI (From Local Clone / npm link)
The companion Node.js CLI (packages/droidpath-cli) adds idempotent multi-client agent rule installation (.cursorrules, CLAUDE.md, GEMINI.md, .agent/rules/droidpath.md, OpenAI tool schemas, and compact local LLM prompts).
Note:
droidpathis not yet published tonpmjs.org, so run it from a local clone or vianpm linktoday (npx -y droidpath ...will also work once published to npm):
git clone https://github.com/V0val0x/DroidPath.git
cd DroidPath
# Run directly from clone:
node packages/droidpath-cli/bin/droidpath.mjs start --configure
node packages/droidpath-cli/bin/droidpath.mjs doctor
# Or link globally once on your machine:
npm --prefix packages/droidpath-cli link
droidpath init --client all # Configure Cursor, Claude, Gemini CLI, Antigravity, LM Studio & Local AI + agent rules
droidpath rules --format local # Print compact system prompt for local models (or --format openai for tool schemas)
droidpath daemon deploy # SHA-256 cached adb push + adb forward + app_process
droidpath mcp --stdio # Launch native Rust MCP server (auto-injects daemon)Architecture (3 Layers · Cross-Platform)
flowchart LR
Agent["AI Agent (Claude / Cursor / Gemini / MCP Client)"] <-->|"JSON-RPC 2.0 (stdio / HTTP+SSE)"| CLI["droidpath-mcp (Rust ~2.0 MB)\nNative CLI & MCP Server"]
subgraph Host["Windows · Linux · macOS Host (Rust droidpath-core + Tauri v2 HUD)"]
CLI <-->|"Path Queries & Passive Learning"| Bridge["ShadowGraphBridge"]
HUD["Tauri v2 Desktop HUD\nscrcpy H.264 -> WebCodecs\nHITL Buttons & Passive Clicks"] <--> Bridge
Bridge --> DOM["ShadowDomState + ShadowTreeIndex"]
Bridge --> Graph["SpatialGraphEngine\nScreenLayoutHasher · Jaccard ≥ 0.90\n~/.droidpath/shadow_graph.json\n(100% AndOnMac Swift-compatible)"]
Bridge --> AStar["AStarPathfinder + MacroExecutionEngine\nAuto-Recovery · HITL · FLAG_SECURE"]
Bridge -->|"Self-Healing Recovery Hook"| Recovery["SHA-256 Deploy + app_process Restart"]
end
subgraph Android["Android Device (Zero-APK)"]
Daemon["android-daemon.jar (Kotlin single-DEX)\napp_process :27189 · NDJSON Delta Stream"]
Scrcpy["scrcpy-server (H.264 + Control)"]
Sys["UiAutomation / Accessibility / WindowManager"]
end
Daemon <-->|"adb forward tcp:27189"| DOM
Scrcpy <-->|"Loopback WS -> WebCodecs"| HUD
AStar -->|"TCP :27189 native input (ADB fallback)"| Daemon
Daemon --- SysLayer 1 — Headless Kotlin Shadow DOM Daemon (
android-daemon/):Compiles into a standalone ~648 KB single-DEX JAR (
android-daemon.jar) launched viaapp_process— zero companion APK install required — and injects nativeUiAutomationtap/swipe/keyeventgestures directly over TCP:27189(with zero-fling 120Hz swipes and automaticadbfallback).Enforces on-device Privacy by Design: binds its TCP socket strictly to
127.0.0.1loopback (adb forward) and masksisPassword/ sensitive editable fields to"***"before streaming over TCP:27189.Streams full snapshots, compact NDJSON incremental diffs, foreground
TYPE_APPLICATIONwindow priority overcom.android.systemuinotifications, andSECURE_SCREEN_ACTIVE/SECURE_SCREEN_CLEAREDevents onFLAG_SECUREor biometric prompts over TCP (:27189).Deployed idempotently via SHA-256 verification and protected by automatic self-healing recovery.
Layer 2 — Cross-Platform Rust Core (
crates/droidpath-core):Bit-exact FNV-1a 64-bit
ScreenLayoutHasherstripping volatile clocks, dates, e-commerce tokens (<PRICE>,<ETA>,<WEIGHT>), Luhn-validated card numbers (<CARD>), contextual 2FA/OTP codes (<OTP>), unanchored decorative bannerImageViews, andcom.android.systemuinotification overlays.SpatialGraphEnginebuilds a directed multigraph with automatic Jaccard (>= 0.90) compaction, hazardous edge classification (HazardousActionClassifier),consecutiveFailuresedge decay and self-pruning, acyclic spanning DAG rebuild, and 100% bidirectionalshadow_graph.jsoncompatibility with SwiftAndOnMac.Zero-PII Cross-Device Android Settings Seed Graph (
SeedGraphCatalog) & Seed-to-Real Hydration: Ships pre-seeded with 20 canonical, coordinate-freecom.android.settingsscreens and 19 deterministic edges (covering EN/RU and Pixel, AOSP, OneUI, HyperOS, OxygenOS semantic aliases). On a brand-new phone,android_navigate_to_noderoutes from Home (LaunchApp("com.android.settings")) straight to targets like Night Light, Developer options, or Wi-Fi on the very first run, then automatically hydrates traversed seed vertices and edges into exact device-specific layout hashes, selectors, and coordinates (opt-out viaDROIDPATH_DISABLE_SEED_GRAPH=1).
Layer 3 — Persistent A* Router, MCP CLI (
crates/droidpath-mcp) & Tauri v2 Desktop HUD (apps/droidpath-desktop):AStarPathfinder+MacroExecutionEnginewith cold-start fallback (android_explore_and_click/auto_explore: true), forward-skip recovery (1 -> 3/4),Back-to-Roottask-stack drift unwinding,Smart Scroll-to-Selector, off-path scroll replan, universal popup dismissal (UniversalDismissDetector), reflexive heads-up notification swipe-up, Human-in-the-Loop confirmation (requires_confirmation/confirmed: true) before irreversible payment/destructive steps, andFLAG_SECUREbiometric handoff (60s default wait).LLM Onboarding Rules: Ships
.cursorrules,CLAUDE.md,GEMINI.md, anddocs/system_prompt.md(installable idempotently viapackages/droidpath-cliinit/rules) so cloud and local models follow the Shadow-DOM-first protocol without spammingandroid_screenshot.Tauri v2 Desktop HUD combines an embedded
scrcpy-serverH.264 -> WebCodecs<canvas>mirror (with automaticscreencapfallback) and an integrated 3-color Agentic HUD (Red autonomous execution, Yellow awaiting HITL confirmation with interactive Approve / Cancel buttons, Blue awaiting biometrics /FLAG_SECURE) + live SVG Spatial Graph Explorer (with seeded vs. hydrated vertex styling) in a single window — working cleanly on Windows, macOS, and Linux Wayland/X11 while preserving passive graph learning by clicking.
Live Benchmark (Pixel 10a · android_navigate_to_node)
Prompt: "Navigate to Show layout bounds" (Home > Settings > System > Developer Options > Show Layout Bounds):
Metric | Traditional VLM Screenshot Loop | DroidPath A* + Native Daemon ( |
Intermediate LLM Roundtrips | 7–9 vision inference calls (~15k tok) | 0 calls (0 vision tokens) |
Total End-to-End Latency | ~30,000–40,000 ms (est.) | 2,003 ms (7 hops · 1x live) |
State & Input Path | Full PNG screenshots ( | Sub-ms Shadow DOM NDJSON + native |
Comparison with Alternatives
Existing solutions rely on stateless ADB bindings, adding 2–4 seconds of latency per action and forcing the LLM to micromanage the UI step by step. DroidPath (and AndOnMac) uses a persistent Directed Acyclic Graph (DAG) and A* routing across Windows, Linux, and macOS, cutting latency to <1s per click and removing LLM overhead on known routes.
Tool | UI & Automation Model | Latency / Action | LLM Overhead | Mirroring & HUD |
Mobile MCP / Maestro MCP / adbridge | Stateless ADB / | 2–4 s | LLM plans every tap/scroll | None |
Appium / CursorTouch | WebDriver sessions or screenshot/coordinate loops | 2–5 s | Heavy screenshot / selector polling | External / VNC |
DroidPath (Rust + Tauri v2 / AndOnMac) | Persistent DAG + A* router + live Shadow DOM daemon |
|
| Tauri v2 WebCodecs / 120Hz Metal + 3-color HUD |
Building from Source
Prerequisites: Rust (stable), adb (Android Platform Tools), Node.js 18+ (for CLI / Tauri frontend), JDK 17 (only if rebuilding android-daemon.jar).
git clone https://github.com/V0val0x/DroidPath.git
cd DroidPath
# 1. Run all Rust core + MCP integration tests
cargo test -p droidpath-core -p droidpath-mcp
# 2. Build optimized native droidpath-mcp binary (~2.0 MB, zero JVM)
cargo build --release -p droidpath-mcp
# 3. Run Node.js CLI unit & installer tests
npm --prefix packages/droidpath-cli test
# 4. Build & launch cross-platform Tauri v2 Desktop HUD
cd apps/droidpath-desktop
npm install
npm run tauri dev # or: npm run tauri build
# 5. (Optional) Rebuild Kotlin single-DEX android-daemon.jar
./android-daemon/scripts/build-dex.sh
npm --prefix packages/droidpath-cli run sync-daemonExposed MCP Tools (9 Tools)
Tool | Description |
| Runs Layer 3 A* routing across persisted & seeded screens to reach a target text, |
| Dynamic Cold-Start Auto-Explore: scores live Shadow DOM nodes, scrolls scrollable lists (reversing at bottom), clicks, and records new edges into the Spatial Graph on the fly (or returns top-20 PII-scrubbed |
| Reads live interactive UI elements from the Kotlin Shadow DOM stream in |
| Inspects persisted graph vertex/edge counts ( |
| Lists connected USB and Wireless ADB Android devices |
| Taps by |
| Swipes |
| Types ASCII or Unicode/Cyrillic text (via POSIX-quoted clipboard paste) into the focused Android field |
| Sends Android keyevents ( |
Security, Privacy & Supply-Chain Integrity
See SECURITY.md for the full security policy and vulnerability disclosure process.
Zero-PII On-Device & On-Disk: Password fields are masked to
***insideandroid-daemonbefore streaming; card PANs (Luhn-validated) and contextual 2FA codes are scrubbed to<CARD>/<OTP>prior to hashing orshadow_graph.jsonpersistence.Loopback-Only Network Surface: Both
android-daemon(127.0.0.1:27189) anddroidpath-mcp --http(127.0.0.1:8766) bind strictly to127.0.0.1, enforce RFC 6454 loopbackOrigin/Hostvalidation andContent-Lengthbounds (blocking DNS rebinding & CSRF), and support optionalAuthorization: Bearer <token>authentication.Mandatory HITL & Biometric Safety Gates: Irreversible actions (
Pay,Buy,Transfer,Send,Delete,Factory Reset) halt withrequires_confirmationuntil explicitconfirmed: true;FLAG_SECURE/ biometric prompts pause automation immediately (secure_screen_active).Release SHA-256 Verification: Every GitHub Release publishes a verified
checksums.txtmanifest;install.sh,install.ps1, andpackages/droidpath-cliverify SHA-256 digests fail-closed with 2-hop CDN redirect pinning and atomic installation.
Ecosystem & macOS Native Companion
AndOnMac — Native macOS 120Hz ProMotion VideoToolbox + Metal Android mirroring app with Swift
AndroidShadowGraphKit(100%shadow_graph.jsoncompatible with cross-platform DroidPath)
License
MIT License © 2026 Kirill Zaitsev. See LICENSE.
Available Tools
9 toolsandroid_explore_and_clickA
Dynamic Shadow DOM discovery + click with optional A* graph/prefix routing, bounded list scrolling (down/up), hazardous action HITL guard, and automatic Spatial Graph edge recording. Returns top-20 PII-redacted interactive candidates (needs_selection, isError: false) if no confident match is found.
Inputs: target (required), confirmed, max_scrolls, device_serial, +2 more.
android_get_ui_treeB
Reads interactive Android UI elements from the sub-millisecond Kotlin Shadow DOM stream (falls back to uiautomator XML if daemon stream is cold).
Inputs: device_serial.
android_graph_statsB
Returns Spatial Graph telemetry: learned screen vertices, action edges, active canonical layout hash, daemon state, and persisted graph path.
Inputs: no named parameters.
android_keyeventB
Sends an Android keyevent (e.g. HOME, BACK, ENTER, APP_SWITCH, POWER).
Inputs: keycode (required), device_serial.
android_list_devicesA
Lists connected Android devices visible over USB or Wireless ADB.
Inputs: no named parameters.
android_swipeC
Performs a touch swipe from (x1, y1) to (x2, y2) and attributes the action to the Spatial Graph.
Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +2 more.
android_tap_elementA
Taps an Android UI element by coordinates (x, y) or semantic text / resource_id / content_desc, recording the transition edge into the Spatial Graph.
Inputs: x, y, text, resource_id, +2 more.
android_type_textA
Types ASCII or Unicode text into the focused Android input field with optional press_enter.
Inputs: text (required), press_enter, device_serial.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
The nine tools cover distinct layers: symbolic A* routing (navigate_to_node), dynamic discovery with optional routing (explore_and_click), raw element lookup (get_ui_tree), and a manual low-level tap (tap_element). There is some residual overlap since navigate_to_node, explore_and_click, and tap_element can all end in a tap, but the descriptions clearly delineate graph-routing vs. discovery vs. direct targeting.
All tools share the android_ prefix and snake_case, with most following a verb_noun shape (android_tap_element, android_swipe, android_list_devices). Minor deviations exist in noun-only forms like android_graph_stats and android_keyevent, but the convention remains predictable.
Nine tools is a well-scoped surface for an Android automation server, with each tool earning its place across graph routing, discovery, introspection, and primitive input actions. No redundant or filler tools are present.
Core interaction primitives (tap, swipe, type, keyevent, navigate, explore, UI tree, device listing) are covered, but notable gaps remain for an Android automation domain: no screenshot or visual capture, no app launch/package management, and no explicit wait-for-element or long-press/lifecycle operations.
Maintenance
Related MCP Connectors
AI agents on real phones: run tasks, read the screen, tap, type and install apps.
Cloud Android phones for AI agents: create a phone, read the screen, tap, type, install APKs, park.
Cloud Android phones for AI agents: give phones a task in plain words and get the answer
Graph-native persistent memory for AI agents — 33 MCP tools, zero-LLM writes.
Related MCP Servers
- AlicenseCqualityBmaintenanceA lightweight bridge enabling AI agents to perform real-world tasks on Android devices such as app navigation, UI interaction, and automated QA testing without requiring computer-vision pipelines or preprogrammed scripts.14932MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to automate real desktop applications across Windows, Linux, and macOS using incremental screen perception, accessibility trees, OCR, and window management, dramatically reducing token usage compared to screenshot-per-step approaches.36 PyPI4MIT
- AlicenseAqualityBmaintenanceRuntime access for AI coding agents to observe and control Android and iOS apps.520 npm9MIT
- AlicenseAqualityBmaintenanceEnables an LLM agent to control a real Android phone by choosing runtime-discovered targets from live device state, with safety gating and approval for mutating commands.3MIT