AppKit Inspector

AppKit Inspector ist eine Nur-Debug-Brücke, um eine laufende native macOS-AppKit-Oberfläche von Codex aus zu inspizieren. Es erfasst die Inhaltsansicht der Anwendung im Prozess, ordnet einen angeklickten Punkt seinem NSView zu, zeigt Hierarchie und Geometrie und bereitet präzises visuelles Feedback für eine Codierungsaufgabe vor.

Public Preview: APIs, Plugin-Verpackung und Präsentationsverhalten können sich vor Version 1.0 ändern. Codex Browser ist die unterstützte Standardoberfläche. Vollbild bleibt experimentell und ist standardmäßig deaktiviert.

Funktionen

• Inspiziere ein echtes AppKit-Fenster ohne Berechtigung für Bedienungshilfen oder Bildschirmaufnahme.

• Klicke auf die erfasste Oberfläche und identifiziere das tiefste native NSView.

• Überprüfe Klassennamen, Frames, Metadaten zur Bedienungshilfe und Vorfahrenpfade.

• Kopiere ein Feedback-Paket mit der ausgewählten Ansicht, Geometrie, Notiz und privaten lokalen Artefakten.

• Halte Erkennung und Transport auf 127.0.0.1 authentifiziert.

• Kompiliere die Sonde mit #if DEBUG aus dem aktiven Release-Verhalten heraus.

Related MCP server: computer-use

Anforderungen

• macOS 14 oder neuer;

• Xcode 26 oder neuer mit Swift 6.2;

• Node.js 22 oder neuer;

• eine aktuelle Codex-Desktop-Installation für den Plugin-Workflow.

Schnellstart

Klonen und verifiziere das Projekt:

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

Installiere das geklonte Repository als lokalen Codex-Marketplace und aktiviere das Plugin:

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

Starte die enthaltene AppKit-Demo:

make demo

Starte eine neue Codex-Aufgabe, damit die neu installierten MCP-Tools geladen werden, und frage dann:

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.

Das Standard-Tool open_appkit_inspector erstellt eine 60-sekündige Einmal-Loopback-URL für das rechte Browser-Panel der aktuellen Aufgabe. Es fordert niemals Vollbild an und ruft den Systembrowser nicht automatisch auf. Das externe Browserfenster ist ein expliziter Fallback.

Sonde zu einem AppKit-Projekt hinzufügen

Füge das Paket in Xcode hinzu mit:

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

Oder deklariere es in Package.swift:

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

Füge AppKitInspectorProbe nur zu einem Debug-Target oder einer Debug-Konfiguration hinzu und starte es, nachdem die Anwendung gestartet wurde:

#if DEBUG
import AppKitInspectorProbe

_ = try? AppKitInspectorProbe.start()
#endif

Füge die Sonde niemals in Release-, Archiv-, TestFlight- oder App-Store-Builds hinzu oder starte sie dort.

Präsentationsmodi

• Codex Browser: Standard und unterstützt.

• Externes lokales Fenster: expliziter Fallback, der im Standardbrowser des Systems geöffnet wird.

• MCP-App-Vollbild: experimentell, standardmäßig deaktiviert und nur verfügbar, wenn der MCP-Server mit APPKIT_INSPECTOR_EXPERIMENTAL_FULLSCREEN=1 startet.

Kein Präsentationsfehler öffnet automatisch ein anderes Fenster.

Repository-Struktur

• native/ — wiederverwendbare Swift-Sonde, Demo-Anwendung und native Tests.

• packages/mcp/ — lokaler MCP-Server, Erkennung und authentifizierter Transport.

• packages/app/ — Inspector-Browseroberfläche und lokaler Client.

• plugins/appkit-inspector/ — installierbares Codex-Plugin, generierte Distribution und Skill.

• TODO.md — aufgeschobene Arbeiten und experimentelle Vollbild-Abnahme.

Entwicklung

npm ci
npm run check
swift build -c release

Für eine Live-Brückenprüfung führe make demo in einem Terminal und npm run test:live in einem anderen aus. Nach Änderungen an packages/app/ oder packages/mcp/ führe npm run build aus und füge die passenden generierten Dateien unter plugins/appkit-inspector/dist/ hinzu.

Sicherheit und Datenschutz

Die Sonde und die Inspector-Server binden nur an Loopback, erfordern zufällige Anmeldeinformationen und schreiben benutzerprivate Erkennungsdaten. Codex-Browser-Startlinks sind einmalig und werden zu HttpOnly-Sitzungen mit gleicher Site. Das Projekt verwendet öffentliche AppKit- und Foundation-APIs und nutzt keine Injektion, Bedienungshilfen-Automatisierung, private Frameworks oder Bildschirmaufnahme.

Erfasste Screenshots, Hierarchiedaten, Notizen und Überprüfungsartefakte sind sensibel. Wenn sie über Codex verwendet werden, können sie Teil der Codex-Aufgabe unter den Produkt- und Arbeitsbereichsdatenkontrollen des Benutzers werden. Lies SECURITY.md, bevor du die Sonde integrierst, und verwende private Sicherheitshinweise für Schwachstellenmeldungen.

Mitwirken

Siehe CONTRIBUTING.md. Beiträge, die absichtlich an das Projekt eingereicht werden, sind unter der Apache License 2.0 lizenziert.

Lizenz

Copyright 2026 Jamin Zhou.

Lizenziert unter der Apache License, Version 2.0. Die Zuschreibungen gebündelter Abhängigkeiten sind in THIRD_PARTY_NOTICES.md dokumentiert.