AppKit Inspector

AppKit Inspector は、実行中のネイティブ macOS AppKit インターフェイスを Codex から調査するための、Debug 専用ブリッジです。アプリケーションのコンテンツビューをプロセス内でキャプチャし、クリックした座標を対応する NSView にマッピングし、階層とジオメトリを表示して、コーディングタスクのための正確な視覚フィードバックを準備します。

公開プレビュー: API、プラグインのパッケージング、プレゼンテーションの動作は、1.0 までに変更される可能性があります。Codex Browser は、サポートされているデフォルトの表示先です。フルスクリーンは実験的な機能であり、デフォルトでは無効です。

特徴

• Accessibility や Screen Recording の権限なしで、実際の AppKit ウィンドウを調査できます。

• キャプチャしたインターフェイスをクリックして、最も深いネイティブ 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 を作成します。フルスクリーンを要求したり、システムブラウザを自動的に起動したりすることはありません。外部ブラウザウィンドウは明示的なフォールバックです。

プローブを 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 App フルスクリーン: 実験的で、デフォルトでは無効です。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 かつ same-site のセッションになります。このプロジェクトは公開された AppKit および Foundation API を使用し、インジェクション、正規フレームワーク、非公開フレームワーク、Screen Recording は使用しません。

キャプチャされたスクリーンショット、階層データ、メモ、レビューアーティファクトはセンシティブ情報です。Codex 経由で使用すると、ユーザーの製品およびワークスペースのデータ管理設定に基づいて、Codex タスクの一部になる可能性があります。プローブを統合する前に SECURITY.md を読み、脆弱性の報告にはセキュリティアドバイザリの非公開利用を推奨します。

コントリビューション

CONTRIBUTING.md を参照してください。プロジェクトに意図的に提出されたコントリビューションは、Apache License 2.0 の下でライセンスされます。

ライセンス

Copyright 2026 Jamin Zhou.

Apache License, Version 2.0 に基づいてライセンスされています。 バンドルされる依存関係の帰属は、THIRD_PARTY_NOTICES.md に記載されています。