AppKit Inspector

AppKit Inspector es un puente solo de depuración para inspeccionar una interfaz nativa de macOS AppKit en vivo desde Codex. Captura la vista de contenido de la aplicación en el proceso, asigna un punto clicado a su NSView, muestra la jerarquía y la geometría, y prepara una retroalimentación visual precisa para una tarea de codificación.

Vista previa pública: Las API, el empaquetado de complementos y el comportamiento de presentación pueden cambiar antes de la versión 1.0. Codex Browser es la superficie predeterminada compatible. La pantalla completa sigue siendo experimental y está deshabilitada de forma predeterminada.

Características

• Inspeccione una ventana real de AppKit sin permiso de Accesibilidad ni Grabación de pantalla.

• Haga clic en la interfaz capturada e identifique el NSView nativo más profundo.

• Revise nombres de clases, marcos, metadatos de accesibilidad y rutas de antepasados.

• Copie un paquete de retroalimentación que contenga la vista seleccionada, la geometría, la nota y los artefactos locales privados.

• Mantenga el descubrimiento y el transporte autenticados en 127.0.0.1.

• Compile la sonda fuera del comportamiento de Release activo con #if DEBUG.

Related MCP server: computer-use

Requisitos

• macOS 14 o posterior;

• Xcode 26 o posterior con Swift 6.2;

• Node.js 22 o posterior;

• una instalación actual de Codex de escritorio para el flujo de trabajo del complemento.

Inicio rápido

Clone y verifique el proyecto:

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

Instale el repositorio clonado como un marketplace local de Codex y habilite el complemento:

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

Inicie la demostración de AppKit incluida:

make demo

Inicie una nueva tarea de Codex para que cargue las herramientas MCP recién instaladas y luego pregunte:

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.

La herramienta predeterminada open_appkit_inspector crea una URL de loopback de un solo uso de 60 segundos para el panel del navegador derecho de la tarea actual. Nunca solicita pantalla completa ni invoca el navegador del sistema automáticamente. La ventana del navegador externo es una alternativa explícita.

Agregue la sonda a un proyecto de AppKit

Agregue el paquete en Xcode con:

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

O declárelo en Package.swift:

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

Agregue AppKitInspectorProbe solo a un destino de Debug o a una configuración de Debug, luego inícielo después de que la aplicación se haya lanzado:

#if DEBUG
import AppKitInspectorProbe

_ = try? AppKitInspectorProbe.start()
#endif

Nunca agregue ni inicie la sonda en compilaciones de Release, archivo, TestFlight o App Store.

Modos de presentación

• Codex Browser: predeterminado y compatible.

• Ventana local externa: alternativa explícita abierta en el navegador predeterminado del sistema.

• Pantalla completa de la aplicación MCP: experimental, deshabilitada de forma predeterminada y disponible solo cuando el servidor MCP se inicia con APPKIT_INSPECTOR_EXPERIMENTAL_FULLSCREEN=1.

Ningún fallo de presentación abre automáticamente otra ventana.

Estructura del repositorio

• native/ — sonda Swift reutilizable, aplicación de demostración y pruebas nativas.

• packages/mcp/ — servidor MCP local, descubrimiento y transporte autenticado.

• packages/app/ — interfaz de navegador del Inspector y cliente local.

• plugins/appkit-inspector/ — complemento de Codex instalable, distribución generada y habilidad.

• TODO.md — trabajo diferido y aceptación de pantalla completa experimental.

Desarrollo

npm ci
npm run check
swift build -c release

Para una verificación del puente en vivo, ejecute make demo en una terminal y npm run test:live en otra. Después de cambiar packages/app/ o packages/mcp/, ejecute npm run build e incluya los archivos generados correspondientes en plugins/appkit-inspector/dist/.

Seguridad y privacidad

La sonda y los servidores del Inspector se vinculan solo a loopback, requieren credenciales aleatorias y escriben datos de descubrimiento privados del usuario. Los enlaces de lanzamiento de Codex Browser son de un solo uso y se convierten en sesiones HttpOnly y de mismo sitio. El proyecto utiliza API públicas de AppKit y Foundation y no utiliza inyección, automatización de Accesibilidad, frameworks privados ni Grabación de pantalla.

Las capturas de pantalla, los datos de jerarquía, las notas y los artefactos de revisión son sensibles. Cuando se usan a través de Codex, pueden convertirse en parte de la tarea de Codex bajo los controles de datos del producto y del espacio de trabajo del usuario. Lea SECURITY.md antes de integrar la sonda y use avisos de seguridad privados para informar vulnerabilidades.

Contribuciones

Consulte CONTRIBUTING.md. Las contribuciones enviadas intencionalmente al proyecto se licencian bajo Apache License 2.0.

Licencia

Copyright 2026 Jamin Zhou.

Licenciado bajo la Apache License, Version 2.0. Las atribuciones de dependencias incluidas se documentan en THIRD_PARTY_NOTICES.md.