AppKit Inspector

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

공개 미리보기: API, 플러그인 패키징, 프레젠테이션 동작은 1.0 이전에 변경될 수 있습니다. Codex Browser가 지원되는 기본 표면입니다. 전체 화면은 아직 실험적이며 기본적으로 비활성화되어 있습니다.

기능

• 접근성 또는 화면 녹화 권한 없이 실제 AppKit 창을 검사합니다.

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

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

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

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

• #if DEBUG로 활성 Release 동작에서 프로브를 컴파일 제외합니다.

Related MCP server: computer-use

요구 사항

• macOS 14 이상;

• Swift 6.2를 포함한 Xcode 26 이상;

• 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

새로 설치된 MCP 도구를 로드하도록 새 Codex 작업을 시작한 다음 요청합니다:

Use AppKit Inspector to connect to the running demo and open it in Codex Browser. The workflow
explicitly presents the right Browser panel after navigation. In the Inspector, use **Fit**, **−**,
and **+** to resize the snapshot; trackpad pinch and Command-modified scrolling also zoom.

기본 open_appkit_inspector 도구는 현재 작업의 오른쪽 Browser 패널에 대해 60초 동안 유효한 일회용 루프백 URL을 생성합니다. 전체 화면을 요청하거나 시스템 브라우저를 자동으로 호출하지 않습니다. 외부 브라우저 창은 명시적 대체 수단입니다.

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, 아카이브, TestFlight 또는 App Store 빌드에는 프로브를 추가하거나 시작하지 마십시오.

프레젠테이션 모드

• Codex Browser: 기본 및 지원됨.

• 외부 로컬 창: 시스템 기본 브라우저에서 열리는 명시적 대체 수단.

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

프레젠테이션 실패 시 다른 창이 자동으로 열리지 않습니다.

저장소 구조

• native/ — 재사용 가능한 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/ 아래의 일치하는 생성 파일을 포함합니다.

보안 및 개인정보 보호

프로브와 Inspector 서버는 루프백에만 바인딩하고, 임의 자격 증명을 요구하며, 사용자 비공개 검색 데이터를 기록합니다. Codex Browser 실행 링크는 일회용이며 HttpOnly, 동일 사이트 세션이 됩니다. 이 프로젝트는 공개 AppKit 및 Foundation API를 사용하며 주입, 접근성 자동화, 비공개 프레임워크 또는 화면 녹화를 사용하지 않습니다.

캡처된 스크린샷, 계층 구조 데이터, 메모, 검토 아티팩트는 민감합니다. Codex를 통해 사용할 때 사용자의 제품 및 작업 공간 데이터 제어에 따라 Codex 작업의 일부가 될 수 있습니다. 프로브를 통합하기 전에 SECURITY.md를 읽고 취약점 보고에는 비공개 보안 권고를 사용하십시오.

기여

CONTRIBUTING.md를 참조하십시오. 프로젝트에 의도적으로 제출된 기여는 Apache License 2.0에 따라 라이선스가 부여됩니다.

라이선스

Copyright 2026 Jamin Zhou.

Apache License, Version 2.0에 따라 라이선스가 부여됩니다. 번들된 종속성 저작자 표시는 THIRD_PARTY_NOTICES.md에 문서화되어 있습니다.