Pepper

1# Pepper
2 
3Pepper gives AI agents eyes and hands inside iOS Simulator apps.
4 
5It 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.
6 
7https://github.com/user-attachments/assets/42ab3f1b-21f8-48e6-820f-7ca4012fb03b
8 
9*Claude navigating and inspecting [Ice Cubes](https://github.com/Dimillian/IceCubesApp) (Mastodon client) with zero source access.*
10 
11Works with Claude Code · Cursor · Claude Desktop · any [MCP](https://modelcontextprotocol.io) client
12 
13## Quickstart
14 
15Requires macOS 14+, Python 3.10+, and an iOS Simulator runtime.
16 
17```bash
18pip install pepper-ios
19pepper-ctl deploy            # inject into the frontmost simulator app
20pepper-ctl look              # see what's on screen
21```
22 
23Then ask your agent:
24 
25> "Tap through the onboarding flow and make sure every screen looks right"
26 
27That's it. The agent uses Pepper's MCP tools to see, tap, and inspect — no extra config needed.
28 
29<details>
30<summary>Other MCP clients (Cursor, Claude Desktop, etc.)</summary>
31 
32```json
33{
34  "mcpServers": {
35    "pepper": {
36      "command": "pepper-mcp"
37    }
38  }
39}
40```
41 
42</details>
43 
44<details>
45<summary>Homebrew</summary>
46 
47```bash
48brew install --HEAD skwallace36/pepper/pepper
49```
50 
51Tap: [`skwallace36/homebrew-pepper`](https://github.com/skwallace36/homebrew-pepper)
52 
53</details>
54 
55## What It Does
56 
57```
58$ pepper-ctl look
59Screen: navigation_stack  (9 interactive, 4 text)
60 
61       seg  "Trending"                       → tap text:"Trending"
62       btn  "Sheryl Weikal, Right wing tech bros: we love St..."
63                                              → tap text:"Sheryl Weikal, Right wing tech bros: we ..."
64       seg  "Settings"                       → tap text:"Settings"
65 
66$ pepper-ctl tap --text "Settings"
67Action: Tapped Settings
68Screen: navigation_stack  Title: "Settings"  (15 interactive, 3 text)
69 
70       btn  "App Icon"                       → tap text:"App Icon"
71       btn  "Display Settings"              → tap text:"Display Settings"
72       ...
73```
74 
75Every element comes with its tap command. The agent sees the screen, acts, and gets the new state back in one round trip.
76 
77### Things you can ask your agent
78 
79These work against any app — no setup beyond `deploy`.
80 
81> "Why is this list empty? Check the network request and see what the API returned"
82 
83> "What objects are holding a reference to DeviceActuationService? I think it's leaking"
84 
85> "Switch to dark mode and look for any text that's invisible against the background"
86 
87> "The login button isn't responding — check the responder chain and see what's intercepting taps"
88 
89> "Profile the scroll performance on the feed. Is anything hitching?"
90 
91> "Read what's in the keychain after logout — nothing should be left"
92 
93> "Turn off the feature flag for new-nav and make sure the old flow still works"
94 
95View 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.
96 
97## How It Works
98 
99Pepper 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.
100 
101Because 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`.
102 
103## Development
104 
105[`dylib/DYLIB.md`](dylib/DYLIB.md) — architecture and adding commands · [`tools/TOOLS.md`](tools/TOOLS.md) — MCP tool layer · [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — common issues
106