agent-desktop

Agent Desktop - Printing Press CLI

agent-desktop は、AI エージェント向けのネイティブなデスクトップ自動化 CLI です。エージェントではなく、LLM を呼び出すこともありません。オペレーティングシステムのアクセシビリティツリーを構造化 JSON として公開し、@e1 のようなスナップショット単位の参照を割り当て、呼び出し元のエージェントがそれらの参照を使ってセマンティックな操作を実行できるようにします。

この Printing Press パッケージは、カタログブリッジである agent-desktop-pp-cli をインストールします。このブリッジは自動化を再実装しません。実際のリモート agent-desktop パッケージ（https://github.com/lahfir/agent-desktop）と npm パッケージ agent-desktop をインストールするか、委譲します。

前提条件：CLI のインストール

このスキルは agent-desktop-pp-cli バイナリを使用します。このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。 インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使用してインストールします。バイナリの保存先は、macOS/Linux ではデフォルトで $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin です。

   npx -y @mvanhorn/printing-press-library install agent-desktop --cli-only
   

2. 確認します：agent-desktop-pp-cli --version
3. このスキルを実行するエージェント／ランタイムの $PATH に、表示されたインストール先のディレクトリが含まれていることを確認します。

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go を直接インストールしてください（Go 1.26.6 以降が必要です）。この方法では $GOPATH/bin（デフォルトは $HOME/go/bin）にインストールされるため、代わりにそのディレクトリを $PATH に追加してください。

go install github.com/mvanhorn/printing-press-library/library/developer-tools/agent-desktop/cmd/agent-desktop-pp-cli@latest

インストール後、--version が「command not found」を返す場合、ランタイムから $PATH 上のバイナリディレクトリが見えていません。確認が成功するまで、スキルのコマンドを実行しないでください。

実際の agent-desktop CLI をインストールする

ブリッジをインストールした後、実際のリモートデスクトップ自動化 CLI をインストールして確認します。

agent-desktop-pp-cli install --version latest
agent-desktop-pp-cli doctor

ブリッジはデフォルトで agent-desktop@latest を使用するため、今後のアップストリームリリースは Printing Press にコピーされるのではなく、リモートパッケージチャネルから取得されます。バージョンを固定する必要があるタスクでは、agent-desktop-pp-cli install --version <version> を使用します。ホストに変更を加えず、インストールコマンドを確認するだけの場合は、agent-desktop-pp-cli install --dry-run を使用します。

バージョンに対応したドキュメントを読み込む

実際のバイナリには、独自のエージェントスキルが含まれています。インストール済みの agent-desktop のバージョンに正確に対応しているため、複雑なデスクトップ作業を行う前に、これらのドキュメントを優先して参照してください。

agent-desktop skills
agent-desktop skills get desktop --full
agent-desktop skills get desktop workflows
agent-desktop skills get desktop commands-observation
agent-desktop skills get desktop commands-interaction
agent-desktop skills get desktop commands-system
agent-desktop skills get desktop macos
agent-desktop skills get ffi --full

doctor で実際のバイナリがインストールされていることを確認した後、独自のフラグが必要なコマンドでは agent-desktop を直接呼び出してください。

基本的なループ

有用な自動化はすべて、同じループに従います。

agent-desktop permissions
agent-desktop snapshot --app "App Name" -i
agent-desktop click @e5 --snapshot <snapshot_id>
agent-desktop wait --text "Done" --app "App Name" --timeout 5000
agent-desktop snapshot --app "App Name" -i

エージェント向けのルール：

• 操作する前にスナップショットを取得します。UI の状態を推測しないでください。
• 返された snapshot_id を保持し、参照を使用するすべてのコマンドに渡します。
• 参照は一時的なものとして扱います。UI を変更する操作の後は、スナップショットを再取得してください。
• 座標より参照を優先します。mouse-click --xy の前に、click @e5、type @e2、check @e4、scroll @e1 を使用してください。
• 何も確認せずに待機するのではなく、wait --predicate actionable、wait --text、wait --window、または wait --notification を使用してください。
• STALE_REF または AMBIGUOUS_TARGET が発生した場合は、新しいスナップショットを取得して別の参照を選んでください。同じ古い参照を再試行しないでください。
• 複数のエージェントが最新のスナップショット状態を共有する可能性がある場合は、--session <id> を使用してください。
• 古い参照、曖昧さ、ポリシーによる拒否、または操作可能性の失敗を調査する場合は、--trace /tmp/agent-desktop.jsonl を使用してください。
• 物理入力が明示的に必要な場合にのみ --headed を使用してください。参照による操作は、デフォルトでヘッドレスかつアクセシビリティ優先です。

