Skip to main content
Glama

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)

License: MIT Platforms: Windows · Linux · macOS · Android GitHub Release CI

English | Русская версия (Russian) · Security Policy · Changelog

DroidPath Persistent A* Symbolic UI Router Demo

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

    • Windows: winget install Google.PlatformTools

    • Linux (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 --deploy

Windows (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 -Deploy

After 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 in checksums.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/bin is already on your PATH, "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.jar

VS 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.1 with RFC 6454 loopback Origin/Host validation and Content-Length enforcement.


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: droidpath is not yet published to npmjs.org, so run it from a local clone or via npm link today (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 --- Sys
  1. Layer 1 — Headless Kotlin Shadow DOM Daemon (android-daemon/):

    • Compiles into a standalone ~648 KB single-DEX JAR (android-daemon.jar) launched via app_process — zero companion APK install required — and injects native UiAutomation tap/swipe/keyevent gestures directly over TCP :27189 (with zero-fling 120Hz swipes and automatic adb fallback).

    • Enforces on-device Privacy by Design: binds its TCP socket strictly to 127.0.0.1 loopback (adb forward) and masks isPassword / sensitive editable fields to "***" before streaming over TCP :27189.

    • Streams full snapshots, compact NDJSON incremental diffs, foreground TYPE_APPLICATION window priority over com.android.systemui notifications, and SECURE_SCREEN_ACTIVE / SECURE_SCREEN_CLEARED events on FLAG_SECURE or biometric prompts over TCP (:27189).

    • Deployed idempotently via SHA-256 verification and protected by automatic self-healing recovery.

  2. Layer 2 — Cross-Platform Rust Core (crates/droidpath-core):

    • Bit-exact FNV-1a 64-bit ScreenLayoutHasher stripping volatile clocks, dates, e-commerce tokens (<PRICE>, <ETA>, <WEIGHT>), Luhn-validated card numbers (<CARD>), contextual 2FA/OTP codes (<OTP>), unanchored decorative banner ImageViews, and com.android.systemui notification overlays.

    • SpatialGraphEngine builds a directed multigraph with automatic Jaccard (>= 0.90) compaction, hazardous edge classification (HazardousActionClassifier), consecutiveFailures edge decay and self-pruning, acyclic spanning DAG rebuild, and 100% bidirectional shadow_graph.json compatibility with Swift AndOnMac.

    • Zero-PII Cross-Device Android Settings Seed Graph (SeedGraphCatalog) & Seed-to-Real Hydration: Ships pre-seeded with 20 canonical, coordinate-free com.android.settings screens and 19 deterministic edges (covering EN/RU and Pixel, AOSP, OneUI, HyperOS, OxygenOS semantic aliases). On a brand-new phone, android_navigate_to_node routes 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 via DROIDPATH_DISABLE_SEED_GRAPH=1).

  3. Layer 3 — Persistent A* Router, MCP CLI (crates/droidpath-mcp) & Tauri v2 Desktop HUD (apps/droidpath-desktop):

    • AStarPathfinder + MacroExecutionEngine with cold-start fallback (android_explore_and_click / auto_explore: true), forward-skip recovery (1 -> 3/4), Back-to-Root task-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, and FLAG_SECURE biometric handoff (60s default wait).

    • LLM Onboarding Rules: Ships .cursorrules, CLAUDE.md, GEMINI.md, and docs/system_prompt.md (installable idempotently via packages/droidpath-cli init / rules) so cloud and local models follow the Shadow-DOM-first protocol without spamming android_screenshot.

    • Tauri v2 Desktop HUD combines an embedded scrcpy-server H.264 -> WebCodecs <canvas> mirror (with automatic screencap fallback) 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 (:27189)

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 (screencap) + stateless ADB

Sub-ms Shadow DOM NDJSON + native UiAutomation :27189

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 / uiautomator wrappers

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

<1s / hop

0 intermediate calls on known routes

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

Exposed MCP Tools (9 Tools)

Tool

Description

android_navigate_to_node

Runs Layer 3 A* routing across persisted & seeded screens to reach a target text, resource-id, package, or canonical layout hash (0x...) — supports auto_explore: true cold-start fallback & confirmed: true HITL

android_explore_and_click

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

android_get_ui_tree

Reads live interactive UI elements from the Kotlin Shadow DOM stream in <1ms (with uiautomator XML fallback)

android_graph_stats

Inspects persisted graph vertex/edge counts (seed_vertex_count, hydrated_vertex_count), active canonical hash, daemon state, and storage path

android_list_devices

Lists connected USB and Wireless ADB Android devices

android_tap_element

Taps by (x, y) or semantic text / resource_id / content_desc and attributes the gesture into the Spatial Graph

android_swipe

Swipes (x1, y1) -> (x2, y2) and records the transition

android_type_text

Types ASCII or Unicode/Cyrillic text (via POSIX-quoted clipboard paste) into the focused Android field

android_keyevent

Sends Android keyevents (HOME, BACK, ENTER, RECENTS/APP_SWITCH, VOLUME_UP, VOLUME_DOWN, POWER)


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 *** inside android-daemon before streaming; card PANs (Luhn-validated) and contextual 2FA codes are scrubbed to <CARD> / <OTP> prior to hashing or shadow_graph.json persistence.

  • Loopback-Only Network Surface: Both android-daemon (127.0.0.1:27189) and droidpath-mcp --http (127.0.0.1:8766) bind strictly to 127.0.0.1, enforce RFC 6454 loopback Origin/Host validation and Content-Length bounds (blocking DNS rebinding & CSRF), and support optional Authorization: Bearer <token> authentication.

  • Mandatory HITL & Biometric Safety Gates: Irreversible actions (Pay, Buy, Transfer, Send, Delete, Factory Reset) halt with requires_confirmation until explicit confirmed: true; FLAG_SECURE / biometric prompts pause automation immediately (secure_screen_active).

  • Release SHA-256 Verification: Every GitHub Release publishes a verified checksums.txt manifest; install.sh, install.ps1, and packages/droidpath-cli verify 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.json compatible with cross-platform DroidPath)

License

MIT License © 2026 Kirill Zaitsev. See LICENSE.

Available Tools

9 tools
android_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_navigate_to_nodeB

Layer 3 Persistent A* Symbolic UI Router. Computes the shortest path across known screens in the Spatial Graph and executes taps/swipes via live Shadow DOM feedback without intermediate LLM calls.

Inputs: target, confirmed, max_steps, target_hash, +3 more.

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

    B3.4/5.0

    Scored across 9 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      A 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.
      14
      932
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 PyPI
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      3
      MIT