AI가 아이폰 Safari를 직접 보게 만든 플러그인

프론트엔드 작업을 Claude Code에 맡기면 고친 화면을 Playwright로 열어서 확인까지 해 줍니다. 그런데 주소창 때문에 100vh가 어긋나거나 키보드가 올라오면서 화면이 밀리는 버그는 아이폰 Safari에서 나고, 이런 건 진짜 아이폰에서 봐야 합니다. 그래서 Claude Code가 제 아이폰의 Safari를 보고 만질 수 있게 플러그인을 만들었습니다.

/plugin marketplace add GUMBOKIM/iphone-webkit-inspector
/plugin install iphone-webkit-inspector@gumbokim

코드는 GitHub에 있습니다.

어떻게 붙였나

안드로이드는 쉽습니다. 안드로이드 Chrome은 Playwright가 쓰는 CDP(Chrome DevTools Protocol)를 그대로 쓰니까 adb forward로 포트만 이어 주면 Playwright가 바로 붙습니다.

아이폰 Safari는 CDP가 아니라 맥 Safari의 개발자용 메뉴가 쓰는 WebKit Web Inspector 프로토콜을 씁니다. 다행히 pymobiledevice3에 webinspector cdp라는 명령이 있습니다. 맥에 CDP 서버를 하나 열고, 거기로 들어온 명령을 WebKit 명령으로 바꿔서 USB나 Wi-Fi로 아이폰에 보내 줍니다. 아래에서는 이걸 브릿지라고 부르겠습니다.

브릿지가 CDP를 받으니 Playwright도 connectOverCDP로 붙을 것 같았습니다. 그런데 붙여 보니 페이지가 하나도 안 잡혔습니다. 역시 안 되는구나 했는데, 알고 보니 그때 아이폰에서 Safari가 앞에 떠 있지 않았을 뿐이었습니다. Safari를 띄워 두고 다시 하니 붙습니다. 같은 사이트 안에서 페이지를 옮기고, DOM과 접근성 트리를 읽고, 입력창에 글자를 치고, 콘솔과 네트워크 이벤트를 받고, 스크린샷을 찍는 것까지 다 됐습니다. 이러면 그냥 Playwright 쓰면 되겠는데 싶었습니다.

그런데 클릭에서 막혔습니다. 블로그 상단의 글 목록 링크를 눌렀는데 페이지가 안 넘어갔습니다. 들여다보니 Playwright의 클릭은 페이지 안에서 만든 가짜 이벤트(isTrusted=false)로만 들어오고 있었습니다. 브릿지가 옮겨 줄 수 있는 건 WebKit에 있는 기능까지라 그 밖의 명령은 받아 줄 곳이 없습니다. 탭과 스크롤도 안 되고, 응답을 기다리거나 요청을 가로채면 멈추고, 다른 사이트로 넘어가면 연결이 끊깁니다.

Claude Code가 실제로 쓰는 Playwright MCP로도 해 봤습니다. 이쪽은 더 안 좋았습니다. Safari에 뒤쪽 탭이 하나라도 있으면 그 탭이 응답을 안 해서 첫 명령부터 멈춥니다. 탭을 하나만 남겨도 정작 AI가 써야 할 페이지 이동, 스냅샷, 스크린샷이 전부 시간 초과로 끝납니다. AI한테 쥐여 줄 만한 상태가 아니었습니다.

그래서 Playwright를 빼고 브릿지에 직접 붙는 도구를 만들었습니다.

무엇을 만들었나

플러그인 구조. 맥 안에서 Claude Code가 ios.mjs 명령을 실행하고 ios.mjs 데몬이 탭별 연결을 유지하며 콘솔과 네트워크 이벤트를 기록한다. 데몬은 Unix 소켓으로 CDP를 보내고 pymobiledevice3 브릿지가 이를 WebKit 인스펙터 프로토콜로 번역해 USB 또는 Wi-Fi로 아이폰의 Safari·Chrome 탭에 전달한다. 화면 전체 스크린샷과 FPS는 Xcode 개발자 서비스로 따로 가져온다.