JSON コントラクト

実際の agent-desktop コマンドはすべて、標準出力に JSON エンベロープを書き込みます。

成功：

{
  "version": "2.0",
  "ok": true,
  "command": "snapshot",
  "data": {
    "snapshot_id": "s8f3k2p9",
    "ref_count": 14
  }
}

エラー：

{
  "version": "2.0",
  "ok": false,
  "command": "click",
  "error": {
    "code": "STALE_REF",
    "message": "Element could not be resolved from the requested snapshot",
    "suggestion": "Run snapshot to refresh, then retry with an updated ref"
  }
}

終了コードは、成功が 0、構造化されたランタイムエラーが 1、引数または解析エラーが 2 です。ブリッジの run コマンドは、実際のバイナリの終了コードをそのまま引き継ぎます。

コマンド一覧

実際の CLI では、54 個のコマンドを利用できます。

カテゴリー	コマンド
観察	snapshot、screenshot、find、get、is、list-surfaces
操作	click、double-click、triple-click、right-click、type、set-value、clear、focus、select、toggle、check、uncheck、expand、collapse
スクロール	scroll、scroll-to
キーボード	press、key-down、key-up
マウス	hover、drag、mouse-move、mouse-click、mouse-down、mouse-up
アプリ／ウィンドウ	launch、close-app、list-windows、list-apps、focus-window、resize-window、move-window、minimize、maximize、restore
通知	list-notifications、dismiss-notification、dismiss-all-notifications、notification-action
クリップボード	clipboard-get、clipboard-set、clipboard-clear
待機	wait
システム	status、permissions、version、skills
一括処理	batch

一般的な使用例：

agent-desktop snapshot --app Finder -i --compact
agent-desktop snapshot --skeleton --app Slack -i --compact
agent-desktop snapshot --root @e3 --snapshot <snapshot_id> -i --compact
agent-desktop find --app TextEdit --role button --name Save
agent-desktop get @e3 --snapshot <snapshot_id> --property value
agent-desktop is @e7 --snapshot <snapshot_id> --property checked
agent-desktop click @e5 --snapshot <snapshot_id>
agent-desktop type @e2 --snapshot <snapshot_id> "[email protected]"
agent-desktop check @e6 --snapshot <snapshot_id>
agent-desktop scroll @e1 --snapshot <snapshot_id> --direction down --amount 3
agent-desktop press cmd+s --app TextEdit
agent-desktop list-windows --app Finder
agent-desktop focus-window --app Finder
agent-desktop clipboard-get
agent-desktop wait --element @e5 --snapshot <snapshot_id> --predicate actionable --timeout 5000
agent-desktop batch '[{"command":"status","args":{}}]' --stop-on-error

Printing Press ブリッジコマンド

カタログの確認、インストール、診断、委任にのみ使用してください。

agent-desktop-pp-cli info
agent-desktop-pp-cli install --version latest
agent-desktop-pp-cli install --version latest --dry-run
agent-desktop-pp-cli install --manager bun
agent-desktop-pp-cli doctor
agent-desktop-pp-cli doctor --json
agent-desktop-pp-cli run version
agent-desktop-pp-cli run status

doctor で実際のバイナリが PATH 上にあることを確認した後は、エージェントから agent-desktop を直接呼び出せます。呼び出し元に安定した Printing Press のエントリポイントが必要な場合は、 引き続き agent-desktop-pp-cli run を使用してください。

プラットフォームに関する注意

macOS は、フェーズ 1 で完全に実装されたアダプターです。Terminal、iTerm、Codex などの起動アプリや、その他のエージェントランタイムには、UI 自動化のためのアクセシビリティ権限が必要です。 スクリーンショットの撮影には、画面収録の権限が必要です。一部の自動化サーフェスでは、オートメーションの権限も必要になる場合があります。

次のコマンドで権限を確認し、要求してください。

agent-desktop permissions
agent-desktop permissions --request

権限が拒否された場合は処理を停止し、返された error.suggestion を提示してください。 TCC の失敗を座標クリックで回避しないでください。