iOS Inspector

iOS Inspector is a local desktop debugger for native iOS apps. It combines a desktop control room, a lightweight debug SDK, and agent-readable APIs so humans and coding agents can inspect app behavior without scraping the UI.

The project is focused on iOS simulator workflows first. The default path does not require host proxy routing, simulator proxy configuration, or certificate trust setup.

Features

• Native iOS debug SDK for structured logs, breadcrumbs, custom events, and URLSession network events.
• Desktop timeline for network requests, app logs, and SDK events.
• Request and response inspectors with summary, headers, query, and body views.
• Pretty JSON code viewer with syntax highlighting, line numbers, copy actions, and tree view.
• Simulator inventory, user app selection, launch, terminate, screenshots, logs, and app container file access.
• Local HTTP API and MCP server for agent workflows.

Requirements

• macOS
• Xcode with iOS Simulator support
• Node.js 20 or newer
• Optional: idb for tap/type automation

Install

npm install

Run

Start the local API and web UI:

npm run dev

Open the desktop shell during development:

npm run desktop:dev

Build the production frontend:

npm run build

Add The iOS Debug SDK

Install the local Swift package into an iOS app:

bash scripts/install-ios-inspector-sdk.sh /path/to/YourApp

Start the SDK during debug app startup:

#if DEBUG
import IOSInspectorSDK

IOSInspector.start(bundleId: Bundle.main.bundleIdentifier)
IOSInspector.log("App launched", level: .info)
#endif

Add structured events when useful:

#if DEBUG
IOSInspector.event("checkout_started", metadata: ["source": "debug"])
IOSInspector.breadcrumb("opened settings screen")
#endif

Local API

The backend runs on http://127.0.0.1:5174.

Useful endpoints:

• GET /api/agent/context
• GET /api/apps
• GET /api/events?bundleId=<bundleId>
• POST /api/events/clear
• GET /api/logs?bundleId=<bundleId>&executable=<name>
• GET /api/network/status?bundleId=<bundleId>&executable=<name>
• GET /api/screenshot
• POST /api/actions

Start the MCP server:

npm run mcp

Development

Run tests:

npm test

Run lint:

npm run lint

Build:

npm run build

Repository Structure

electron/        Electron desktop shell
scripts/         Local setup and SDK install scripts
src/             React desktop UI
swift-package/   iOS Inspector Swift package
server.mjs       Local API server
mcp-server.mjs   MCP server for agent tools

Status

iOS Inspector is early-stage software. The current focus is local simulator debugging, SDK-based logs/events/network capture, and agent-readable inspection APIs.