pepper-ios 0.5.0

MCP server and CLI tools for Pepper iOS simulator control

Pepper

Pepper gives AI agents eyes and hands inside iOS Simulator apps.

It injects a shared library into any running simulator app — no source changes, no SDK, no build step. Your agent sees the screen as structured data, taps buttons, inspects live objects, intercepts network calls, reads the heap, and debugs layout issues. Dylib injection requires the simulator; device support uses a different mechanism.

https://github.com/user-attachments/assets/42ab3f1b-21f8-48e6-820f-7ca4012fb03b

Claude navigating and inspecting Ice Cubes (Mastodon client) with zero source access.

Works with Claude Code · Cursor · Claude Desktop · any MCP client

Quickstart

Requires macOS 14+, Python 3.10+, and an iOS Simulator runtime.

pip install pepper-ios
pepper-ctl deploy            # inject into the frontmost simulator app
pepper-ctl look              # see what's on screen

Then ask your agent:

"Tap through the onboarding flow and make sure every screen looks right"

That's it. The agent uses Pepper's MCP tools to see, tap, and inspect — no extra config needed.

Other MCP clients (Cursor, Claude Desktop, etc.)

{
  "mcpServers": {
    "pepper": {
      "command": "pepper-mcp"
    }
  }
}

Homebrew

brew install --HEAD skwallace36/pepper/pepper

Tap: skwallace36/homebrew-pepper

What It Does

$ pepper-ctl look
Screen: navigation_stack  (9 interactive, 4 text)

       seg  "Trending"                       → tap text:"Trending"
       btn  "Sheryl Weikal, Right wing tech bros: we love St..."
                                              → tap text:"Sheryl Weikal, Right wing tech bros: we ..."
       seg  "Settings"                       → tap text:"Settings"

$ pepper-ctl tap --text "Settings"
Action: Tapped Settings
Screen: navigation_stack  Title: "Settings"  (15 interactive, 3 text)

       btn  "App Icon"                       → tap text:"App Icon"
       btn  "Display Settings"              → tap text:"Display Settings"
       ...

Every element comes with its tap command. The agent sees the screen, acts, and gets the new state back in one round trip.

Things you can ask your agent

These work against any app — no setup beyond deploy.

"Why is this list empty? Check the network request and see what the API returned"

"What objects are holding a reference to DeviceActuationService? I think it's leaking"

"Switch to dark mode and look for any text that's invisible against the background"

"The login button isn't responding — check the responder chain and see what's intercepting taps"

"Profile the scroll performance on the feed. Is anything hitching?"

"Read what's in the keychain after logout — nothing should be left"

"Turn off the feature flag for new-nav and make sure the old flow still works"

View hierarchy, network interception, heap inspection, console capture, crash logs, performance profiling, accessibility audits, constraint debugging, keychain/UserDefaults/CoreData access, locale and orientation control, feature flags, push notifications — 60+ tools in total. Parameter docs are built into every tool; your MCP client surfaces them automatically.

How It Works

Pepper uses macOS's dynamic linker (DYLD_INSERT_LIBRARIES) to load a dylib into the simulator process at launch. The dylib starts a WebSocket server on a local port. pepper-mcp connects to that WebSocket and translates MCP tool calls into commands executed inside the app.

Because it runs in-process, Pepper has access to the full view hierarchy, the ObjC runtime, live object graphs, network delegates, and the HID event system. All touch input goes through native input events (IOHIDEvent) — the same path real fingers take. No private APIs, no entitlements — just dyld.

Development

dylib/DYLIB.md — architecture and adding commands · tools/TOOLS.md — MCP tool layer · docs/TROUBLESHOOTING.md — common issues