Description

Automates interactions for iOS simulators/devices and Android emulators/devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scr...

README (SKILL.md)

Mobile Automation with agent-device

Name: Agent Device
Author: okwasniewski

For exploration, use snapshot refs. For deterministic replay, use selectors.

Start Here (Read This First)

Use this skill as a router, not a full manual.

Pick one mode:
- Normal interaction flow
- Debug/crash flow
- Replay maintenance flow
Run one canonical flow below.
Open references only if blocked.

Decision Map

No target context yet: devices -> pick target -> open.
Normal UI task: open -> snapshot -i -> press/fill -> diff snapshot -i -> close
Debug/crash: open \x3Capp> -> logs clear --restart -> reproduce -> logs path -> targeted grep
Replay drift: replay -u \x3Cpath> -> verify updated selectors

Canonical Flows

1) Normal Interaction Flow

agent-device open Settings --platform ios
agent-device snapshot -i
agent-device press @e3
agent-device diff snapshot -i
agent-device fill @e5 "test"
agent-device close

2) Debug/Crash Flow

agent-device open MyApp --platform ios
agent-device logs clear --restart
agent-device logs path

Logging is off by default. Enable only for debugging windows. logs clear --restart requires an active app session (open \x3Capp> first).

3) Replay Maintenance Flow

agent-device replay -u ./session.ad

Command Skeleton (Minimal)

Session and navigation

agent-device devices
agent-device open [app|url] [url]
agent-device open [app] --relaunch
agent-device close [app]
agent-device session list

Use boot only as fallback when open cannot find/connect to a ready target.

Snapshot and targeting

agent-device snapshot -i
agent-device diff snapshot -i
agent-device find "Sign In" click
agent-device press @e1
agent-device fill @e2 "text"
agent-device is visible 'id="anchor"'

press is canonical tap command; click is an alias.

Utilities

agent-device appstate
agent-device get text @e1
agent-device screenshot out.png
agent-device trace start
agent-device trace stop ./trace.log

Batch (when sequence is already known)

agent-device batch --steps-file /tmp/batch-steps.json --json

Guardrails (High Value Only)

Re-snapshot after UI mutations (navigation/modal/list changes).
Prefer snapshot -i; scope/depth only when needed.
Use refs for discovery, selectors for replay/assertions.
Use fill for clear-then-type semantics; use type for focused append typing.
iOS appstate is session-scoped; Android appstate is live foreground state.
iOS settings helpers are simulator-only; use faceid match|nonmatch|enroll|unenroll.
If using --save-script, prefer explicit path syntax (--save-script=flow.ad or ./flow.ad).

Security and Trust Notes

Prefer a preinstalled agent-device binary over on-demand package execution.
If install is required, pin an exact version (for example: npx --yes agent-device@\x3Cexact-version> --help).
Signing/provisioning environment variables are optional, sensitive, and only for iOS physical-device setup.
Logs/artifacts are written under ~/.agent-device; replay scripts write to explicit paths you provide.
Keep logging off unless debugging and use least-privilege/isolated environments for autonomous runs.

Common Mistakes

Mixing debug flow into normal runs (keep logs off unless debugging).
Continuing to use stale refs after screen transitions.
Using URL opens with Android --activity (unsupported combination).
Treating boot as default first step instead of fallback.

References

Usage Guidance

This skill appears coherent and matches its description, but be aware of two practical risks: (1) logs and session artifacts are written to your home (~/.agent-device) and may contain sensitive runtime data — review and redact before sharing; (2) iOS physical-device workflows may require optional signing environment variables (team ID, signing identity, provisioning profile) which are sensitive — do not populate these unless you trust the environment and understand the implications. Prefer using an already-installed, pinned agent-device binary (or a pinned npx invocation) and run automation in isolated/least-privilege environments when granting signing or CI access. If you need higher assurance, ask the publisher for an exact binary/package URL or provenance and a reproducible install artifact to audit before installing or running.

Capability Analysis

