AppKit Inspector

AppKit Inspector는 실행 중인 네이티브 macOS AppKit 인터페이스를 Codex에서 검사할 수 있게 해주는 Debug 전용 브리지입니다. 애플리케이션의 콘텐츠 뷰를 프로세스 내부에서 캡처하고, 클릭한 지점을 해당 NSView에 매핑하며, 계층 구조와 지오메트리를 표시하고, 코딩 작업을 위한 정밀한 시각적 피드백을 준비합니다.

공개 미리보기(Public Preview): API, 플러그인 패키징, 표시 동작은 1.0 이전에 변경될 수 있습니다. 코드 브라우저(Codex Browser)는 지원되는 기본 표면입니다. Fullscreen은 실험 기능이며 기본적으로 비활성화되어 있습니다.

주요 기능

• 실제 AppKit 창을 접근성(Accessibility)이나 화면 녹화(Screen Recording) 권한 없이 검사합니다.

• 캡처된 인터페이스를 클릭하고, 해당 지점의 가장 깊은 네이티브 NSView를 식별합니다.

• 클래스 이름, 프레임, 접근성 메타데이터, 상위 경로를 확인합니다.

• 선택한 뷰, 지오메트리, 메모, 비공개 로컬 아티팩트가 포함된 피드백 패키지를 복사합니다.

• 검색과 전송을 127.0.0.1 위에서 인증된 상태로 유지합니다.

• #if DEBUG로 프로브가 릴리스(Release) 동작에서는 컴파일되지 않게 합니다.

요구 사항

• macOS 14 이상;

• Xcode 26 이상, Swift 6.2;

• Node.js 22 이상;

• 플러그인 워크플로를 위한 최신 Codex 데스크톱 설치.

빠른 시작

프로젝트를 클론하고 확인합니다:

git clone https://github.com/JaminZhou/AppKitInspector.git
cd AppKitInspector
npm ci
npm run check

클론한 저장소를 로컬 Codex 마켓플레이스로 설치한 뒤 플러그인을 활성화합니다:

codex plugin marketplace add "$PWD"
codex plugin add appkit-inspector@appkit-inspector-dev

포함된 AppKit 데모를 시작합니다:

make demo

새 Codex 태스크를 새로 설치된 MCP 도구가 로드되도록 시작한 뒤 다음을 요청합니다:

Use AppKit Inspector to connect to the running demo and open it in Codex Browser.

기본 open_appkit_inspector 도구는 현재 태스크의 오른쪽 Browser 패널에 60초 동안 유효한 일회용 루프백 URL을 만듭니다. 전체 화면을 요청하거나 시스템 브라우저를 자동으로 호출하지 않습니다. 외부 브라우저 창은 명시적 폴백(fallback)입니다.

AppKit 프로젝트에 프로브 추가

Xcode에서 패키지를 추가합니다:

https://github.com/JaminZhou/AppKitInspector.git

또는 Package.swift에 선언합니다:

.package(
    url: "https://github.com/JaminZhou/AppKitInspector.git",
    from: "0.1.1"
)

AppKitInspectorProbe는 Debug 타깃이나 Debug 구성에만 추가하고, 애플리케이션이 실행된 뒤 시작합니다:

#if DEBUG
import AppKitInspectorProbe

_ = try? AppKitInspectorProbe.start()
#endif

Release, 아카이브(archive), TestFlight 또는 App Store 빌드에는 프로브를 추가하거나 시작하지 마십시오.

표시 모드

• Codex Browser: 기본이며 지원되는 방식입니다.

• 외부 로컬 창: 시스템 기본 브라우저에서 열리는 명시적 폴백입니다.

• MCP 앱 전체 화면: 실험적이며 기본적으로 비활성화되어 있고, MCP 서버가 APPKIT_INSPECTOR_EXPERIMENTAL_FULLSCREEN=1로 시작할 때만 사용할 수 있습니다.

표시가 실패해도 다른 창이 자동으로 열리지 않습니다.

저장소 구조

• local/ — 재사용 가능한 Swift 프로브, 데모 애플리케이션 및 네이티브 테스트.

• packages/mcp/ — 로컬 MCP 서버, 검색 및 인증 전송 계층.

• packages/app/ — Inspector 브라우저 인터페이스와 로컬 클라이언트.

• plugins/appkit-inspector/ — 설치 가능한 Codex 플러그인, 생성된 배포 파일 및 스킬.

• TODO.md — 미뤄둔 작업과 실험적 전체화면 수용 기준.

개발

npm ci
npm run check
swift build -c release

실시간 브리지 확인을 위해 한 터미널에서 make demo를 실행하고, 다른 터미널에서 npm run test:live를 실행합니다. packages/app/나 packages/mcp/를 변경한 뒤에는 npm run build를 실행하고 plugins/appkit-inspector/dist/ 아래의 일치하는 생성 파일을 포함하세요.

보안 및 개인정보

프로브와 Inspectors 서버는 루프백에만 바인딩하며, 무작위 자격 증명을 요구하고, 사용자 비공개 검색 데이터를 저장합니다. Codex Browser 실행 링크는 일회용이며 HttpOnly, same-site(HttpOnly, same-site) 세션이 됩니다. 이 프로젝트는 공용 AppKit 및 Foundation API를 사용하며, 코드 주입, 접근성 자동화, 비개방 프레임워크, 화면 녹화를 사용하지 않습니다.

캡처된 스크린샷, 계층 데이터, 메모, 검토 아티팩트는 민감합니다. Codex를 통해 사용되는 경우, 사용자의 제품 및 워크스페이스 데이터 통제에 따라 Codex 태스크의 일부가 될 수 있습니다. 프로브를 통합하기 전에 SECURITY.md를 읽으시고, 취약점 신고에는 비공개 보안 권고문(private security advisory)를 사용하세요.

기여

CONTRIBUTING.md를 참고하세요. 프로젝트에 제출된 기여물은 Apache License 2.0에 따라 처리라이선스가 부여됩니다.

License 라이선스

Copyright 2026 Jamin Zhou.

Licensed under Apache Apache License, Version 2.0에 따라 라이선스가 부여됩니다. 번들로 포함한 의존성 정보는 THIRD_PARTY_NOTICES.md에 문서화되어 있습니다.