Claude Code + iOS Simulator

BestSelf was an e-commerce company for seven years. Physical products, Shopify, fulfillment, the whole thing. When we decided to build Helm, a focus app that blocks distracting apps on your phone, we were moving into software with zero infrastructure for it. No engineers on staff who’d shipped iOS apps before. No QA process. No one whose job it was to find bugs before users did.

That job fell to me.

What that looked like in practice: build something, open the simulator, poke around, try the flow a few times, decide it seemed fine, move on. Repeat for every change. Except Helm isn’t a todo app. It reaches into iOS and controls what you can access on your own phone. If something breaks, a user might get locked out, or the blocking might not trigger when it should. High stakes, lots of states, and no one checking any of it except me.

I didn’t learn about this until December, after Helm was mostly built. There’s an MCP server that connects Claude Code directly to your iOS simulator. Claude can tap, swipe, read the screen, and run a test pass without you lifting a finger. I’m writing this now because the next time I build an app, this is getting set up on day one. If you’re building anything with a UI and doing your own manual testing, same goes for you.

What actually changes

The problem with testing your own app isn’t effort. It’s that you know too much. You built it, so you use it the way you intended it to work. You test the happy path. You find maybe half of what’s actually broken.

When you give Claude access to your iOS simulator, it becomes your QA engineer. It doesn’t know how the app is supposed to work, so it looks at what’s actually on screen. It reads the accessibility tree, taps through flows, and reports what it finds. Not what you hoped it would find.

That covers bugs. The more underrated part is UX feedback. Claude can tell you the button label is ambiguous. That a flow requires three more taps than it should. That an error state gives the user no way out. You get a bug report and a design review at the same time, from something looking at your app completely fresh.

The specific workflow this changes is verification. Before: fix a bug, open the simulator, navigate to the screen, manually confirm it’s fixed, move on. Multiply that by every bug in a complex app. After: fix it, tell Claude to check it, move on. You stay in the decisions. Claude handles the confirmation.

Some things still require manual testing on a physical device. For Helm, actual app blocking has to be tested on real hardware, that’s just the nature of what it does. But we have a dev mode that exposes those flows in the simulator. Claude does a full first pass there. The physical device testing becomes the final check, not the entire process.

The setup

You need macOS, Xcode with iOS simulators, and Homebrew. Budget 15 minutes.

Step 1: install IDB

IDB is Facebook’s iOS Development Bridge. It gives Claude a clean interface for tapping, swiping, and reading what’s on screen. Things the standard simulator tooling doesn’t expose cleanly.

brew tap facebook/fb
brew install idb-companion
pip3 install fb-idb

If you’re on Python 3.11 or later using the system interpreter, add --break-system-packages to the pip command.

Verify it worked: run idb list-targets and your simulators should appear.

Step 2: add the MCP server to Claude Code

claude mcp add ios-simulator npx ios-simulator-mcp

One command. Claude Code now has access to your simulator.

Step 3: verify the connection

Open Claude Code and run /mcp. Navigate to ios-simulator. You’ll see the tools: ui_tap, ui_swipe, screenshot, launch_app, and a couple of accessibility describe tools for reading what’s on screen. If they’re there, you’re connected.

Teaching Claude your app

The tools give Claude access. What you put in CLAUDE.md gives Claude context. Add a section like this:

## iOS simulator testing

When I ask you to test a feature or verify a fix:

1. Build the app and wait for success
2. Launch in simulator using launch_app
3. Navigate to the feature using ui_tap and ui_swipe
4. Read the screen state using the accessibility describe tools
5. Screenshot the result
6. Report what you found: bugs, anything that looks off, UX friction

When something looks wrong: read the accessibility tree, compare
what's there to what should be there, screenshot it, suggest a fix.

You can add specific coordinates for your tab bar, common navigation patterns, key flows. The more you document, the better Claude gets at testing your specific app. Every flow you describe is context it carries forward.

If something isn’t working

IDB isn’t connecting to the simulator. Make sure a simulator is actually booted before you run anything. Open Xcode, go to the simulator, boot a device. Then run idb list-targets again. IDB needs a running target.

pip3 install fb-idb fails on Python 3.12. Apple’s system Python is locked down. Run pip3 install fb-idb --break-system-packages or install Python via Homebrew and use that instead.

Claude Code doesn’t show the ios-simulator tools in /mcp. Quit Claude Code completely and reopen it. MCP servers are loaded at startup. If you added the server while Claude Code was already running, it won’t appear until you restart.

Claude taps the wrong place. Coordinates in the simulator shift depending on viewport size. If Claude is consistently missing elements, tell it to use the accessibility describe tools to read element positions before tapping, rather than using hardcoded coordinates from your CLAUDE.md.

The app crashes on launch in the simulator. This is usually a code signing or entitlements issue with your dev build, not an IDB problem. Check your build scheme. For Helm specifically, the Screen Time API entitlements behave differently in the simulator than on device, which is exactly why we have a dev mode that exposes those flows differently.

What I wish I’d known earlier

We built Helm the hard way. Manual testing, me in the loop for every verification, no systematic process. We shipped it, it works, I’m proud of it. But there was a stretch early on where things weren’t working correctly and confirming each fix was exhausting. Fix it, check it, move on, repeat.

This tool existed. I just didn’t know about it until after.

If you’re an operator building your first software product, or a solo founder who’s never had to think about QA before: set this up before you write your first line of app code. You don’t need a QA team. You need Claude with eyes on your simulator, a CLAUDE.md that explains how your app works, and the habit of asking it to run a first pass before you open the simulator yourself.

The physical device still matters. Some things you’ll always test manually. But that becomes the final check, not the whole process.