{"_id":"@artemisai/pi-droid","_rev":"5-43592ab3ed1f7f18f6117164f370b925","name":"@artemisai/pi-droid","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"@artemisai/pi-droid","version":"0.1.0","keywords":["pi","pi-package","pi-extension","pi-coding-agent","android","adb","mobile-automation","device-automation","pi-droid","pi-agent","llm-tools","ai-agent","ai","uiautomator","screenshot","android-testing","typescript","plugin-system"],"author":{"name":"ArtemisAI"},"license":"MIT","_id":"@artemisai/pi-droid@0.1.0","maintainers":[{"name":"artemisai-dev","email":"daniel@artemis-ai.ca"}],"homepage":"https://github.com/ArtemisAI/pi-droid#readme","bugs":{"url":"https://github.com/ArtemisAI/pi-droid/issues"},"pi":{"skills":["./skills"],"extensions":["./dist/index.js"]},"dist":{"shasum":"127671b198209aa82ff5f16ed31a6d60dc741e85","tarball":"https://registry.npmjs.org/@artemisai/pi-droid/-/pi-droid-0.1.0.tgz","fileCount":134,"integrity":"sha512-70lzly714ClyA7x27jXHleXiFYiK5ShAGtnELCov433i2yCJU9Ldv32HGZ1gURiZ6jXMmEyPi0ONU9krKl+ZCg==","signatures":[{"sig":"MEYCIQC9FSVV+VcFpmsIPXOszX5C+87bEYGZNcvlEsDKwBTKuQIhAJ8XozyJsOyiWt+8KNEH+oYE3VOOcuRv2TrTQ1Q36SZy","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":507496},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"funding":"https://github.com/sponsors/ArtemisAI","gitHead":"c00f731fa40a9e6a48a1ce160f5f3b2e85de06b5","private":false,"scripts":{"dev":"pi -e ./src/index.ts","lint":"tsc --noEmit","test":"vitest run","build":"tsc","test:ci":"vitest run tests/adb/ tests/plugins/ tests/notifications/ tests/tools/ tests/integration/extension-load.test.ts tests/integration/sandbox-install.test.ts","prebuild":"rm -rf dist","test:unit":"vitest run tests/adb/ tests/plugins/ tests/notifications/ tests/tools/","test:watch":"vitest","test:device":"vitest run tests/integration/device-e2e.test.ts tests/integration/agent-device.test.ts","prepublishOnly":"npm run build && npm run test:ci","test:integration":"vitest run tests/integration/"},"_npmUser":{"name":"artemisai-dev","email":"daniel@artemis-ai.ca"},"repository":{"url":"git+https://github.com/ArtemisAI/pi-droid.git","type":"git"},"_npmVersion":"10.8.2","description":"36 LLM tools for AI agents to control Android devices via ADB — annotated screenshots, plugin system, multi-device support","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","vitest":"^3.1.1","typescript":"^5.6.0","@types/node":"^22.0.0","@sinclair/typebox":"^0.34.0","@mariozechner/pi-ai":"^0.66.0","@marcfargas/pi-test-harness":"^0.5.0","@mariozechner/pi-agent-core":"^0.66.0","@mariozechner/pi-coding-agent":"^0.66.0"},"peerDependencies":{"@sinclair/typebox":"*","@mariozechner/pi-ai":"*","@mariozechner/pi-agent-core":"*","@mariozechner/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-droid_0.1.0_1776101057785_0.6146487095835367","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Renamed to pi-droid — run: pi install pi-droid"},"0.1.1":{"name":"@artemisai/pi-droid","version":"0.1.1","keywords":["pi","pi-package","pi-extension","pi-coding-agent","android","adb","mobile-automation","device-automation","pi-droid","pi-agent","llm-tools","ai-agent","ai","uiautomator","screenshot","android-testing","testing","typescript","plugin-system","phone","mobile","ui-automation"],"author":{"name":"ArtemisAI"},"license":"MIT","_id":"@artemisai/pi-droid@0.1.1","maintainers":[{"name":"artemisai-dev","email":"daniel@artemis-ai.ca"}],"homepage":"https://github.com/ArtemisAI/pi-droid#readme","bugs":{"url":"https://github.com/ArtemisAI/pi-droid/issues"},"pi":{"skills":["./skills"],"extensions":["./dist/index.js"]},"dist":{"shasum":"d680b7c6e8d359ea8d6109466a1c32f4d2f2dc36","tarball":"https://registry.npmjs.org/@artemisai/pi-droid/-/pi-droid-0.1.1.tgz","fileCount":134,"integrity":"sha512-LA5KTpL0lyk7iHP13g8EY1GRt9+R8YvRXbISX37EzleZT72/HuRrOO/oQF/zujDampeQ0hnV9X1qIPELt8L5eg==","signatures":[{"sig":"MEUCICVnZda3z8LBch/RxMhnNA9y4QXr5LVM54RTNywGjEH3AiEApQnnmwUZRMOlAbRpTN0qTeWyriHe86Uh3bro5V5tA9A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":507581},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"funding":"https://github.com/sponsors/ArtemisAI","gitHead":"af4eb334bcc8ceed661184f192305a6c56b23a45","private":false,"scripts":{"dev":"pi -e ./src/index.ts","lint":"tsc --noEmit","test":"vitest run","build":"tsc","test:ci":"vitest run tests/adb/ tests/plugins/ tests/notifications/ tests/tools/ tests/integration/extension-load.test.ts tests/integration/sandbox-install.test.ts","prebuild":"rm -rf dist","test:unit":"vitest run tests/adb/ tests/plugins/ tests/notifications/ tests/tools/","test:watch":"vitest","test:device":"vitest run tests/integration/device-e2e.test.ts tests/integration/agent-device.test.ts","prepublishOnly":"npm run build && npm run test:ci","test:integration":"vitest run tests/integration/"},"_npmUser":{"name":"artemisai-dev","email":"daniel@artemis-ai.ca"},"repository":{"url":"git+https://github.com/ArtemisAI/pi-droid.git","type":"git"},"_npmVersion":"10.8.2","description":"Android phone control for pi-agent — 36 tools to see, touch, and automate any device via ADB","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","vitest":"^3.1.1","typescript":"^5.6.0","@types/node":"^22.0.0","@sinclair/typebox":"^0.34.0","@mariozechner/pi-ai":"^0.66.0","@marcfargas/pi-test-harness":"^0.5.0","@mariozechner/pi-agent-core":"^0.66.0","@mariozechner/pi-coding-agent":"^0.66.0"},"peerDependencies":{"@sinclair/typebox":"*","@mariozechner/pi-ai":"*","@mariozechner/pi-agent-core":"*","@mariozechner/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-droid_0.1.1_1776102376059_0.8471352621529982","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Renamed to pi-droid — run: pi install pi-droid"},"0.1.2":{"name":"@artemisai/pi-droid","version":"0.1.2","keywords":["pi","pi-package","pi-extension","pi-coding-agent","android","adb","mobile-automation","device-automation","pi-droid","pi-agent","llm-tools","ai-agent","ai","uiautomator","screenshot","android-testing","testing","typescript","plugin-system","phone","mobile","ui-automation"],"author":{"name":"ArtemisAI"},"license":"MIT","_id":"@artemisai/pi-droid@0.1.2","maintainers":[{"name":"artemisai-dev","email":"daniel@artemis-ai.ca"}],"homepage":"https://github.com/ArtemisAI/pi-droid#readme","bugs":{"url":"https://github.com/ArtemisAI/pi-droid/issues"},"pi":{"skills":["./skills"],"extensions":["./dist/index.js"]},"dist":{"shasum":"8c86c34b18bdb065b7c84152f0a982db0669a4a5","tarball":"https://registry.npmjs.org/@artemisai/pi-droid/-/pi-droid-0.1.2.tgz","fileCount":134,"integrity":"sha512-AFhYc+5DPhdTwvQn26jV9pQ0tDgaK6aHbL1XOwOQF53mbD2BNXPc9ZZbV7LfObc+vgN/Udfu/wEQOadcSCDXRA==","signatures":[{"sig":"MEUCIQC4y/1Oxy21sQ/SL+eLbpTDITBCRjyocOyfnoCq5y0D3gIgHAvMxJJwX3FMRvsVrVA0a87dOAAzcS8MRP3kMAXo3hk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":507744},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"funding":"https://github.com/sponsors/ArtemisAI","gitHead":"2f88fec86472cee41e21fd4ae70c4c6ce4e008a2","private":false,"scripts":{"dev":"pi -e ./src/index.ts","lint":"tsc --noEmit","test":"vitest run","build":"tsc","test:ci":"vitest run tests/adb/ tests/plugins/ tests/notifications/ tests/tools/ tests/integration/extension-load.test.ts tests/integration/sandbox-install.test.ts","prebuild":"rm -rf dist","test:unit":"vitest run tests/adb/ tests/plugins/ tests/notifications/ tests/tools/","test:watch":"vitest","test:device":"vitest run tests/integration/device-e2e.test.ts tests/integration/agent-device.test.ts","prepublishOnly":"npm run build && npm run test:ci","test:integration":"vitest run tests/integration/"},"_npmUser":{"name":"artemisai-dev","email":"daniel@artemis-ai.ca"},"repository":{"url":"git+https://github.com/ArtemisAI/pi-droid.git","type":"git"},"_npmVersion":"10.8.2","description":"Android phone control for pi-agent — 36 tools to see, touch, and automate any device via ADB","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","vitest":"^3.1.1","typescript":"^5.6.0","@types/node":"^22.0.0","@sinclair/typebox":"^0.34.0","@mariozechner/pi-ai":"^0.66.0","@marcfargas/pi-test-harness":"^0.5.0","@mariozechner/pi-agent-core":"^0.66.0","@mariozechner/pi-coding-agent":"^0.66.0"},"peerDependencies":{"@sinclair/typebox":"*","@mariozechner/pi-ai":"*","@mariozechner/pi-agent-core":"*","@mariozechner/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-droid_0.1.2_1776106514015_0.4509971602638203","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Renamed to pi-droid — run: pi install pi-droid"},"0.1.3":{"name":"@artemisai/pi-droid","version":"0.1.3","keywords":["pi","pi-package","pi-extension","pi-coding-agent","android","adb","mobile-automation","device-automation","pi-droid","pi-agent","llm-tools","ai-agent","ai","uiautomator","screenshot","android-testing","testing","typescript","plugin-system","phone","mobile","ui-automation"],"author":{"name":"ArtemisAI"},"license":"MIT","_id":"@artemisai/pi-droid@0.1.3","maintainers":[{"name":"artemisai-dev","email":"daniel@artemis-ai.ca"}],"homepage":"https://github.com/ArtemisAI/pi-droid#readme","bugs":{"url":"https://github.com/ArtemisAI/pi-droid/issues"},"pi":{"image":"https://raw.githubusercontent.com/ArtemisAI/pi-droid/main/banner.jpeg","skills":["./skills"],"extensions":["./dist/index.js"]},"dist":{"shasum":"002efffdf8bd0ee9d45e3fff5ec1716649aa0b7f","tarball":"https://registry.npmjs.org/@artemisai/pi-droid/-/pi-droid-0.1.3.tgz","fileCount":134,"integrity":"sha512-z9K6QEmAeCWbxTXeTJtOekWFleaojoTdq1kFGA/OhTJcWDVmsBIdKgnbERDplD0Gc6mBdzCC/dzTbkwXx6sKjQ==","signatures":[{"sig":"MEYCIQDk3s8DWVL31vxPDv+hSn6KmMNYTXDw4hZH5HliL/8CpAIhALTS7vW/vwSnsigtbp/cIiteWlrieVA0QZ95LoKk4zgA","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":507830},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"funding":"https://github.com/sponsors/ArtemisAI","gitHead":"8003a149e4a4c478ee9af8afde817452956eb1de","private":false,"scripts":{"dev":"pi -e ./src/index.ts","lint":"tsc --noEmit","test":"vitest run","build":"tsc","test:ci":"vitest run tests/adb/ tests/plugins/ tests/notifications/ tests/tools/ tests/integration/extension-load.test.ts tests/integration/sandbox-install.test.ts","prebuild":"rm -rf dist","test:unit":"vitest run tests/adb/ tests/plugins/ tests/notifications/ tests/tools/","test:watch":"vitest","test:device":"vitest run tests/integration/device-e2e.test.ts tests/integration/agent-device.test.ts","prepublishOnly":"npm run build && npm run test:ci","test:integration":"vitest run tests/integration/"},"_npmUser":{"name":"artemisai-dev","email":"daniel@artemis-ai.ca"},"repository":{"url":"git+https://github.com/ArtemisAI/pi-droid.git","type":"git"},"_npmVersion":"10.8.2","description":"Android phone control for pi-agent — 36 tools to see, touch, and automate any device via ADB","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","vitest":"^3.1.1","typescript":"^5.6.0","@types/node":"^22.0.0","@sinclair/typebox":"^0.34.0","@mariozechner/pi-ai":"^0.66.0","@marcfargas/pi-test-harness":"^0.5.0","@mariozechner/pi-agent-core":"^0.66.0","@mariozechner/pi-coding-agent":"^0.66.0"},"peerDependencies":{"@sinclair/typebox":"*","@mariozechner/pi-ai":"*","@mariozechner/pi-agent-core":"*","@mariozechner/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-droid_0.1.3_1776108202322_0.4507731307084879","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Renamed to pi-droid — run: pi install pi-droid"}},"time":{"created":"2026-04-13T17:24:17.699Z","modified":"2026-04-14T16:28:34.260Z","0.1.0":"2026-04-13T17:24:17.993Z","0.1.1":"2026-04-13T17:46:16.256Z","0.1.2":"2026-04-13T18:55:14.197Z","0.1.3":"2026-04-13T19:23:22.523Z"},"bugs":{"url":"https://github.com/ArtemisAI/pi-droid/issues"},"author":{"name":"ArtemisAI"},"license":"MIT","homepage":"https://github.com/ArtemisAI/pi-droid#readme","keywords":["pi","pi-package","pi-extension","pi-coding-agent","android","adb","mobile-automation","device-automation","pi-droid","pi-agent","llm-tools","ai-agent","ai","uiautomator","screenshot","android-testing","testing","typescript","plugin-system","phone","mobile","ui-automation"],"repository":{"url":"git+https://github.com/ArtemisAI/pi-droid.git","type":"git"},"description":"Android phone control for pi-agent — 36 tools to see, touch, and automate any device via ADB","maintainers":[{"name":"artemisai-dev","email":"daniel@artemis-ai.ca"}],"readme":"# Pi-Droid\n\n![Pi-Droid](./banner.jpeg)\n\n**Give your AI agent hands on an Android phone.**\n\n```bash\npi install npm:@artemisai/pi-droid\n```\n\nPi-Droid is a [pi-agent](https://github.com/badlogic/pi-mono) extension that gives AI agents direct, real-time control over Android devices via ADB. Annotated screenshots with numbered element indices let the agent tap, swipe, and type without guessing pixel coordinates — works on any screen size, any device.\n\n[![npm version](https://img.shields.io/npm/v/@artemisai/pi-droid)](https://www.npmjs.com/package/@artemisai/pi-droid)\n[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)\n[![tests](https://img.shields.io/badge/tests-473%2B%20passing-brightgreen)]()\n[![latest release](https://img.shields.io/github/v/release/ArtemisAI/pi-droid)](https://github.com/ArtemisAI/pi-droid/releases/latest)\n\n---\n\n## What it does\n\n| Category | Tools | Highlights |\n|----------|-------|------------|\n| **See** | 6 perception tools | Annotated screenshots with numbered indices, raw UI tree, OCR fallback |\n| **Touch** | 5 input tools | Tap by text/ID/coords, type with clear-first, swipe, scroll, key events |\n| **Navigate** | 3 app tools | Launch/stop apps, wait for elements, wait for activities |\n| **System** | 6 system tools | Battery, settings, processes, logcat, shell, APK install |\n| **Manage** | 3 device tools | Multi-device registry, preflight checks, WiFi ADB |\n| **Lock** | 4 lock tools | Query/set/clear PIN and pattern locks |\n| **Record** | 2 recording tools | Screen recording, gesture macro record/save/replay |\n| **Automate** | 3 automation tools | Wake+unlock, find-and-tap with scrolling, scroll-until-found |\n| **Extend** | 4 plugin tools | Discover capabilities, run plugin actions, health check, heartbeat cycle |\n\n**36 tools total**, organized into 4 skills that scope tool sets for focused agent behavior.\n\n---\n\n## Prerequisites\n\n| Requirement | Notes |\n|-------------|-------|\n| **Node.js** >= 18 | ESM support required |\n| **ADB** on PATH | `adb devices` should list your device |\n| **Android device** | USB debugging enabled, USB or WiFi connected |\n| **[ADBKeyboard](https://github.com/senzhk/ADBKeyboard)** | Required for Unicode text input via `android_type` |\n| **Tesseract OCR** *(optional)* | Only needed for `android_ocr` tool |\n\n---\n\n## Installation\n\n```bash\npi install npm:@artemisai/pi-droid\n```\n\nSet your device serial (optional if only one device is connected):\n\n```bash\nexport ANDROID_SERIAL=your_device_serial\n```\n\n### Verify\n\n```bash\nnpx tsx run.mts screen\n```\n\n### Development\n\n```bash\ngit clone https://github.com/ArtemisAI/pi-droid.git\ncd pi-droid\nnpm install\nnpm run build\nnpm test\n```\n\n---\n\n## Tool Reference\n\n### Perception (6 tools)\n\n| Tool | Description |\n|------|-------------|\n| `android_look` | Annotated screenshot with numbered element index — primary perception tool |\n| `android_screenshot` | Raw screenshot — use for failure diagnosis only |\n| `android_ui_dump` | Raw UI tree XML for full element hierarchy |\n| `android_ocr` | Tesseract OCR on current screen or saved screenshot |\n| `android_observe` | Continuous screen state observation |\n| `android_screen_state` | Current activity, package, orientation, lock state as JSON |\n\n### Input (5 tools)\n\n| Tool | Description |\n|------|-------------|\n| `android_tap` | Tap by coordinates, text match, or resource ID; supports long press |\n| `android_type` | Type text into the focused field; optional `clear_first` to replace |\n| `android_swipe` | Swipe between two coordinates with configurable duration |\n| `android_scroll` | Scroll up or down on the current screen |\n| `android_key` | Press a key: `back`, `home`, `enter`, `tab`, or any `KEYCODE_*` |\n\n### App and Navigation (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `android_app` | Launch, stop, or check status of an app by package name |\n| `android_wait` | Wait for an element to appear (by text or resource ID) with timeout |\n| `android_wait_activity` | Wait for a specific activity to reach the foreground |\n\n### System (6 tools)\n\n| Tool | Description |\n|------|-------------|\n| `android_device_info` | Battery, network, and hardware info |\n| `android_settings` | Read/write system settings (WiFi, Bluetooth, brightness, volume, etc.) |\n| `android_processes` | List running processes, kill by PID or name |\n| `android_logcat` | Capture, search, and clear logcat |\n| `android_shell` | Execute arbitrary ADB shell commands |\n| `android_install` | Install/uninstall APKs, check package versions |\n\n### Device Management (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `android_devices` | List connected devices, register/unregister, set active device |\n| `android_preflight` | Run device readiness checks (ADB, screen, battery, etc.) |\n| `android_wifi` | Connect/disconnect WiFi ADB, auto-discover devices |\n\n### Lock Management (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `android_lock_status` | Query current lock state and type |\n| `android_lock_clear` | Remove existing lock |\n| `android_lock_set_pattern` | Set a pattern lock |\n| `android_lock_set_pin` | Set a PIN lock |\n\n### Recording and Macros (2 tools)\n\n| Tool | Description |\n|------|-------------|\n| `android_record` | Start/stop screen recording, pull recordings |\n| `android_macro` | Record, save, load, and replay gesture macros |\n\n### Automation (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `android_ensure_ready` | Wake screen, unlock, dismiss overlays — call before any automation |\n| `android_find_and_tap` | Search UI tree for element and tap it; retries with scrolling |\n| `android_scroll_find` | Scroll until an element appears, then return it |\n\n### Plugin System (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `android_skills` | Discover all loaded plugin capabilities and parameters |\n| `android_plugin_action` | Execute a plugin action with approval gates for sensitive operations |\n| `android_plugin_status` | Get health status of all loaded plugins |\n| `android_plugin_cycle` | Run a plugin's autonomous heartbeat cycle |\n\n---\n\n## Skills\n\nPi-Droid defines four skills that scope tool sets for focused agent behavior. Skills are discovered automatically by pi-agent's package manager.\n\n| Skill | Description | Key Tools |\n|-------|-------------|-----------|\n| `android-screen` | Perceive device state | `look`, `screen_state`, `screenshot`, `ui_dump`, `ocr`, `observe` |\n| `android-interact` | Perform actions on the device | `tap`, `type`, `swipe`, `scroll`, `key`, `app` |\n| `android-automate` | High-level automation sequences | `ensure_ready`, `find_and_tap`, `scroll_find`, `wait`, `wait_activity`, `preflight` |\n| `android-plugin` | Manage and execute app plugins | `skills`, `plugin_action`, `plugin_status`, `plugin_cycle` |\n\n---\n\n## Plugin System\n\nPi-Droid's plugin system lets you add app-specific automation behind a standard interface. Plugins can declare approval gates for sensitive actions (sending messages, making purchases, posting content).\n\n### Building a plugin\n\nExtend `CliPlugin` for CLI-backed apps, or implement `PiDroidPlugin` for full control:\n\n```typescript\nimport { CliPlugin } from \"@artemisai/pi-droid\";\n\nexport class WeatherPlugin extends CliPlugin {\n  name = \"weather\";\n  // ...\n}\n```\n\n### Loading plugins\n\nPlugins are configured in `config/default.json` and loaded automatically on session start:\n\n```json\n{\n  \"plugins\": {\n    \"weather\": {\n      \"enabled\": true,\n      \"package\": \"@example/pi-droid-weather\"\n    }\n  }\n}\n```\n\nDistribute plugins as npm packages. See [PLUGINS.md](./PLUGINS.md) for the full plugin development guide, manifest schema, and marketplace integration.\n\n---\n\n## Configuration\n\nPi-Droid reads configuration from `config/default.json`:\n\n```json\n{\n  \"adb\": {\n    \"serial\": \"your_device_serial\"\n  },\n  \"plugins\": {},\n  \"routing\": {}\n}\n```\n\n| Key | Purpose |\n|-----|---------|\n| `adb.serial` | Device serial (overridden by `ANDROID_SERIAL` env var) |\n| `plugins` | Plugin configurations keyed by name |\n| `routing` | Input router settings for deterministic action dispatch |\n\nEnvironment variables:\n\n| Variable | Purpose |\n|----------|---------|\n| `ANDROID_SERIAL` | Target device serial (takes precedence over config) |\n\n---\n\n## Programmatic Usage\n\nPi-Droid exports its full ADB layer for use in custom automation scripts, external plugins, or standalone tools:\n\n```typescript\nimport {\n  Device,\n  tap, swipe, typeText, keyEvent,\n  takeScreenshot, annotatedScreenshot,\n  getScreenState, waitForActivity,\n  launchApp, stopApp,\n  dumpUiTree, findElement, waitForElement,\n  ensureReady, findAndTap, scrollToFind,\n  getBatteryInfo, getDeviceInfo,\n  adbShell,\n} from \"@artemisai/pi-droid\";\n\n// Connect to a device\nconst device = await Device.connect(process.env.ANDROID_SERIAL);\n\n// Take an annotated screenshot with numbered elements\nconst annotated = await annotatedScreenshot();\n\n// Find and tap an element by text\nawait findAndTap({ text: \"Settings\" });\n\n// Wait for an activity transition\nawait waitForActivity(\"com.android.settings/.Settings\");\n\n// Run a raw ADB shell command\nconst result = await adbShell(\"dumpsys battery\");\n```\n\n### Available exports\n\n- **Device abstraction**: `Device`\n- **Command execution**: `adb`, `adbShell`, `AdbError`, `listDevices`, `isDeviceReady`\n- **Input**: `tap`, `swipe`, `typeText`, `keyEvent`, `pressBack`, `pressHome`, `pressEnter`, `scrollDown`, `scrollUp`\n- **Screen state**: `getScreenState`, `waitForActivity`, `getActivityStack`, `isKeyboardVisible`, `getOrientation`\n- **Screenshots and perception**: `takeScreenshot`, `screenshotBase64`, `annotatedScreenshot`, `dumpUiTree`, `findElements`, `findElement`, `waitForElement`\n- **App management**: `launchApp`, `stopApp`, `getAppInfo`, `listPackages`, `wakeScreen`, `isScreenOn`\n- **Monitoring**: `getBatteryInfo`, `getNetworkInfo`, `getDeviceInfo`, `isScreenLocked`, `getRunningApps`\n- **Automation**: `ensureReady`, `findAndTap`, `scrollToFind`, `DefaultStuckDetector`, `createTaskBudget`\n- **OCR**: `runOcrOnImage`, `runOcrOnCurrentScreen`\n- **Plugin system**: `PluginManager`, `CliPlugin`, `TelegramPlugin`, `ApprovalQueue`\n- **Types**: `AdbExecOptions`, `UIElement`, `Bounds`, `ElementSelector`, `StuckEvent`, and more\n\n---\n\n## Development\n\n```bash\nnpm install            # Install dependencies\nnpm run build          # Compile TypeScript\nnpm run lint           # Type-check without emitting\nnpm test               # Run all tests (473+)\nnpm run test:unit      # Unit tests only (mocked ADB)\nnpm run test:ci        # CI-safe subset (unit + sandbox integration)\nnpm run test:integration # All integration tests\nnpm run test:device    # Full suite including device E2E\nnpm run dev            # Development mode (load as pi extension)\n```\n\n### Project structure\n\n```\nsrc/\n  index.ts          Extension entry point\n  adb/              ADB primitives (app-agnostic, 28 modules)\n  tools/            LLM tool registrations\n  plugins/          Plugin system (loader, CLI base class, marketplace)\n  notifications/    Notification channels and approval queues\nskills/             Skill definitions (scoped tool sets)\ntests/              473+ tests mirroring src/ structure\nconfig/             Default configuration\n```\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for development guidelines, coding standards, and the PR checklist.\n\n## Security\n\nSee [SECURITY.md](./SECURITY.md) for vulnerability reporting and security considerations.\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md) for release history.\n\n## License\n\n[MIT](./LICENSE) -- ArtemisAI\n","readmeFilename":"README.md"}