io.github.pooriaarab/agentic-device

agentic-device

npm package · CLI · Library · Safety · Limits

agentic-device is a TypeScript library, CLI, and MCP server for driving phones you own — an iPhone through WebDriverAgent or an ESP32 HID bridge — so an agent can run setup-oriented UI actions and queue auditable phone-posting tasks. It is a consent-first device pack: actions dry-run by default and anything that needs a human (passcode, CAPTCHA, verification code) stops with needs-human instead of faking progress.

Install

npm install agentic-device

Requires Node.js and the published dist/ build. Two runtime dependencies: the MCP SDK and zod.

Post your first task

agentic-device device register --udid MY_PHONE_UDID --label "My iPhone" --connection simulator
agentic-device device action --udid MY_PHONE_UDID --action '{"type":"home"}'
agentic-device device post-task --udid MY_PHONE_UDID --platform instagram --text "Ship day"
agentic-device device queue

device action and post-task are dry runs until you pass --execute, and device action stays a review gate even then: the run reports what the driver did or the VendorError it hit.

CLI

agentic-device device register --udid <id> --label <label> --connection <wda|esp32-hid|simulator>
agentic-device device list
agentic-device device action --udid <id> --action <json> [--execute]
agentic-device device post-task --udid <id> --platform <name> --text <text> [--media <path>]
agentic-device device queue [--claim|--complete|--fail <task-id>]
agentic-device costs
agentic-device mcp

Library

import { DeviceRegistry, SimulatorDriver, runAction } from "agentic-device";

const registry = new DeviceRegistry();
const phone = registry.register({ udid: "mine", label: "My iPhone", connectionType: "simulator" });
await runAction(phone, new SimulatorDriver(), { type: "home" }); // dry run

MCP server

agentic-device mcp (or npx agentic-device-mcp) serves the same registry, queue, drivers, and cost report as tools on stdio, so a host such as Claude Code or Cursor can register a device, preview an action, and read the task queue.

Use cases

• A support agent queues a product-announcement post for a device on your desk and you approve the run.
• A QA agent drives its own simulator through an app's onboarding to capture screenshots.
• A posting pipeline records each device task as an auditable queue entry instead of an untracked script.

Alternatives and related tools

• Appium is the general mobile-automation framework; WebDriverAgent is its iOS driver, and agentic-device speaks the same protocol for the posting-task subset.
• ESP32-BLE-Keyboard is the reference firmware for the Bluetooth-HID path.
• Full device-farm products (BrowserStack App Automate, Firebase Test Lab) rent you devices at scale; this pack is for the phones on your own desk.

Safety

• Register only your own phones by UDID.
• device action is a dry run by default; pass --execute only after review.
• humanCheckpoint always returns needs-human for passcode, CAPTCHA, and verification-code steps — the pack never bypasses a platform check.
• Drivers surface failures as VendorError; they never report failed hardware or network work as success.

Limits

• No passcode, CAPTCHA, two-factor, or App Store review bypass — ever.
• The WebDriverAgent path needs a reachable WDA endpoint for a physical device; simulator is the zero-hardware option.
• The posting queue is in-process by default; persist tasks in your own store for production runs.

Upstream bases

The WDA driver follows the protocol exposed by appium/WebDriverAgent. The ESP32 HID path is designed around ESP32-BLE-Keyboard. These integrations are for owner-operated devices only.

License

MIT