Type: OpenClaw Skill Name: agent-device Version: 1.0.1 The OpenClaw AgentSkills bundle provides a tool for mobile device automation, enabling interactions with iOS/Android devices, taking screenshots, managing logs, and running batch commands. The documentation is transparent about file system interactions (e.g., logs in `~/.agent-device`, user-specified paths for scripts/videos) and explicitly warns about handling sensitive data (e.g., log content, signing environment variables), offering security best practices like log redaction and using least-privilege environments. There is no evidence of intentional malicious behavior, data exfiltration, persistence mechanisms, or prompt injection attempts designed to subvert the agent's purpose. The instructions are clear, aligned with the stated purpose, and include genuine security advice.

Capability Assessment

✓ Purpose & Capability

The name/description match the provided SKILL.md and reference files: everything documents CLI commands for iOS/Android automation (open, snapshot, press, replay, logs, record, batch, etc.). There are no unrelated required binaries, credentials, or install steps requested by the manifest that would contradict the stated purpose.

ℹ Instruction Scope

The instructions legitimately direct the agent to run local CLI commands and to read/write session logs and replay scripts under ~/.agent-device (and platform-specific paths like ~/Library/Logs/DiagnosticReports). This is expected for a mobile automation tool, but those steps do give the skill access to potentially sensitive local app logs and artifacts; references also mention optional signing env vars for physical iOS devices. The SKILL.md does not instruct exfiltration to external endpoints.

✓ Install Mechanism

This is an instruction-only skill with no install spec or bundled code, minimizing install risk. The doc recommends preferring a preinstalled binary or pinning an exact package version if installing via npx, which is reasonable guidance.

ℹ Credentials

The manifest declares no required env vars; the docs reference optional sensitive variables (AGENT_DEVICE_IOS_TEAM_ID, AGENT_DEVICE_IOS_SIGNING_IDENTITY, AGENT_DEVICE_IOS_PROVISIONING_PROFILE, AGENT_DEVICE_APP_LOG_REDACT_PATTERNS) that are proportionate to iOS physical-device signing and log redaction. These are optional and the docs explicitly advise treating them as sensitive; still, providing signing credentials would be high privilege and should be done only when necessary.

✓ Persistence & Privilege

always is false; the skill does not request forced inclusion or modification of other skills. It documents writing logs, session state, daemon metadata, and saved replay scripts under ~/.agent-device and explicit paths you supply, which is appropriate for its function and scoped to its own data.

Version History

v1.0.1

- Added new logs and debug reference: logs-and-debug.md replaces logs.md. - Updated documentation to improve clarity, guidance, and flow structure. - "Logs" references in core docs now point to logs-and-debug.md. - Streamlined main README: more concise starting guide, clarified canonical flows, and improved guardrails section.

v1.0.0

Initial release of agent-device for automating interactions with iOS simulators/devices and Android emulators/devices. - Automates navigation, tapping, typing, scrolling, and UI data extraction on mobile devices. - Supports both agent-driven exploration (using refs) and deterministic replay scripts (using selectors). - Includes commands for device/app session management, UI snapshotting/diffing, app and system settings, interaction actions, logging, and batching of scripted steps. - Provides deterministic replay capability and script updating to handle selector drift. - Integrated settings helpers for quick toggling of common device states and biometrics (simulator only for iOS). - Detailed CLI usage examples and workflows are documented in the included SKILL.md

Metadata

Slug agent-device

Version 1.0.1

License —

All-time Installs 10

Active Installs 9

Total Versions 2

Frequently Asked Questions

What is Agent Device?

Automates interactions for iOS simulators/devices and Android emulators/devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scr... It is an AI Agent Skill for Claude Code / OpenClaw, with 1101 downloads so far.

How do I install Agent Device?

Run "/install agent-device" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Agent Device free?

Yes, Agent Device is completely free (open-source). You can download, install and use it at no cost.

Which platforms does Agent Device support?

Agent Device is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Agent Device?

It is built and maintained by Oskar Kwaśniewski (@okwasniewski); the current version is v1.0.1.

More Skills

Agent Device