結論から：agent-desktop は Vercel Labs のオープンソース CLI（Apache-2.0）で、コーディングエージェントがネイティブのデスクトップアプリを「見て」操作できるようにします。OS のアクセシビリティツリーを読み、ボタンや入力欄ごとに ref を付けます。エージェントは ref に対して操作し、もう一度画面を読んで結果を確かめます。スクリーンショットからピクセル座標を推測する方式ではありません。
- エージェントではなく、モデルも入っていません。 各コマンドは JSON を 1 つ出力して終了します。「観察→操作→確認」のループは Claude Code、Codex、Cursor 側で回すので、3 つとも使えます。
- インストールは 1 行：
npm install -g agent-desktop。続けてnpx skills addで公式 skill をプロジェクトに入れると、Claude Code・Codex・Cursor がそれぞれ読み込みます。 - 実際に最後まで動かしました：本サイトの API Key で、Claude Code は約 28.6 秒、Codex は約 35 秒で、デスクトップ電卓のボタンを押して答えを読み取りました。どちらも正解です。
- 先に知っておきたい落とし穴が 2 つ：一部のアプリ（今回試した GTK4 版 GNOME 電卓など）はコントロールの位置情報を出さないため、ref クリックが
bounds unavailableで失敗します。また Linux で Codex の標準サンドボックス下では、agent-desktop がデスクトップの D-Bus に接続できずOperation not permittedになります。対処法は後半のエラー節にあります。
API Key を作成して、Claude Code・Codex・Cursor に agent-desktop をつなぐ →
agent-desktop とは、なぜ今話題なのか
10 月 31 日の朝（北京時間）、Vercel の Chris Tate が X で agent-desktop を発表しました。キャッチは「agent-browser, for your whole computer」。どのコーディングエージェントでも使える Computer Use で、macOS・Windows・Linux に対応し、マウスを奪わずバックグラウンドで動き、複数のエージェントが同時に操作できます。11 月 1 日午後の時点で、この投稿は約 64 万回表示、いいね 7,700 超、ブックマーク 8,700 超です。作者の Lahfir はリリース投稿で、エージェントによるデスクトップアプリの E2E テスト、アクセシビリティツリーでの読み取り、ウィンドウの一部だけを掘り下げてトークンを節約できること、1 つのアプリを多数のエージェントで同時に操作できることを挙げています。
GitHub リポジトリのスターは約 5,000。10 月 30 日に v1.0.2 が出て、同時に公式ドキュメントも公開されました。要点は次のとおりです。
| 項目 | 内容 |
|---|---|
| 形態 | Rust 製 CLI と C ライブラリ。コマンド名は 60 個で、どれも JSON を 1 つ出力 |
| 仕組み | macOS は AX API、Windows は UI Automation、Linux は AT-SPI。アプリが公開しているコントロールのツリーを読む |
| 動作環境 | macOS 13 以降、Windows 10 1809 以降または Server 2019 以降、Ubuntu 24.04 以降（glibc 2.35 以上）。x64 と ARM64 |
| やらないこと | モデルは内蔵しない。Web ページの自動化はしない（ページは agent-browser）。アクセシビリティツリーを出さない UI は見えない |
コミュニティの声として、@decildmc によると、Mac の Computer Use 環境を cua-driver から agent-desktop に切り替えたそうです。理由は、クリックできる要素だけをモデルに渡し、マウスを動かさずにボタンを直接押せるからとのこと。@o_kwasniewski によると、週末にこれを土台にしたネイティブアプリの E2E テストのデモを作ったそうです。X のトレンド要約によると、52 ステップのデモで、スケルトン取得と部分的な掘り下げによりトークンが約 198k から約 31k に減った例が紹介されています。
スクリーンショット型の Computer Use と比べた強みは、ref が安定していることと、安全に再試行できること（エラーに入力が届いたかどうかが書かれる）です。弱みは、アクセシビリティ情報を公開しているアプリでしか使えないことです。
ステップ 1：agent-desktop をインストールして権限を確認する
npm install -g agent-desktop
agent-desktop version
agent-desktop status
status の supported_surfaces が空でなく、accessibility が granted なら準備完了です。Linux で得た正常な出力はこうでした。
{"ok":true,"command":"status","data":{"permissions":{"accessibility":{"state":"granted"}},
"platform":"linux","supported_surfaces":["window","sheet","alert","menu"],"version":"1.0.2"}}
OS ごとの権限：
- macOS：agent-desktop を起動するアプリ（ターミナル、iTerm2、VS Code、エージェントのホストアプリ）に「アクセシビリティ」の許可を与えます。
agent-desktop permissions --guideを実行するとシステム設定の該当ページが開きます。スクリーンショットには「画面収録」も必要です。詳しくは macOS のドキュメント。 - Windows：許可は不要ですが、管理者として動いているアプリは、同じ権限レベルのターミナルから実行しないと読むだけで操作できません。バイナリは署名されていないため、SmartScreen やウイルス対策ソフトにブロックされることがあります。詳しくは Windows のドキュメント。
- Linux：ユーザーのグラフィカルセッション内で実行し、
at-spi2-coreを入れておきます。詳しくは Linux のドキュメント。
ステップ 2：Claude Code・Codex・Cursor に組み込む
agent-desktop には、バージョンに合った説明書が同梱されています（agent-desktop skills get desktop と skills get platform）。組み込むとは、初回利用の前にエージェントにこの 2 つを読ませることです。方法は 2 つあり、どちらか一方で十分です。
方法 A：skills で公式 skill を入れる（おすすめ）
# in your project root
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop
# non-interactive, pick the clients explicitly
npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop \
-a claude-code -a codex -a cursor -y
プロジェクトで実行したところ、インストーラーの出力は次のとおりでした。
✓ ./.agents/skills/agent-desktop
universal: Codex, Cursor
symlinked: Claude Code
つまり skill はプロジェクトの .agents/skills/agent-desktop に置かれ、Codex と Cursor はこのフォルダを直接読み、Claude Code は .claude/skills/agent-desktop のシンボリックリンク経由で同じファイルを読みます。-g を付けるとユーザー単位で入り、全プロジェクトで使えます。skills の基本は AI エージェントで Skills を使う方法を参照してください。
インストーラーはセキュリティスキャンの結果も表示します（今回は Gen が Safe、Socket が 0 alerts、Snyk が Med Risk）。skill はエージェントの全権限で動くという注意も出るので、入れる前に SKILL.md に目を通しておきましょう。
方法 B：AGENTS.md / CLAUDE.md に 2 行足す
skill を入れたくない場合は、公式の次の文をプロジェクトの AGENTS.md（Codex と Cursor が読む）に、Claude Code 用には CLAUDE.md に入れます。
Use `agent-desktop` to see and operate desktop apps. Before the first use, run
`agent-desktop skills get desktop` and `agent-desktop skills get platform`, and follow them.
Claude Code と Codex で指示ファイルを 1 つにまとめたいなら、Claude Code と Codex で AGENTS.md を共有するが参考になります。
ステップ 3：本サイトの API Key でクライアントを設定する
- aicodewith.ai に登録してログインし、キー管理で Key を作成して、表示された文字列をすべてコピーします。
- 使っているクライアントを設定します。
Claude Code：
export ANTHROPIC_BASE_URL="https://api.aicodewith.ai"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
恒久的な設定や Windows での設定は、Claude Code をサードパーティ API につなぐ方法を参照してください。Cursor でのモデルの選び方も同じ記事にあります。
Codex：グローバルの ~/.codex/config.toml に書きます。
# ~/.codex/config.toml
model_provider = "aicodewith"
model = "gpt-6.1-sol"
[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "YOUR_API_KEY"
ほかの項目は Codex config.toml 設定ガイドにまとめています。
Cursor：上の記事どおりにモデルを設定すれば、Cursor のエージェントはプロジェクト内の .agents/skills と AGENTS.md を Codex と同じように読みます。
ステップ 4：エージェントに「観察→操作→確認」を回させる
基本ループは 3 段階です。snapshot で ref 付きのコントロールツリーを取得し、ref に対して click や type などを実行し、もう一度 snapshot か get で結果を確かめます。ref にはそれを生んだ snapshot の ID が入っている（例：@s2jrj9msmdpdlw:e46）ので、画面が変わったら snapshot を取り直します。
agent-desktop list-apps # app names agent-desktop can see
agent-desktop snapshot --app galculator -i --compact # interactive elements, each with a ref
agent-desktop click @s2jrj9msmdpdlw:e46 # act on a ref from that snapshot
agent-desktop snapshot --app galculator -i --compact # observe again to verify
# dense apps (Electron, IDEs): map a skeleton first, then drill into one region
agent-desktop snapshot --app "Visual Studio Code" --skeleton -i --compact
agent-desktop snapshot --root @sXXXX:e1 -i --compact
要素の多いアプリ（Electron クライアントや IDE）では、まず浅い --skeleton を取り、--root で必要な部分だけを展開するよう公式は勧めています。トークン量が操作する範囲だけに比例するようになります。詳しくはスケルトンと部分展開。
普段は自分でこれらのコマンドを打つ必要はありません。エージェントに「agent-desktop で X アプリを開いて Y をして、結果を確認して」と頼めば十分です。
実測：本サイトの API Key で Claude Code と Codex に電卓を操作させる
テスト日は 2026 年 11 月 1 日。環境は Linux（Debian 13、X11 とウィンドウマネージャー xfwm4）、agent-desktop 1.0.2、対象アプリは GTK3 の電卓 galculator です。課題は「ボタンのクリックだけで計算し、式の入力はしない。計算後にアプリから結果を読み取る」。どちらのクライアントにも、方法 B の CLAUDE.md / AGENTS.md だけを置きました。
Claude Code 2.1.316
claude -p "Use agent-desktop to operate the galculator app that is already open: calculate 12 × 34 by clicking its buttons, then read the result back (Edit > Copy Display Value, then agent-desktop clipboard-get). Reply with RESULT=<number>." \
--model claude-sonnet-4-6 \
--allowedTools "Bash(agent-desktop:*)"
| 項目 | 結果 |
|---|---|
| 問題 | 12 × 34 |
| 返答 | RESULT=408（正解） |
| 所要時間 | 約 28.6 秒、11 ターン |
| agent-desktop コマンド数 | 15 回（うち 1 回は失敗し、エージェント自身が修正） |
Claude Code が実際に実行したコマンド（抜粋）：
agent-desktop skills get desktop
agent-desktop skills get platform
agent-desktop snapshot --app "galculator" -i --compact
agent-desktop click @s2jrj9msmdpdlw:e40 # AC
agent-desktop click @s2jrj9msmdpdlw:e46 # 1 (then 2, *, 3, 4, =)
agent-desktop click @s2jrj9msmdpdlw:e6 # "Copy Display Value" -> ACTION_FAILED, menu not open
agent-desktop click @s2jrj9msmdpdlw:e4 # open the Edit menu
agent-desktop snapshot --surface menu --app "galculator" -i --compact
agent-desktop click @s1muxufwf6hxgz:e3 # Copy Display Value
agent-desktop clipboard-get # -> 408
CLAUDE.md の指示どおり 2 つの説明書を読み、snapshot を取って ref でボタンを順に押しています。最初に「Copy Display Value」を押したときはメニューがまだ開いていなかったため、次のエラーで失敗しました。そこで Edit メニューを開き、--surface menu で snapshot を取り直して押し直し、最後に clipboard-get で 408 を読み取りました。
{"ok":false,"command":"click","error":{"code":"ACTION_FAILED",
"message":"Target is not actionable: visible (live offscreen state is true)"}}
このマシンでは click 1 回が約 0.07 秒で、時間のほとんどはモデルの思考に使われていました。
Codex 0.164.0
codex exec "Use agent-desktop to operate the galculator app that is already open: calculate 56 × 78 by clicking its buttons, then read the result back from the app. Reply with RESULT=<number>."
| 項目 | 結果 |
|---|---|
| 問題 | 56 × 78 |
| 返答 | RESULT=4368（正解） |
| 所要時間 | 約 35 秒 |
| agent-desktop コマンド数 | 24 回（うち 2 回失敗） |
失敗した 2 回はどちらも冒頭の agent-desktop: command not found です。テストのために agent-desktop をグローバルではなくプロジェクトフォルダに入れていたので、Codex がコマンドを実行するログインシェルの PATH に含まれていませんでした。Codex は自分で実行ファイルのパスを探し当て、課題を終えました。実際に使うときは npm install -g でグローバルに入れてください。
うまくいかなかった比較：GTK4 版 GNOME 電卓
最初は GNOME 電卓（GTK4）で試しました。agent-desktop はすべてのボタンを一覧できましたが、クリックは毎回 bounds unavailable で失敗しました。私たちの X11 環境では、このアプリがコントロールの位置情報を出さないため、可視性の事前チェックが通らず、agent-desktop がクリックを拒否したのです（delivery: not_delivered なので誤クリックはありません）。すると Claude Code は mouse-click --headed で画面座標を推測し始め、10 分たっても終わらなかったので手動で止めました。キーボード入力の agent-desktop press はこのアプリでも使えました。
教訓：bounds unavailable が続くときは、エージェントに座標を推測させず、キーボード操作か別のアプリに切り替えること。 プロンプトに「クリックが失敗したら press でキーを送って」と書いておくのも手です。
よくあるエラーと対処法
agent-desktop のエラーはすべて JSON です。error.code と disposition.retry で判断します。safe なら入力は届いていないので再試行して構いません。unsafe か unknown なら、二重送信を避けるため先に画面を観察します。全一覧は公式のエラーページにあります。以下は実際に出たものです。
status が accessibility denied で supported_surfaces が空（Linux）
{"ok":true,"command":"status","data":{"permissions":{"accessibility":{"state":"denied",
"suggestion":"AT-SPI is not installed or not visible to this process. Install the at-spi2-core package, then retry."}},
"supported_surfaces":[]}}
AT-SPI が入っていないか、プロセスから見えていません。at-spi2-core を入れ、グラフィカルセッション内で実行しているか確認します（セッション変数のない SSH シェルからはアプリが見えません）。Flatpak や snap のアプリには対応するインターフェースの許可が必要です。
list-apps で native window type could not be proven と出る
{"ok":false,"command":"list-apps","error":{"code":"ACTION_NOT_SUPPORTED",
"message":"The native window type of accessibility frame owned by pid 3857714 could not be proven"}}
ウィンドウマネージャーのない仮想ディスプレイで出ました。ウィンドウマネージャー（xfwm4）を起動したら、すぐに list-apps が通りました。普通のデスクトップ環境ではまず出ません。
click が bounds unavailable でタイムアウトする
{"ok":false,"command":"click","error":{"code":"TIMEOUT",
"message":"Target did not become actionable within the wait budget",
"details":{"kind":"actionability_timeout","last_report":{"report":{"checks":[
{"check":"visible","reason":"bounds unavailable","status":"unknown"}]}}},
"disposition":{"delivery":"not_delivered","retry":"safe"}}}
アプリが位置情報を出していません。--headed を付けても変わりません。press でキー入力するか、アクセシビリティ対応のしっかりした別のアプリを使います。上の GTK4 の例を参照してください。
click が ACTION_FAILED：visible (live offscreen state is true) で失敗する
対象が今は見えていません。たとえば閉じたメニューの中の項目です。先にメニューを開き、snapshot --surface menu で新しい ref を取ります。
Codex で INTERNAL：Operation not permitted が出る
{"ok":false,"command":"list-apps","error":{"code":"INTERNAL",
"message":"The accessibility bus returned an unexpected error",
"platform_detail":"Failed to connect to address `unix:path=/tmp/dbus-...`: Operation not permitted (os error 1)"}}
Linux で codex exec -s workspace-write を使ったときに出ました。Codex のサンドボックスがデスクトップの D-Bus への接続を遮るため、agent-desktop がアクセシビリティバスに届きません。agent-desktop のコマンドはサンドボックス外で実行させます。対話モードなら Codex に聞かれたときにそのコマンドを承認するか、専用のテスト機や VM に限って --dangerously-bypass-approvals-and-sandbox を使います。今回の実測は別のテスト用デスクトップで後者を使いました。
command not found
/bin/bash: line 1: agent-desktop: command not found
エージェントがコマンドを実行するときの PATH に agent-desktop がありません。npm install -g agent-desktop でグローバルに入れるか、AGENTS.md にフルパスを書きます。
Windows PowerShell で ref が効かない
PowerShell は裸の @xxx をスプラッティング演算子として扱うので、ref はシングルクォートで囲みます。
agent-desktop click '@s8f3k2p9:e8'
セキュリティ上の注意
- snapshot には画面に表示中の内容が入ります。 @mikawuf によると、snapshot には画面上の情報が含まれるので、公開ログに残さないようにとのことです。パスワードマネージャーやチャットアプリは閉じてからエージェントに操作させましょう。
- 権限は必要な分だけ。 Claude Code では
--allowedTools "Bash(agent-desktop:*)"で agent-desktop だけを許可できます。Codex のサンドボックスを外すのは隔離した環境だけにします。 - skill も AGENTS.md もエージェントが従う指示です。 出どころの確かなものだけを使いましょう。AGENTS.md の乗っ取りリスクも参照してください。
- クラウドで動かしたい場合、作者の Lahfir によると、Vercel Sandbox で起動した Linux デスクトップ上でも agent-desktop を動かせます。
よくある質問
agent-desktop と agent-browser の違いは
agent-browser は Web ページ、agent-desktop はネイティブのデスクトップアプリを操作します。Chromium や Electron アプリ内の Web コンテンツは、agent-desktop が launch "App" --cdp で DevTools ポートを開き、agent-browser に渡せます。
Computer Use 対応の特別なモデルが必要か
不要です。agent-desktop はテキスト（JSON）を出すだけなので、シェルコマンドを実行できるコーディングエージェントならどれでも使えます。今回の実測では Claude Sonnet 4.6 と GPT-6.1 Sol を使いました。
自作デスクトップアプリの E2E テストに使えるか
使えます。作者が挙げている主な用途の 1 つです。コードの変更が実際のアプリで効いているかを確かめる方法は、verification skill で実アプリを動かして検証するも参考にしてください。
