← Platforms

Apple SDK — iOS & macOS

Remote debugging for native Apple apps: one Swift Package that puts your iOS or macOS build under your AI tool's control on a real device or simulator.

One package, two platform lines

The Apple SDK is a single Swift Package (OmniDebugLink) that adapts to the platform it compiles for:

• UIKit line — iOS, iPadOS, tvOS and Mac Catalyst. View-tree snapshots, screenshots via drawHierarchy, and public-API activation for clicks.
• AppKit line — macOS. The same task set, backed by NSView tree traversal and real synthesized NSEvent input.

Each build announces its own capability list on connect, so your AI tool automatically sees only the tasks the connected device can actually run. Protocol semantics align with the Flutter and Android clients: coordinates are normalized 0–1 with a top-left origin, and screenshots travel as JPEG in the __odl_file envelope.

Requirements

• Xcode 14 or newer (Swift 5.7 toolchain) on macOS.
• Deployment targets: iOS 15, macOS 12.
• A client token pair from the console — one token pair = one device seat.

Install and start

// Package.swift
.package(url: "https://github.com/omnidebuglink/omnidebuglink_apple.git", from: "0.2.0")

import OmniDebugLink

// In AppDelegate.application(_:didFinishLaunching:) / App.init():
OmniDebugLink.start("<clientToken>")

OmniDebugLink.recordLog("order placed", level: .info)
OmniDebugLink.recordError(error)

OmniDebugLink.tasks.register("my_task", { req in ["ok": true] }, description: "...")

claude mcp add --transport http odl \
  "https://api.omnidebuglink.dev/mcp"

Runtime switches

• OmniDebugLink.actionsEnabled (default true) is the master switch for write operations. Set it to false for a read-only observation mode — the change is announced on connect, and toggling it re-sends the announcement automatically (or call announce() yourself).
• recordLog(_:level:) and recordError(_) feed the read_logs buffer. Apple platforms have no historical-log API, so only content you forward is captured — plus uncaught exceptions, which are trapped best-effort before the process exits.

Built-in tasks

Available on both platform lines:

The UIKit and AppKit lines share one UI task set — introspection first, then actions:

For more on what these return and how to chain them, see UI & scene introspection and real input injection.

Addressing views

Targets are addressed by key / text / view_type substring with an index for disambiguation, and path as an exact fallback. Find and act happen atomically inside one task, so the tree cannot change between the two steps.

SwiftUI controls do not appear in the view subtree — they live in the host view's accessibilityElements, which the snapshot flattens into addressable pseudo-nodes. In practice .accessibilityIdentifier() does not land on those elements, so set .accessibilityLabel() on SwiftUI controls and locate them by text; ui_click then activates them through accessibilityActivate(), which drives SwiftUI Buttons and Toggles reliably. When the accessibility runtime is not active, results say so and hint at how to enable it.

iOS vs macOS input: an honest difference

iOS has no public touch-synthesis API — UITouch cannot be configured and UIEvent cannot be created, and private API would risk App Store rejection. The UIKit line therefore activates elements instead: ui_click and tap_screen use sendActions plus accessibilityActivate(), swipe performs programmatic scrolling on UIScrollView, and long_press approximates an activation hold. Free-form gesture injection is not possible there with public API, and each task's return value states plainly what was actually done.

macOS injects real events: NSEvents are synthesized in-process and queued through NSApp.postEvent, so clicks, drags, press-holds and key codes are routed exactly like user input — and no accessibility permission prompt is needed. (An earlier CGEvent.postToPid path was measured as ignored by AppKit, which is why the final design uses NSApp delivery.) AppKit's bottom-left coordinate space is converted to the protocol's top-left origin on the way out, so coordinates mean the same thing on both lines.

Platform maturity

Worth knowing

• Never share a token pair across devices. When a newer connection takes over the same token, the SDK receives close code 4000 and stops reconnecting permanently (a warning is logged). One token pair is one device seat, not a broadcast channel.
• Screenshots are JPEG with a budget. The base64 envelope is capped (roughly 850k characters), so the SDK first lowers JPEG quality and then downsamples rather than failing. GPU-rendered layers are not captured by the AppKit cacheDisplay path.
• Segmented controls and sliders need intent. A blind tap on a segment is silently ineffective, so ui_click infers the segment or slider value from the click x coordinate and matches segment titles; if neither is available the task refuses honestly and points at set_component.
• input_text makes the target field first responder first, otherwise a following send_key has nowhere to land.
• The SDK is released under the MIT License.