Want to access all premium content?
Become a paying subscriber to get access to all courses, guides like this, prompts and skills library, and $500+ worth of AI tools.
Phone Harness is a free, open-source tool that lets a coding agent read an iPhone screen and send taps and keystrokes through iPhone Mirroring. You don't need to install anything on the phone or jailbreak it.
An app can work on your laptop and still have problems on a phone. This guide has Claude Code build a small web app, open it in Safari on your iPhone, and test it with taps. You'll need Claude Code, a Mac running macOS Sequoia or later, an iPhone on the same Wi-Fi, and Python.
Step 1: Install Phone Harness. Have Claude handle the setup.
Step 2: Connect your phone. Pair iPhone Mirroring and grant permissions.
Step 3: Check the connection. Confirm the tool can read the screen.
Step 4: Build the app. Serve a test page from your Mac.
Step 5: Run the test. Set the boundaries, then check the result.
Step 1: Install Phone Harness
Phone Harness uses an MIT license. Its local iPhone setup works through the mirroring window on your Mac.
The tool can interact with other apps on the phone, so keep banking apps signed out and use a test page with made-up data.
Create a folder and start Claude Code:
mkdir -p ~/phone-app-test && cd ~/phone-app-testclaudePaste this:
Set up phone-harness. Clone https://github.com/ShawnPana/phone-harness into ~/.phone-harness and read install.md before making changes. Follow the installation instructions and register the skill for Claude Code.
Tell me when I need to grant a permission or pair my phone. Finish by running phone-harness --doctor and report the results.The repository also provides a setup prompt. Read any package installation requests before approving them.
Setup adds a skill that tells Claude how to use Phone Harness. You can then describe tests in plain language.
Step 2: Connect your phone
Pairing requires you to authenticate.
Connect the Mac and iPhone to the same Wi-Fi. Open iPhone Mirroring on your Mac and follow its setup prompts, keeping the phone nearby.
Once the phone screen appears in the mirroring window, move on to permissions.
Open System Settings, then Privacy & Security:
Enable Terminal under Accessibility so the tool can tap and type.
Enable Terminal under Screen Recording so it can capture the screen.
Quit and reopen Terminal after granting access. If captures come back blank, check Screen Recording first.
Approve any additional macOS permission prompts. Keep the iPhone nearby and locked while using Mirroring; unlocking it pauses the connection.
Step 3: Check the connection
Restart Claude Code in your test folder and ask:
Run phone-harness --doctor and show the full output.The health check covers six items: pyobjc, Accessibility, Screen Recording, the mirroring app's installation and running state, and its window.
Fix the first failure before working through later ones. If the window check fails, open iPhone Mirroring yourself, finish pairing, and leave the window open on screen. Give Claude the failing line and ask for the next step.
Next, check the mirroring window:
Use phone-harness to call screen_info(). Show the returned window size and position.The result should include the window's bounds. Keep iPhone Mirroring in front when the tool sends taps.
Passing these checks confirms the connection is ready to test. It doesn't yet confirm that taps hit the right controls.
Step 4: Build the app
Ask Claude to build a simple tip splitter:
Build a tip splitter as one index.html in this folder.
Include fields for bill amount, tip percentage, and number of people, plus a Split button showing the amount per person. Make the page usable on a phone.
Serve this folder with python3 -m http.server 8000 and give me the address to open on my iPhone over the same Wi-Fi.=Claude should create the file, start the server, and give you your Mac's local address, such as http://192.168.1.20:8000.
If macOS asks whether Python can accept incoming connections, allow it for the test.
Open Safari through iPhone Mirroring and enter the address. You can use your Mac's keyboard.
Check that Claude can read the page:
Read the phone screen with phone-harness. List the fields and buttons you can identify. Don't tap anything.Compare its answer with the page. If the page won't load, check the server, Wi-Fi connection, and whether a VPN is interfering.
Step 5: Run the test
Phone Harness doesn't restrict the agent to your test page. Give Claude clear boundaries at the start of each session:
Use only Safari on the phone and only the test page at my Mac's local address.
Use made-up numbers. Don't sign in, download files, or open another app or website without asking. Stop and ask if a test requires leaving this page.
Run the first test:
Test the tip splitter on the phone. Enter 84.50 for the bill, 18 for the tip percentage, and 4 people.
Tap Split and report the displayed amount per person.
The expected result, rounded to two decimal places, is 24.93. If the page shows something else, have Claude investigate the calculation or input handling.
Press Escape in Claude Code to interrupt the task if needed.
Use cases
Once Claude can read and operate the page, try these four tests within the same boundaries.
Use case #1: Check the math
Use an example with a known answer.
Enter a bill of 84.50, an 18 percent tip, and 4 people.
Compare the displayed result with 24.93. Report whether the calculation and rounding are correct.Check that Claude's report matches the phone screen.
Use case #2: Try bad input
Check what happens when fields are empty or contain invalid values.
Test an empty bill, zero people, and a negative tip separately.
For each case, report the displayed result or error message and whether it explains how to fix the input.Look for NaN, Infinity, or unexplained results. The page should tell the user what needs changing.
Use case #3: Fix and retest
Have Claude fix the problems and repeat the tests on the phone.
Fix the bugs found in index.html.
Reload the page on the phone and repeat each failing test. Report the new result for every case.Compare the new results with the earlier failures.
Use case #4: Add a feature
Build a round-up option and test both states.
Add a toggle that rounds each person's amount up to the next whole dollar.
Reload the page on the phone. Test the toggle on and off with a bill of 84.50, an 18 percent tip, and 4 people. Report both amounts.Expect 25 with rounding on and 24.93 with it off.
Confirmed limitations
Phone Harness is still changing. Its installation guide and PyPI listing give different minimum Python versions, so check the current requirements during setup. Reported issues include scrolling and typing on newer macOS releases, particularly macOS 26.
The workflow described here reads screen text through OCR. It can catch incorrect numbers and missing messages, but that doesn't replace a visual layout check. Inspect clipped buttons, overlapping fields, and spacing yourself.
Taps require the mirroring window to be in front. Unlocking the iPhone pauses Mirroring, and multi-touch tests such as pinch-to-zoom aren't supported here.
Claude Code sends retrieved screen content to its model. Use made-up data and keep unrelated apps out of the test.
Closing
Start with the known-answer test and compare the phone screen with Claude's report. Then try invalid inputs, fix the failures, and repeat them on the phone.
Once that works, use the same process on a feature in your own app. Keep tests small enough to check yourself, and review the layout alongside the reported results.
See you in the next one :)