ios.mjs라는 Node 스크립트 하나에 명령을 다 넣고, 언제 어떻게 쓰는지 적은 SKILL.md와 묶어서 Claude Code 플러그인으로 만들었습니다. 의존성은 없습니다. 브릿지는 uvx로 띄우니까 pymobiledevice3를 따로 설치할 필요도 없습니다. uv만 있으면 됩니다.

탭에 처음 붙는 데 몇 초씩 걸려서 백그라운드 데몬이 탭별 연결을 들고 있게 했습니다. 한 번 붙은 뒤로는 간단한 명령이 10ms 안팎에 끝나고, 그사이 콘솔과 네트워크도 계속 기록됩니다.

AI가 화면을 다루는 방식은 Playwright MCP에서 빌렸습니다. snapshot이 버튼과 입력창에 @e3 같은 번호를 붙여 주면 AI는 tap @e3, type으로 조작합니다. tap은 손가락 터치가 아니라 페이지 안에서 클릭을 실행하는 건데, WebKit의 emulateUserGesture를 켜고 실행해서 소리 재생처럼 사용자가 직접 눌러야 하는 동작도 됩니다. Playwright로는 안 넘어가던 그 글 목록 링크도 tap으로 누르면 넘어갑니다.

나머지는 평소 DevTools로 하던 일을 명령으로 옮겼습니다. 네트워크 응답을 열어 보고, 스타일이 어느 CSS 파일에서 왔는지 찾고, 중단점을 걸어 한 줄씩 따라가는 것까지 됩니다. Safari 주소창과 키보드까지 나온 화면 전체 스크린샷은 브릿지가 아니라 Xcode 개발자 서비스로 찍습니다.

처음에는 데몬과 브릿지를 127.0.0.1 포트로 열었습니다. 다른 AI 도구에 코드 리뷰를 맡겼더니 웹페이지나 같은 맥의 다른 사용자가 그 포트로 아이폰에 붙을 수 있다는 지적이 나왔습니다. 맞는 말이라 둘 다 제 계정만 열 수 있는 폴더 안의 Unix 소켓으로 바꿨습니다.

안 되는 것

화면에 떠 있는 탭만 그려집니다. 스크린샷과 녹화도 그 탭만 되고, 열려 있는 다른 탭을 앞으로 가져오지도 못합니다. 주소창 버튼이나 권한 요청 창, 키보드 같은 Safari 자체 UI도 못 누릅니다. 그래서 키보드 확인은 아직 사람이 입력창을 한 번 눌러 줘야 합니다. 키보드가 뜬 뒤의 화면은 AI가 볼 수 있습니다.

alert()와 confirm()은 이 플러그인으로도 못 닫습니다. Web Inspector에 닫는 명령 자체가 없습니다. 한 번 뜨면 누가 닫기를 누를 때까지 페이지가 멈춥니다. 다른 사이트로 넘어가면 탭 연결이 끊기는 것도 그대로라 다시 붙어야 합니다.

플러그인으로 찍은 아이폰 화면. 블로그 글 목록 위에 테스트로 띄운 plug-dlg 알림창이 떠 있고, 아래에 Safari 주소창과 툴바가 보인다.

플러그인으로 찍은 아이폰 화면입니다. 테스트로 띄운 alert() 때문에 페이지가 멈춰 있습니다. 주소창까지 나온 화면은 찍히는데, 이 닫기 버튼은 누를 수 없습니다.

iOS 18.6.2에서는 LCP와 CLS가 안 나옵니다. 네트워크 속도 제한도 없어서 아이폰 설정 → 개발자 → Network Link Conditioner로 대신합니다.

macOS, Xcode, uv, Node 22 이상, 그리고 개발자 모드와 Safari 웹 속성(Web Inspector)을 켠 iOS 17 이상 아이폰이 있으면 됩니다. 설정이 맞는지는 AI에게 doctor를 돌려 달라고 하면 확인해 줍니다. 이 글은 iOS 18.6.2와 pymobiledevice3 11.49.2 기준입니다.