Skip to content
Back to search

simvyn

Universal mobile devtool for Agents & Humans - control iOS Simulators, Android Emulators, and real devices from a single dashboard and CLI

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pranshuchittora--simvyn/badge.svg)](/listings/pranshuchittora--simvyn)

HTML

<a href="/listings/pranshuchittora--simvyn"><img src="/api/listings/pranshuchittora--simvyn/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx simvyn

Starts the local server, opens the web dashboard in your browser, and discovers all connected simulators, emulators, and USB-connected physical devices automatically.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 419 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/assets/simvyn-icon-1024.png" width="180" alt="simvyn" />
  3. </p>
  4. <h1 align="center">simvyn</h1>
  5. <p align="center">
  6. Universal mobile devtool — control iOS Simulators, Android Emulators, and real devices from a single dashboard and CLI
  7. </p>
  8. <p align="center">
  9. <a href="https://www.npmjs.com/package/simvyn"><img src="https://img.shields.io/npm/v/simvyn?color=cb3837&logo=npm" alt="npm version" /></a>
  10. <a href="https://www.npmjs.com/package/simvyn"><img src="https://img.shields.io/npm/dm/simvyn?color=cb3837&logo=npm" alt="npm downloads" /></a>
  11. <a href="https://github.com/pranshuchittora/simvyn/actions/workflows/ci.yml"><img src="https://github.com/pranshuchittora/simvyn/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a>
  12. <a href="https://github.com/pranshuchittora/simvyn/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/simvyn?color=blue" alt="MIT License" /></a>
  13. <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/simvyn?color=5FA04E&logo=node.js&logoColor=white" alt="Node version" /></a>
  14. </p>
  15. <p align="center">
  16. <img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/assets/banner.png" alt="simvyn dashboard" />
  17. </p>
  18. <p align="center">
  19. <img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/assets/demo.gif" alt="simvyn demo" />
  20. </p>
  21. ## Table of Contents
  22. - [Quick Start](#quick-start)
  23. - [Installation](#installation)
  24. - [AI Coding Agents](#ai-coding-agents)
  25. - [Features](#features)
  26. - [Module Showcases](#module-showcases)
  27. - [Collections Guide](#collections-guide)
  28. - [CLI Reference](#cli-reference)
  29. - [How It Works](#how-it-works)
  30. - [Supported Platforms](#supported-platforms)
  31. - [Contributing](#contributing)
  32. - [Security](#security)
  33. - [License](#license)
  34. ## Quick Start
  35. ```bash
  36. npx simvyn
  37. ```
  38. Starts the local server, opens the web dashboard in your browser, and discovers all connected simulators, emulators, and USB-connected physical devices automatically.
  39. ## Installation
  40. **Global install:**
  41. ```bash
  42. npm install -g simvyn
  43. ```
  44. **One-time use (no install):**
  45. ```bash
  46. npx simvyn
  47. ```
  48. **Requirements:**
  49. - Node.js 22 (22.14.0+) or 24+
  50. - macOS (full iOS + Android support) or Linux (Android only)
  51. ## AI Coding Agents
  52. simvyn includes a portable [Agent Skill](https://github.com/pranshuchittora/simvyn/blob/main/skills/simvyn/SKILL.md) for discovering devices, running supported CLI commands, capturing screenshots, inspecting app data, and collecting bounded logs. It teaches an agent to use the CLI with explicit device IDs and platform limits. The skill uses the agent's existing terminal tool; it does not register an MCP server or new agent tools.
  53. **Pi:** the npm package is a [Pi package](https://pi.dev/packages/simvyn). Along with the skill, it adds `simvyn`, `simvyn_screenshot`, `simvyn_logs`, and `simvyn_record` tools, a `/simvyn` command that runs the dashboard, and `/simvyn-repro`, `/simvyn-screen`, and `/simvyn-logs` prompt templates. It requires Pi 0.74 or later:
  54. ```bash
  55. pi install npm:simvyn
  56. ```
  57. **Other compatible agents:** install the portable skill from GitHub, selecting your agent, and install the simvyn CLI separately:
  58. ```bash
  59. npm install -g simvyn
  60. npx skills add pranshuchittora/simvyn --skill simvyn --agent codex --yes
  61. ```
  62. The GitHub command requires these skill files to be present on the default branch; the Pi command requires the Pi resources in the published npm release. For unreleased changes, use the [local checkout instructions](https://github.com/pranshuchittora/simvyn/blob/main/docs/agents.md#test-an-unreleased-checkout).
  63. See the [agent setup and workflow guide](https://github.com/pranshuchittora/simvyn/blob/main/docs/agents.md) for the bundled launcher, supported outputs, noninteractive operation, and current limitations. A compact [documentation index](https://github.com/pranshuchittora/simvyn/blob/main/llms.txt) is also available for tools that accept documentation URLs.
  64. ## Features
  65. - **Device Management** — Discover, boot, shutdown, erase, create, and clone simulators, emulators, and physical devices with favourite pinning
  66. - **App Management** — Install, launch, terminate, uninstall apps via drag-and-drop or CLI
  67. - **Log Viewer** — Real-time streaming with level filtering, find-in-page search (Cmd+F), regex search, pagination, and export
  68. - **Location Simulation** — Set GPS coordinates, play GPX/KML routes with speed control, save favorites
  69. - **Device Settings** — Dark mode, locale, orientation, permissions, status bar overrides, accessibility presets
  70. - **Screenshots and Recording** — Capture screenshots and record screen video with history
  71. - **Deep Links** — Open URLs and custom schemes, save favorites per app
  72. - **Database Inspector** — Browse SQLite tables, run SQL queries, view SharedPreferences and NSUserDefaults
  73. - **File Browser** — Browse app sandboxes, upload/download files, edit text inline
  74. - **Push Notifications** — Compose JSON payloads, send to iOS simulators, template library
  75. - **Collections** — Bundle device actions into reusable sequences, apply to multiple devices at once
  76. - **Crash Logs** — iOS diagnostic reports and Android logcat/tombstone crashes
  77. - **Clipboard** — Read and write device clipboard contents
  78. - **Media** — Push photos and videos to device camera rolls and galleries
  79. - **Tool Settings** — Server configuration, storage management, diagnostics, and debug reports
  80. - **Real Device Support** — Connect physical Android and iOS devices via USB with automatic discovery
  81. - **Web Dashboard** — Apple Liquid Glass design with command palette, keyboard navigation
  82. - **Full CLI** — Every feature works headlessly via `simvyn <command>`
  83. ## Module Showcases
  84. ### Device Management
  85. Discover all connected iOS Simulators, Android Emulators, and USB-connected physical devices in one unified list. Boot, shutdown, and erase devices without touching Xcode or Android Studio. Create new iOS simulators by choosing a device type and runtime, or clone an existing one to quickly spin up duplicates. Physical devices appear automatically when plugged in and are grouped separately in the device selector.
  86. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/device-management.png" alt="Device Management" width="700" /></p>
  87. - List all available simulators, emulators, and physical devices across platforms
  88. - Boot, shutdown, and erase devices with one click or CLI command
  89. - Create new iOS simulators with device type and runtime selection
  90. - Clone and rename existing simulators
  91. - Pin favourite devices to the top of the device selector
  92. - Real-time device state updates via WebSocket
  93. ### App Management
  94. Install, launch, terminate, and uninstall apps on any connected device. Drag and drop IPA, APK, or iOS simulator .app bundles directly onto the dashboard. View detailed app information and clear app data without manual adb or simctl commands.
  95. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/app-management.png" alt="App Management" width="700" /></p>
  96. - Drag-and-drop IPA, APK, and iOS simulator .app installation
  97. - Launch, terminate, and uninstall apps by bundle ID
  98. - View app details including version, size, and permissions
  99. - Clear app data on Android devices
  100. - List all installed apps with search filtering
  101. ### Log Viewer
  102. Stream device logs in real time with powerful filtering. Filter by log level, search with regex patterns, and filter by process name. Use find-in-page search (Cmd+F) to highlight specific entries without hiding surrounding context. Export filtered logs for sharing or archival. Paginated history lets you scroll back through thousands of entries without performance issues.
  103. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/log-viewer.png" alt="Log Viewer" width="700" /></p>
  104. - Real-time log streaming via WebSocket
  105. - Filter by level: debug, info, warning, error, fatal
  106. - Find-in-page search (Cmd+F) with match highlighting, navigation, and counter
  107. - Regex search and process name filtering
  108. - Paginated history with virtual scrolling
  109. - Export filtered logs to file
  110. - Pause/resume log streaming while preserving state across clears
  111. ### Location
  112. Set precise GPS coordinates on any device using an interactive map or manual input. Play back GPX and KML route files with adjustable speed control. Save frequently used locations as favorites for quick access.
  113. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/location.png" alt="Location" width="700" /></p>
  114. - Interactive map with click-to-set coordinates
  115. - GPX and KML route file playback with speed control
  116. - Favorite locations saved per device
  117. - Multi-device location broadcast
  118. - Reverse geocoding for human-readable addresses
  119. ### Device Settings
  120. Toggle dark mode, change locale, rotate device orientation (Android), manage app permissions, and override status bar appearance. Apply accessibility presets to test your app under different conditions. All settings changes take effect immediately on the target device.
  121. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/device-settings.png" alt="Device Settings" width="700" /></p>
  122. - Toggle dark/light mode
  123. - Change device locale
  124. - Manage app permissions
  125. - Override status bar (time, battery, signal)
  126. - Accessibility presets (bold text, increase contrast, content size)
  127. ### Screenshots and Recording
  128. Capture screenshots and record screen video on any device. All captures are saved with timestamps and organized in a browsable history. Download or delete captures directly from the dashboard.
  129. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/screenshots-and-recordings.png" alt="Screenshots and Recording" width="700" /></p>
  130. - One-click screenshot capture
  131. - Screen recording with start/stop controls
  132. - Timestamped capture history
  133. - Download and delete captures from the dashboard
  134. ### Deep Links
  135. Open URLs and custom URI schemes on any device. Save frequently used deep links as favorites organized by app. Test your app's deep link handling without manually typing URLs into a terminal.
  136. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/deep-links.png" alt="Deep Links" width="700" /></p>
  137. - Open any URL or custom scheme on a device
  138. - Save favorite deep links per app
  139. - Link history with recent-first ordering
  140. - Works with both iOS and Android
  141. ### Database Inspector
  142. Browse SQLite databases inside any app's sandbox. View table schemas, run arbitrary SQL queries, and inspect SharedPreferences (Android) or NSUserDefaults (iOS). Edit values inline without writing scripts.
  143. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/database-inspector.png" alt="Database Inspector" width="700" /></p>
  144. - Browse SQLite tables with sortable columns
  145. - Run arbitrary SQL queries
  146. - View and edit SharedPreferences and NSUserDefaults
  147. - Inline cell editing with type detection
  148. ### File Browser
  149. Browse the sandbox file system of any installed app. Navigate directories, upload and download files, and edit text files inline. Transfer files between your machine and the device without manual adb pull/push commands.
  150. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/file-system.png" alt="File Browser" width="700" /></p>
  151. - Browse app sandbox directories
  152. - Upload and download files
  153. - Inline text file editing
  154. - Works with both iOS and Android app containers
  155. ### Push Notifications
  156. Compose JSON push notification payloads and send them to iOS simulators. Use the built-in template library as a starting point or write payloads from scratch. Real-time JSON validation highlights errors before sending.
  157. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/push-notifications.png" alt="Push Notifications" width="700" /></p>
  158. - Compose and send push payloads to iOS simulators
  159. - Built-in payload template library
  160. - Real-time JSON validation
  161. - Target specific apps by bundle ID
  162. ### Collections
  163. Create reusable sets of device actions and apply them to multiple devices at once. Collections bundle together steps like setting location, toggling dark mode, and installing an app into a single repeatable workflow. Three starter presets ship with simvyn to get you started.
  164. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/collections.png" alt="Collections" width="700" /></p>
  165. - Create, duplicate, and manage named collections
  166. - Browse categorized action catalog across all modules
  167. - Drag-and-drop step reordering
  168. - Apply to multiple devices with compatibility checking
  169. - Three built-in starter presets
  170. ### Crash Logs
  171. View iOS diagnostic reports (.ips files) and Android crash logs from logcat and tombstone dumps. Browse crash entries with timestamps and process information. Inspect full crash details without digging through device file systems.
  172. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/crash-logs.png" alt="Crash Logs" width="700" /></p>
  173. - iOS diagnostic report (.ips) parsing
  174. - Android logcat crash grouping by PID and tag
  175. - Android tombstone dump retrieval
  176. - Timestamped crash list with detail view
  177. ### Clipboard
  178. Read and write the device clipboard from the dashboard or CLI. Useful for quickly pasting test data into apps or inspecting what an app copied.
  179. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/clipboard.png" alt="Clipboard" width="700" /></p>
  180. - Read current clipboard contents
  181. - Write text to device clipboard
  182. - Works with iOS Simulators and Android Emulators
  183. ### Media
  184. Push photos and videos directly into a device's camera roll or gallery. Drop files onto the dashboard to inject them without cables, email, or cloud transfers.
  185. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/media.png" alt="Media" width="700" /></p>
  186. - Add photos and videos to device gallery via drag-and-drop
  187. - Supports large files up to 500 MB
  188. - Works with iOS Simulators and Android Emulators
  189. ### Tool Settings
  190. Configure the simvyn server, manage storage, and view diagnostics. Includes a debug report generator for filing issues.
  191. <p align="center"><img src="https://raw.githubusercontent.com/pranshuchittora/simvyn/main/docs/assets/tool-settings.png" alt="Tool Settings" width="700" /></p>
  192. - Server port, auto-open, and polling interval configuration
  193. - Storage usage overview with data wipe option
  194. - Diagnostics: Xcode version, devicectl availability, adb version
  195. - One-click debug report for bug filing
  196. ## Collections Guide
  197. Collections let you bundle multiple device actions into a reusable sequence and apply them to any combination of devices with one click.
  198. ### Creating a Collection
  199. Open the Collections panel from the sidebar. Click **New Collection** and give it a name. The collection starts empty — you'll add steps from the action catalog.
  200. ### Adding Steps
  201. Click **Add Step** to browse the categorized action catalog. Actions are organized by module — Device Settings, Location, App Management, and more. Select an action, configure its parameters inline (coordinates, bundle IDs, toggle values), and it appears in your collection. Drag steps to reorder them.
  202. ### Applying a Collection
  203. Click **Apply** to open the apply modal. Select one or more target devices from the device list. A compatibility summary shows which steps will be skipped on incompatible platforms (for example, iOS-only actions on an Android device). Press **Cmd+Enter** to execute. A live status matrix shows per-step, per-device progress in real time.
  204. ### Command Palette Integration
  205. Saved collections appear in the command palette (**Cmd+K**). Search for a collection by name and apply it directly with the device picker — no need to navigate to the Collections panel.
  206. ### Starter Collections
  207. Three built-in presets ship with simvyn:
  208. - **Dark Mode + Japanese Locale** — Enables dark mode and sets locale to Japanese
  209. - **Screenshot Setup** — Configures status bar overrides for clean App Store screenshots
  210. - **Reset Device State** — Clears location, resets settings, and erases app data
  211. ### CLI Usage
  212. ```bash
  213. simvyn collections list # List all collections
  214. simvyn collections apply <name> <devices...> # Apply a collection to devices
  215. ```
  216. ## CLI Reference
  217. Every feature is accessible from the command line. Run `simvyn` with no arguments to start the dashboard, or use any command below for headless operation.
  218. | Command | Description |
  219. | ------------------------------------------------- | ------------------------------------------ |
  220. | `simvyn` | Start the dashboard (default) |
  221. | `simvyn device list` | List all devices |
  222. | `simvyn device boot <device>` | Boot a device |
  223. | `simvyn device shutdown <device>` | Shutdown a device |
  224. | `simvyn device erase <device>` | Erase device content and settings |
  225. | `simvyn device create <name> <type> <runtime>` | Create a new iOS simulator |
  226. | `simvyn device clone <device> <name>` | Clone an iOS simulator |
  227. | `simvyn device rename <device> <name>` | Rename an iOS simulator |
  228. | `simvyn device delete <device>` | Delete an iOS simulator |
  229. | `simvyn location set <device> <lat> <lng>` | Set GPS coordinates |
  230. | `simvyn location route <device> <file>` | Play a GPX/KML route |
  231. | `simvyn location clear <device>` | Clear simulated location |
  232. | `simvyn app list <device>` | List installed apps |
  233. | `simvyn app install <device> <path>` | Install an IPA, APK, or iOS simulator .app |
  234. | `simvyn app uninstall <device> <bundle-id>` | Uninstall an app |
  235. | `simvyn app launch <device> <bundle-id>` | Launch an app |
  236. | `simvyn app terminate <device> <bundle-id>` | Terminate an app |
  237. | `simvyn app info <device> <bundle-id>` | Show app details |
  238. | `simvyn app clear-data <device> <bundle-id>` | Clear app data (Android) |
  239. | `simvyn logs <device>` | Stream device logs |
  240. | `simvyn screenshot <device>` | Capture a screenshot |
  241. | `simvyn record <device>` | Record the screen |
  242. | `simvyn link <device> <url>` | Open a deep link |
  243. | `simvyn push <device>` | Send a push notification |
  244. | `simvyn fs ls <device> <bundle-id> [path]` | List files in app sandbox |
  245. | `simvyn fs pull <device> <bundle-id> <path>` | Download a file |
  246. | `simvyn fs push <device> <bundle-id> <src> <dst>` | Upload a file |
  247. | `simvyn db list <device> <bundle-id>` | List databases |
  248. | `simvyn db query <device> <bundle-id> <db> <sql>` | Run a SQL query |
  249. | `simvyn db prefs <device> <bundle-id>` | View SharedPreferences / NSUserDefaults |
  250. | `simvyn keychain add <device> <cert>` | Add a root certificate |
  251. | `simvyn keychain reset <device>` | Reset the keychain |
  252. | `simvyn collections list` | List all collections |
  253. | `simvyn collections show <id>` | Show collection details |
  254. | `simvyn collections create <name>` | Create a new collection |
  255. | `simvyn collections delete <id>` | Delete a collection |
  256. | `simvyn collections duplicate <id>` | Duplicate a collection |
  257. | `simvyn collections apply <name> <devices...>` | Apply a collection to devices |
  258. | `simvyn settings orientation <device> <orient>` | Set device orientation (Android) |
  259. ## How It Works
  260. simvyn wraps `xcrun simctl` (iOS Simulators), `xcrun devicectl` (iOS physical devices), and `adb` (Android) behind a unified interface. No SDK required — works with any app, no code changes needed.
  261. The architecture is built around a module system where each feature (location, logs, app management, etc.) is a self-contained plugin that registers its own API routes, CLI commands, and WebSocket handlers. The web dashboard communicates with a local Fastify server over a single multiplexed WebSocket connection for real-time device state and log streaming. Features that aren't available on a particular device type are automatically disabled with clear indicators in the UI.
  262. ## Supported Platforms
  263. | Platform | iOS Simulators | iOS Devices | Android Emulators | Android Devices |
  264. | -------- | -------------- | ----------- | ----------------- | --------------- |
  265. | macOS | Yes | Limited | Yes | Yes |
  266. | Linux | No | No | Yes | Yes |
  267. ### Real Device Support
  268. Physical devices connected via USB are discovered automatically alongside simulators and emulators. The dashboard groups them into separate sections (Physical / Simulators / Emulators) and shows a toast when a device disconnects.
  269. **Android physical devices** support nearly all features — app management, deep links, logs, screenshots, database inspector, file browser, and more. A few emulator-only features (location simulation via `adb emu geo`, battery simulation) are unavailable and clearly marked in the UI.
  270. **iOS physical devices** require Xcode 15+ and use `xcrun devicectl` under the hood. Supported features include device discovery, app install/uninstall/launch/terminate, app listing, deep links, and file copy. Many features that rely on `simctl` (screenshots, screen recording, location simulation, clipboard, appearance, status bar, push notifications) are not available on physical iOS devices. Unsupported controls are disabled with tooltips explaining why. Collections automatically skip steps that don't apply to physical devices.
  271. ## Contributing
  272. Contributions are welcome — bug fixes, new modules, platform coverage, and docs alike.
  273. Start with the **[Contributing Guide](https://github.com/pranshuchittora/simvyn/blob/main/CONTRIBUTING.md)**, which covers development setup, the project layout, how to add a module, and the checks CI runs.
  274. - [Report a bug](https://github.com/pranshuchittora/simvyn/issues/new?template=bug_report.yml)
  275. - [Request a feature](https://github.com/pranshuchittora/simvyn/issues/new?template=feature_request.yml)
  276. - [Code of Conduct](https://github.com/pranshuchittora/simvyn/blob/main/CODE_OF_CONDUCT.md)
  277. - [Changelog](https://github.com/pranshuchittora/simvyn/blob/main/CHANGELOG.md)
  278. ```bash
  279. git clone https://github.com/pranshuchittora/simvyn.git
  280. cd simvyn
  281. npm install
  282. npm run dev
  283. ```
  284. ## Security
  285. simvyn is a local developer tool and is not designed to be exposed to untrusted networks.
  286. Please report vulnerabilities privately through [GitHub Security Advisories](https://github.com/pranshuchittora/simvyn/security/advisories/new) rather than as a public issue. See the [Security Policy](https://github.com/pranshuchittora/simvyn/blob/main/SECURITY.md) for scope and what to include.
  287. Every release is published to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements) via trusted publishing, so you can verify a tarball back to the commit that built it:
  288. ```bash
  289. npm audit signatures
  290. ```
  291. ## License
  292. [MIT](https://github.com/pranshuchittora/simvyn/blob/main/LICENSE) © [Pranshu Chittora](https://github.com/pranshuchittora)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.