{"id":46869170,"url":"https://github.com/zemse/agent-ios","last_synced_at":"2026-03-10T19:33:32.520Z","repository":{"id":333088223,"uuid":"1135902709","full_name":"zemse/agent-ios","owner":"zemse","description":"iOS automation CLI for AI agents","archived":false,"fork":false,"pushed_at":"2026-01-17T07:17:26.000Z","size":48,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-17T18:19:20.998Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zemse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-16T18:55:43.000Z","updated_at":"2026-01-17T07:17:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zemse/agent-ios","commit_stats":null,"previous_names":["zemse/agent-ios"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zemse/agent-ios","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zemse%2Fagent-ios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zemse%2Fagent-ios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zemse%2Fagent-ios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zemse%2Fagent-ios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zemse","download_url":"https://codeload.github.com/zemse/agent-ios/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zemse%2Fagent-ios/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30350113,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T15:55:29.454Z","status":"ssl_error","status_checked_at":"2026-03-10T15:54:58.440Z","response_time":106,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-10T19:33:32.045Z","updated_at":"2026-03-10T19:33:32.500Z","avatar_url":"https://github.com/zemse.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-ios\n\nCLI for LLM-friendly iOS automation. Works with both Simulators and physical devices. Get accessibility snapshots, tap elements by reference, type text, and more.\n\n[![npm version](https://img.shields.io/npm/v/agent-ios.svg)](https://www.npmjs.com/package/agent-ios)\n\n## Install\n\n```bash\nnpm install -g agent-ios\nagent-ios setup  # Clones WebDriverAgent to ~/WebDriverAgent\n```\n\n### Requirements\n\n- macOS with Xcode + Command Line Tools\n- Node.js 18+\n\n## Quick Start\n\n```bash\n# Simulator\nagent-ios start-session --sim \"iPhone 15\"  # Boot simulator + start WDA\nagent-ios snapshot                          # Get accessibility tree with refs\nagent-ios tap @e5                           # Tap element by ref\nagent-ios type @e10 \"Hello World\"           # Type text into element\nagent-ios stop-session                      # Stop session\n\n# Physical device (connected via USB)\nagent-ios list-devices                           # See connected devices\nagent-ios start-session --device \"G's iPhone\"    # Start WDA on real device\n```\n\n## Commands\n\n### Session\n\n```bash\nagent-ios start-session [--sim \u003cname\u003e]       # Boot simulator and start WDA\nagent-ios start-session --device \u003cname|id\u003e   # Start WDA on physical device\nagent-ios stop-session                       # Stop WDA and daemon\nagent-ios status                             # Check daemon/target/WDA status\nagent-ios list-sims                          # List available simulators\nagent-ios list-devices                       # List connected physical devices\n```\n\n### App Management\n\n```bash\nagent-ios install \u003cpath\u003e       # Install .app bundle on target (simulator or device)\nagent-ios launch \u003cbundle-id\u003e   # Launch app by bundle ID\nagent-ios terminate \u003cbundle-id\u003e # Terminate app\n```\n\n### Automation\n\n```bash\nagent-ios snapshot                     # Get accessibility tree as JSON with refs\nagent-ios screenshot [--out \u003cfile\u003e]    # Take screenshot (PNG, base64 if no file)\nagent-ios tap \u003cref\u003e                    # Tap element (e.g., @e5)\nagent-ios type \u003cref\u003e \u003ctext\u003e            # Type text into element\nagent-ios clear \u003cref\u003e                  # Clear text field\nagent-ios swipe \u003cref\u003e \u003cdir\u003e            # Swipe on element (up/down/left/right)\nagent-ios wait \u003cref\u003e [--timeout \u003cms\u003e]  # Wait for element (default 10s)\n```\n\n### Alerts\n\n```bash\nagent-ios alert-accept       # Accept current alert\nagent-ios alert-dismiss      # Dismiss current alert\nagent-ios alert-button \u003ctext\u003e # Tap specific alert button\n```\n\n## Output Format\n\nAll commands return JSON:\n\n```json\n{\"success\": true, \"data\": {...}}\n{\"success\": false, \"error\": \"...\"}\n```\n\n## Snapshot Schema\n\n```json\n{\n  \"timestamp\": \"2025-01-16T10:00:00Z\",\n  \"elements\": [\n    {\n      \"ref\": \"@e1\",\n      \"type\": \"XCUIElementTypeButton\",\n      \"label\": \"Log in\",\n      \"identifier\": \"loginButton\",\n      \"value\": null,\n      \"frame\": { \"x\": 12, \"y\": 780, \"w\": 351, \"h\": 48 },\n      \"enabled\": true,\n      \"visible\": true,\n      \"children\": [\"@e2\"]\n    }\n  ],\n  \"tree\": \"@e0\",\n  \"refMap\": {\n    \"@e1\": {\n      \"type\": \"XCUIElementTypeButton\",\n      \"label\": \"Log in\",\n      \"identifier\": \"loginButton\"\n    }\n  }\n}\n```\n\n- `ref`: Opaque reference for use in commands (`tap @e1`)\n- `refMap`: Quick lookup of ref to type/label/identifier\n- `tree`: Root element ref\n- Elements are flat with `children` refs (no deep nesting)\n\n## Environment Variables\n\n| Variable            | Default            | Description                          |\n| ------------------- | ------------------ | ------------------------------------ |\n| `WDA_PATH`          | `~/WebDriverAgent` | Path to WebDriverAgent               |\n| `WDA_PORT`          | `8100`             | WDA HTTP port                        |\n| `IOS_AGENT_SESSION` | `default`          | Session name (for multiple sessions) |\n\n## Architecture\n\n```\nCLI (agent-ios) → Unix Socket → Node.js Daemon → HTTP → WebDriverAgent → iOS Simulator / Device\n```\n\nThe daemon manages WDA lifecycle and maintains element ref mappings between snapshots. For physical devices, `xcrun devicectl` is used for device discovery and app installation, while WDA is built with `platform=iOS` instead of `platform=iOS Simulator`.\n\n## Troubleshooting\n\n**WDA build slow?** First build compiles WebDriverAgent. Watch progress:\n\n```bash\ntail -f /tmp/agent-ios-wda.log\n```\n\n**Element not found?** UI changed since last snapshot. Run `snapshot` again to get fresh refs.\n\n**Simulator not booting?** Ensure Xcode CLI tools are set:\n\n```bash\nsudo xcode-select -s /Applications/Xcode.app/Contents/Developer\n```\n\n**Device not showing up?** Ensure it's connected via USB, unlocked, and trusted. Check with:\n\n```bash\nxcrun devicectl list devices\n```\n\n**WDA fails on device?** You may need to configure code signing for WebDriverAgent. Open `WebDriverAgent.xcodeproj` in Xcode, select the `WebDriverAgentRunner` target, and set a valid development team.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzemse%2Fagent-ios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzemse%2Fagent-ios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzemse%2Fagent-ios/lists"}