To3akaRin/mac-computer-use

Enable any LLM to control your computer with cross-platform support, featuring 3D modeling examples and live demos.

TL;DR

mac‑computer‑use は、大規模言語モデル駆動のエージェントがmacOSデスクトップを制御できるオープンソースの エージェントスキル です。macOS Accessibility (AX) またはChrome DevTools Protocol (CDP) を通じてウィンドウやUI要素を観察・操作・検証でき、ローカルCLIツールから実行可能で、オープンな エージェントスキル仕様 を遵守しています。

何ができるか（平易な言葉で）

観察 – 開いているアプリの一覧、ウィンドウのジオメトリ、UIコントロール（ボタン、テキストフィールドなど）を取得。Chromiumベースのウィンドウについては、CDPでページのDOMを調査可能。
操作 – ネイティブmacOS入力イベント（クリック、ホバー、スクロール、入力）またはCDP入力コマンドを送信して、ターゲットUIと対話。
検証 – UI状態を読み取り、ScreenCaptureKitでスクリーンショットを取得し、構造化されたJSONを返すことで、エージェントが操作の成功を確認可能。

この一連のワークフローは、エージェントスキル仕様 をサポートする任意のエージェントランタイム（Claude Code、Codex、Cursorなど）がロード・実行できる形でパッケージ化されています。

どんな人が使うか

macOSアプリの自動化が必要なAIアシスタントを開発する開発者（例：ファイルを開く、フォームに入力、スクリプトを実行するなど、カスタムAppleScriptやSeleniumコードを書かずに済む）。
身体化AI（embodied AI）を研究する研究者（LLMが実際のデスクトップを操作できる、再現性がありセキュアな環境を必要とする）。
UI操作をシェルコマンドでは表現しづらいタスクをスクリプト化したいパワーユーザー（即時プラグアンドプレイのCLIを求める）。

使い始め方（ステップバイステップ）

スキルのインストール：Vercel Skills CLI経由で実行：
```
npx skills add To3akaRin/mac-computer-use
```
これにより mac-computer-use/ ディレクトリがローカルスキルストアにコピーされます。
Macの要件を確認：
- macOS 14以上、Apple Silicon（Intelは動作する可能性ありだが未検証）。
- Xcode Command‑Line Tools（Swift 6）– xcode-select --install。
- Node 22.4+（CDP部分のみ必要）。
- ターミナルまたは実行するエージェントアプリに アクセシビリティ および 画面録画 の権限を付与。
簡単な観察コマンドを実行：利用可能なウィンドウを確認：
```
./.skills/mac-computer-use/scripts/run.sh native windows
```
出力は各ウィンドウのID、タイトル、サイズ、プロセスを含むJSON形式。
ウィンドウを選択し、UIを調査（TextEditの例）：
```
./.skills/mac-computer-use/scripts/run.sh native ax \
    --window <WINDOW_ID> \
    --snapshot-out ./artifacts/window.json
```
そのウィンドウ内のすべてのAccessibility要素のJSON記述を出力します。

操作を実行 – 例：最初のテキストフィールドに「Hello」を入力：

./.skills/mac-computer-use/scripts/run.sh native type \
    --window <WINDOW_ID> \
    --element "AXTextField" \
    --text "Hello"

検証 – フィールドの内容を読み取るか、スクリーンショットを取得：
```
./.skills/mac-computer-use/scripts/run.sh native shot \
    --window <WINDOW_ID> \
    --output ./artifacts/after.png
```
JSON結果により、テキストが正しく設定されたかをエージェントが判断可能。

すべてのコマンドは --dry-run フラグをサポートしており、実際の入力を送信せずにパラメータをチェックできるため、安全性に役立ちます。

コア技術的詳細（興味のある人向け）

機能	実装方法
言語	ネイティブmacOSツールにはSwift 6、CDP連携にはNode.jsスクリプト
UI観察	ネイティブアプリにはmacOS Accessibility (AX) API、ChromiumベースのウィンドウにはChrome DevTools Protocol (CDP)
入力生成	ネイティブアプリには`CGEvent`ベースのマウス/キーボードイベント、WebページにはCDP `Input`ドメイン（`click`、`insertText`など）
検証	AX値の読み取り、CDPの読み取り専用アサーション、ScreenCaptureKitによるスクリーンショット取得
パッケージング	オープンなエージェントスキル仕様を遵守 – `SKILL.md`メタデータファイルと、ランタイムが呼び出す `scripts/` ランチャーファイル
ランタイムnpm依存なし	CDPクライアントは超小型の自己完結型スクリプト。別サーバーやAPIキーは不要
セキュリティルール	• ユーザー非活動から≥2秒経過後、≤15秒待機後にのみ操作。 • `--dry‑run`プレビューモード。 • 古いウィンドウスナップショットは拒否。
出力形式	`target`、`channel`（nativeまたはcdp）、`status`（`success`、`unknown`、`refused`）、および証拠（スクリーンショット、AX読み取り結果）を含むJSONオブジェクト

制限事項と未解決の課題

アプリカバレッジ – AXツリーが明確に公開されているアプリ、またはCDPポートを持つアプリでは即時動作。一部サードパーティツールはカスタムコントロールを備え、特定が難しい場合あり。
Intel/macOS 14 – 公式に検証されていない。CIはApple Silicon/macOS 15で実行。
リモート実行不可 – スキルはMac上でローカルで実行が必要。Linuxサンドボックスではデスクトップを制御できない。
ドキュメント言語 – 多くのガイド（references/*.md）は現在中国語で、非中国語話者による貢献を妨げる可能性あり。

クイックリファレンスチートシート

コマンド	目的	例
`native windows`	すべてのウィンドウを一覧表示	`run.sh native windows`
`native ax`	ウィンドウのAccessibilityツリーをダンプ	`run.sh native ax --window 123 --snapshot-out out.json`
`native type`	特定のAX要素にテキストを入力	`run.sh native type --window 123 --element AXTextField --text "Hi"`
`native click`	座標またはAXパスでUI要素をクリック	`run.sh native click --window 123 --point 0.5,0.2`
`cdp snapshot`	ChromiumページのDOMとスクリーンショットを取得	`node scripts/cdp.mjs snapshot --endpoint http://127.0.0.1:9222 --target PAGE_ID`
`native doctor`	自己診断（権限、Swift、Node）	`run.sh native doctor`

まとめ

mac‑computer‑use は、任意のLLM駆動エージェントが呼び出せる、決定論的で観察・操作・検証可能なmacOSデスクトップインターフェースを実現します。クラウドサービスを必要とせず、高レベルの言語推論と低レベルのUI操作のギャップを埋め、自律的なmacOSエージェントの基盤として堅実な構成を提供します。