agent-computer-use

agent-computer-use — コンピューター操作スキル

デスクトップアプリケーションを操作する CLI ツール agent-cu を利用できます。ボタンのクリック、テキストの入力、画面の読み取り、スクロール、ファイルのドラッグ、ウィンドウの移動などを、すべてターミナルから実行できます。

初回セットアップ（ユーザーによる操作）

初めて agent-cu コマンドを実行すると、Claude Code がユーザーに承認を求めます。ユーザーが選べる方法は、推奨順に次の 3 つです。

1. 最も簡単 — ターミナルで agent-cu setup を実行します。インタラクティブなウィザードにより、適切な設定ファイルに Bash(agent-cu *) が書き込まれます。これは一度だけ実行します。承認を繰り返し求められてユーザーが困っているようであれば、この方法を提案してください。

   あなた（エージェント）が自分で実行していて、プロンプトに応答できない場合は、非インタラクティブフラグを使用してください。

   • agent-cu setup --yes → unsupervised + global（推奨されるデフォルト）
   • agent-cu setup --mode <unsupervised|supervised> --scope <global|project> で個別に指定

2. 最も手早い — 承認プロンプトで 「Yes, and don't ask again for: agent-cu *」 を選びます。対象となるのはその特定のサブコマンドパターンだけです。他のサブコマンドでは、再びプロンプトが表示されます。

3. 手動 — ~/.claude/settings.json の permissions.allow に "Bash(agent-cu *)" を追加します。

ユーザーの設定ファイルを自分で変更しようとしないでください。代わりに、agent-cu setup を案内してください。

操作の考え方

コンピューターの前に座っている人間のように考えてください。 操作する前に、自分に問いかけてください。画面には何が見えるでしょうか。何をクリックするでしょうか。何を入力するでしょうか。

人間は次のように操作します。

1. 画面を見る（スナップショット）
2. 必要なものを見つける（参照先を特定）
3. 操作を 1 つ実行する（クリック、入力、キー操作）
4. 変化を確認する（再スナップショット）

同じように操作してください。手順を省略してはいけません。操作後に UI が変化していないと決めつけてはいけません。

基本のループ

snapshot → identify → act → verify

agent-cu snapshot -a Music -i -c          # what's on screen?
# read the output, find the right @ref
agent-cu click @e5                         # do one thing
agent-cu snapshot -a Music -i -c          # what changed?

すべての操作で UI が変化します。 以前の参照先は古くなっています。必ずスナップショットを取り直してください。

アプリを開く

操作を始める前に、必ずアプリの準備が整うまで待ってください。

agent-cu open Safari --wait
agent-cu snapshot -a Safari -i -c

開いてスナップショットを取得していないアプリを操作してはいけません。

要素を見つける

ステップ 1：-i -c（インタラクティブ＋コンパクト）を指定してスナップショットを取得します。

agent-cu snapshot -a Calculator -i -c

これにより、@e1、@e5、@e12 のような参照先を持つ、クリックまたは入力が可能な要素だけが表示されます。

ステップ 2：出力を読みます。名前、役割、または ID から必要な要素を探します。

ステップ 3：参照先を使用します。参照先を使う方法が、要素を指定するうえで最も速く、最も信頼できます。

要素が見つからない場合は、深度を上げてください。

agent-cu snapshot -a Safari -i -c -d 8

クリック

ボタン、リンク、メニュー項目には click を使います。

agent-cu click @e5                         # single click (AXPress, headless)
agent-cu click @e5 --count 2               # double-click (opens files, plays songs)

click はまず AXPress を試します（バックグラウンドで実行され、フォーカスを奪いません）。ダブルクリックまたは右クリックの場合に限り、マウスシミュレーションにフォールバックします。

安定した ID を持つ要素（スナップショット間で変化しない要素）には、次を使います。

agent-cu click 'id="play"' -a Music
agent-cu click 'id~="track-123"' -a Music  # partial id match

入力

対象要素を指定する場合（推奨 — AXSetValue を使用し、ヘッドレスで動作します）：

agent-cu type "hello world" -s @e3

フォーカスされているフィールドに入力する場合（キーボードシミュレーションを使用し、アプリにフォーカスが必要です）：

agent-cu type "hello world" -a Safari

参照先がある場合は、必ず -s @ref を優先してください。より信頼性が高くなります。

キー入力

agent-cu key Return -a Calculator
agent-cu key cmd+k -a Slack
agent-cu key cmd+a -a TextEdit
agent-cu key Escape -a Safari

スクロール

agent-cu scroll down -a Music              # scroll main content area
agent-cu scroll down --amount 10 -a Music  # scroll more
agent-cu scroll-to @e42                    # scroll element into view (headless)

スクロールするには、アプリにフォーカスが必要です。ヘッドレスで操作する場合は scroll-to を使ってください。

コンテンツを読む

agent-cu text -a Calculator                # all visible text
agent-cu get-value @e5                     # one element's value/state
agent-cu get-value 'id="title"' -a Music   # by selector

大きなアプリでは、text の代わりに特定の要素に対して get-value を使ってください。

ウィンドウ管理

agent-cu move-window -a Notes --x 100 --y 100
agent-cu resize-window -a Notes --width 800 --height 600
agent-cu windows -a Finder                 # get window positions and sizes

これらの操作は即時に実行され、ヘッドレスで動作します。AXSetPosition／AXSetSize を使用します。

ドラッグ＆ドロップ

ドラッグするには、アプリにフォーカスが必要です。また、重なっていない 2 つの領域が画面上に表示されている必要があります。

人間のように考えてください：ドラッグ元とドロップ先の両方を見る必要があります。

# Step 1: Set up windows side by side
agent-cu move-window -a Finder --x 0 --y 25
agent-cu resize-window -a Finder --width 720 --height 475
# (open a second Finder window for destination)

# Step 2: Snapshot to find the file
agent-cu snapshot -a Finder -i -c -d 8

# Step 3: Get the file's position
agent-cu get-value @e32                    # check position

# Step 4: Drag to destination
agent-cu drag @e32 @e50 -a Finder         # drag by refs
# or by coordinates:
agent-cu drag --from-x 300 --from-y 55 --to-x 1000 --to-y 200 -a Finder

セレクター構文

参照先（常にこちらを優先）

@e1, @e2, @e3                         # from most recent snapshot

DSL

'role=button name="Submit"'            # role + exact name
'name="Login"'                         # exact name
'id="AllClear"'                        # exact id (most stable)
'id~="track-123"'                      # id contains (case-insensitive)
'name~="Clear"'                        # name contains (case-insensitive)
'button "Submit"'                      # shorthand: role name
'"Login"'                              # shorthand: just name
'role=button index=2'                  # 3rd match (0-based)
'css=".my-button"'                     # CSS selector (Electron apps only)

チェーン

'id=sidebar >> role=button index=0'    # first button inside sidebar
'name="Form" >> button "Submit"'       # submit button inside form

Electron アプリ（CDP）

Electron アプリ（Slack、Cursor、VS Code、Postman、Discord）は自動的に検出されます。初回使用時に、agent-cu が CDP 対応で再起動します。

すべての操作がヘッドレスで動作します。ウィンドウのアクティベーション、マウス、フォーカスの奪取は必要ありません。

agent-cu snapshot -a Slack -i -c           # full DOM tree via CDP
agent-cu click @e5                         # JS element.click()
agent-cu key cmd+k -a Slack                # CDP key dispatch
agent-cu type "hello" -a Slack             # CDP insertText
agent-cu scroll down -a Slack              # JS scrollBy()
agent-cu text -a Slack                     # document.body.innerText

Electron アプリでの入力：insertText はフォーカスされた要素に入力します。特定の入力欄に入力する必要がある場合は、次のようにします。

agent-cu snapshot -a Slack -i -c           # find the input ref
agent-cu click @e18                        # click to focus it
agent-cu key cmd+a -a Slack                # select all
agent-cu key backspace -a Slack            # clear
agent-cu type "your text" -a Slack         # now type

検証

操作が成功したと思い込んではいけません。ツリーを再度見るだけでなく、状態を示す属性を確認して検証してください。

id と name の違い（重要）

多くのアプリでは、ボタンに固定の id（スロット）と、変化する name（現在のラベル）が設定されています。

Music の再生コントロールボタンは典型的な例です。

• id は常に "play" です。現在再生中であっても、「再生コントロールボタン」として識別します。
• name は再生状態に応じて "play" と "pause" の間で切り替わります。

状態を検出するには、id ではなく name を読み取ります。

# check if music is playing
agent-cu find 'id="play"' -a Music --compact
# → [{"name":"pause", ...}]   ← means: playback is ON
# → [{"name":"play", ...}]    ← means: playback is OFF

同じパターンは多くのアプリに見られます。ブックマーク／ブックマーク解除、ミュート／ミュート解除、展開／折りたたみ、フォロー／フォロー解除などです。切り替えが成功したことを確認するときは、操作後に必ず要素の**現在の name**を読み取ってください。

--expect によるインライン検証

agent-cu click @e5 --expect 'name="Dashboard"'
# clicks, then polls for an element with name="Dashboard". Fails if it never appears.

値の読み取り

agent-cu get-value @e3                     # one element's value + role + position
agent-cu find 'id="play"' -a Music --compact   # most stable if id is known
agent-cu snapshot -a Safari -i -c          # broad check

冪等な入力

agent-cu ensure-text @e3 "hello"           # only types if value differs

動的に計算された値の読み取り（例：Calculator の計算結果）

一部のアプリでは、ラベル付きの要素に通常の value として結果が表示されず、staticText ノード内に隠れています。tree を使い、value を持つノードを探してください。

agent-cu tree -a Calculator -d 8 --compact | python3 -c "
import json, sys
d = json.load(sys.stdin)
def walk(n):
    if n.get('value'): print(n.get('role'), '=', repr(n['value']))
    for c in n.get('children', []): walk(c)
walk(d)
"
# → staticText = '1,234×7'
# → staticText = '8,638'

**ロケールに関する注意点：**数値はロケールに合わせて書式設定されます。インドのロケールでは 7^8 = 57,64,801、国際ロケールでは 5,764,801 と表示されます。値は同じです。比較する前に、カンマと空白を取り除いてください。

待機

UI の読み込みに時間がかかる場合：

agent-cu wait-for 'name="Dashboard"'       # poll until element appears
agent-cu wait-for 'role=button' --timeout 15
sleep 2                                # simple delay after navigation

バッチ操作

コマンドごとの起動を避けるため、複数のコマンドを連結します。

echo '[["click","@e5"],["key","Return","-a","Music"]]' | agent-cu batch --bail

実際の使用例

Music で曲を検索して再生する（検証済みの手順）

# 1. Open and snapshot
agent-cu open Music --wait
agent-cu snapshot -a Music -i -c
# → @e1 is the Search sidebar item

# 2. Click Search
agent-cu click @e1 -a Music

# 3. Type into the search field — use role=textField, not a ref (the ref
#    for the search field changes as the view switches)
agent-cu type "Espresso Sabrina Carpenter" -s 'role=textField' -a Music --submit
sleep 2  # let search results populate

# 4. Pick a result. Grep the snapshot for items matching the track name —
#    the `id` embeds a stable catalog id, so grab that.
agent-cu snapshot -a Music -c | grep -i "espresso" | head -5
# → [@e53] other("axcell") "Espresso" id=Music.shelfItem.TopSearchLockup[id=top-search-section-top-1744253558,...]

# 5. Open the album (double-click). Use the full id string, not the ref —
#    refs can drift between snapshots during long flows.
agent-cu click 'id="Music.shelfItem.TopSearchLockup[id=top-search-section-top-1744253558,parentId=top-search-section-top]"' -a Music --count 2
sleep 2

# 6. Find the track row and play. The track has a stable id pattern.
agent-cu snapshot -a Music -c | grep "track-lockup" | head -3
# → [@e52] group "Espresso" id=Music.shelfItem.AlbumTrackLockup[...]

# 7. Select, then try Return to play. If that fails, fall back to the
#    transport play button directly.
agent-cu click @e52 -a Music
agent-cu key Return -a Music
sleep 1

# 8. Verify via the transport button's `name` — "pause" means playing.
agent-cu find 'id="play"' -a Music --compact
# if name="play", playback didn't start. Fallback:
agent-cu click 'id="play"' -a Music

この手順から得られる重要な教訓：

• 画面の大きな変更を挟んだスナップショット間では、参照（@e53 など）が無効になることがあります。スナップショットをまたいで対象を指定する場合は、id="..." を完全な形で指定してください。
• type -s 'role=textField' --submit を使うと、入力、クリア、Return キーの押下を確実に組み合わせられます。
• 検索結果をダブルクリックすると、再生ではなく項目が 開く ことがよくあります。詳細画面に移動してから再生を開始してください。
• 再生コントロールボタンの name を使って、必ず再生状態を確認してください（id="play" はスロットを識別し、name が状態を示します）。
• Return で再生が始まらない場合は、代わりに再生コントロールボタンをクリックしてください。代替手段を用意しておきましょう。

Calculator で複数段階の計算を行う（検証済みの手順）

# 1. Open and snapshot — Calculator buttons have stable ids (Seven, Multiply, Equals, etc.)
agent-cu open Calculator --wait
agent-cu snapshot -a Calculator -i -c

# 2. Use batch for the whole keystroke sequence. Avoids 17 per-process starts.
#    Example: 7^8 = 7×7×7×7×7×7×7×7 = 5,764,801
echo '[
  ["click","id=\"AllClear\"","-a","Calculator"],
  ["click","id=\"Seven\"","-a","Calculator"],
  ["click","id=\"Multiply\"","-a","Calculator"],
  ["click","id=\"Seven\"","-a","Calculator"],
  ["click","id=\"Multiply\"","-a","Calculator"],
  ["click","id=\"Seven\"","-a","Calculator"],
  ["click","id=\"Multiply\"","-a","Calculator"],
  ["click","id=\"Seven\"","-a","Calculator"],
  ["click","id=\"Multiply\"","-a","Calculator"],
  ["click","id=\"Seven\"","-a","Calculator"],
  ["click","id=\"Multiply\"","-a","Calculator"],
  ["click","id=\"Seven\"","-a","Calculator"],
  ["click","id=\"Multiply\"","-a","Calculator"],
  ["click","id=\"Seven\"","-a","Calculator"],
  ["click","id=\"Multiply\"","-a","Calculator"],
  ["click","id=\"Seven\"","-a","Calculator"],
  ["click","id=\"Equals\"","-a","Calculator"]
]' | agent-cu batch

# 3. Read the result — walk the tree for any staticText with a value.
agent-cu tree -a Calculator -d 8 --compact | python3 -c "
import json, sys
d = json.load(sys.stdin)
for n in [d]:
    def walk(n):
        if n.get('value'): print(n.get('role'), '=', repr(n['value']))
        for c in n.get('children', []): walk(c)
    walk(n)
"
# → staticText = '7×7×7×7×7×7×7×7'     ← expression
# → staticText = '57,64,801'             ← result (Indian locale; strip commas → 5764801)

重要な教訓：

• アプリのすべてのインタラクティブ要素に安定した id= が設定されている場合（Calculator など）は、クリックの間にスナップショットを取得せず、コマンドをまとめて実行してください。
• 結果はラベル付きの要素にはありません。ツリーをたどって value を持つノードを探してください。
• 数値はロケールに合わせて書式設定されます。解析する前にカンマと空白を取り除いてください。

Slack で DM を開いてメッセージを送信する

agent-cu key cmd+k -a Slack
sleep 1
agent-cu snapshot -a Slack -i -c
# find and click the search input
agent-cu click @e18
agent-cu key cmd+a -a Slack
agent-cu key backspace -a Slack
agent-cu type "Vukasin" -a Slack
sleep 1
agent-cu key Return -a Slack
sleep 2
agent-cu type "hey, check this out" -a Slack
agent-cu key Return -a Slack

カレンダーのイベントを確認する

agent-cu open Calendar --wait
agent-cu snapshot -a Calendar -i -c -d 6
# read the visible dates
agent-cu text -a Calendar
# navigate to next month
agent-cu click @e3                         # next month button
sleep 1
agent-cu text -a Calendar

ウェブフォームに入力する

agent-cu open Safari --wait
agent-cu snapshot -a Safari -i -c
agent-cu type "https://example.com/form" -s @e34
agent-cu key Return -a Safari
sleep 3
agent-cu snapshot -a Safari -i -c -d 8
agent-cu type "John Doe" -s @e5
agent-cu type "[email protected]" -s @e6
agent-cu type "Hello world" -s @e7
agent-cu click @e8                         # submit button
agent-cu snapshot -a Safari -i -c          # verify submission

Finder のウインドウ間でファイルをドラッグする

# set up side-by-side windows
agent-cu move-window -a Finder --x 0 --y 25
# (ensure two windows open, Downloads left, Desktop right)
agent-cu snapshot -a Finder -i -c -d 8
# find the file (look for textfield with val="filename")
agent-cu click @e32                        # select the file
agent-cu drag --from-x 300 --from-y 55 --to-x 1000 --to-y 200 -a Finder

App Store を閲覧する

agent-cu open "App Store" --wait
agent-cu snapshot -a "App Store" -i -c -d 10
agent-cu click 'id="AppStore.tabBar.discover"' -a "App Store"
sleep 2
agent-cu scroll down --amount 5 -a "App Store"
agent-cu snapshot -a "App Store" -i -c -d 10
agent-cu text -a "App Store"

ルール

1. 操作する前に必ずスナップショットを取得してください。 見えないものは操作できません。
2. 操作した後も必ずスナップショットを取得してください。 UI が変わったため、参照は古くなっています。
3. 次のステップでは参照を、長期的には ID を使ってください。 参照（@e5）は、スナップショット取得直後の操作に最適です。id="..." セレクターはスナップショットをまたいで有効なため、ほかの UI 変更後に再び操作する要素にはこちらを使ってください。
4. スナップショットでは -i -c を使ってください。 インタラクティブかつコンパクトにすることで、ノイズを 10 分の 1 に減らせます。
5. アプリに安定した ID がある場合は、name= より id= を優先してください。 ID は状態が変わっても変化しませんが、名前は変わることがよくあります。
6. 状態を検出するには、id ではなく name 属性を読み取ってください。 多くのアプリでは id は固定スロットのまま、name が現在の状態（再生／一時停止、ミュート／ミュート解除、ブックマーク／ブックマーク解除）を示すように切り替わります。
7. 画面遷移後は待機してください。 まず既知の目印に対して wait-for を使い、目印がない場合は sleep 2-3 を使ってください。
8. 1 回操作したら、状態を確認してください。 状態を確認せずに複数の変更操作を連続して実行しないでください。
9. type -a App より type -s @ref を使ってください。 セレクターパスでは AXSetValue を使うため、信頼性があります。アプリパスはキーボードシミュレーションを使うため、脆弱で、フォーカスが必要です。
10. 要素が分かっている場合は scroll-to @ref を使ってください。 ヘッドレスで実行できます。scroll down にはフォーカスが必要です。
11. アプリ固有のロジックをハードコードしないでください。 play_song_in_music() のようなヘルパーは作らないでください。すべてのアプリで同じプリミティブ（snapshot、click、type、key、find）を使ってください。シーンツリーを確認して、読み取り、操作し、検証してください。
12. すべての操作にフォールバックを用意してください。 click で期待した状態変化が起きない場合は、ダブルクリック → scroll-to + click → キーボードショートカット → 直接操作できるボタン（例：トラック行で Return を押す代わりに、トランスポートの id="play" を使う）の順に試してください。「復旧手順」を参照してください。
13. ID が安定していて数が多い場合は、まとめて処理してください。 電卓、フォーム、キーパッドを使う操作では、JSON 配列を agent-cu batch にパイプで渡すと、N 回のプロセス起動を 1 回にできます。

復旧手順

うまくいかない場合の原則は、正確な失敗の種類を診断し、それに合ったフォールバックを適用することです。同じコマンドを何も考えずに再試行しないでください。

要素が見つからない（古い参照）

症状：以前のスナップショットから取得した @ref に対して、error: element not found matching SelectorChain { ... } が表示されます。

原因：参照は特定のツリーパスに解決されます。画面の大きな変更（画面遷移、スクロール、モーダルを開く操作）によって無効になります。

対処法：スナップショットを再取得して新しい参照を使うか、安定した id= に切り替えます。

agent-cu snapshot -a Safari -i -c
# …find it again, or use the full id you saw earlier:
agent-cu click 'id="the-stable-id"' -a Safari

複数のスナップショットをまたいで操作する対象には、id="..." を優先してください。参照は 1 ステップの操作にのみ使います。

セレクターが曖昧

症状：error: ambiguous selector: found N elements matching が表示されます。

対処法：index= を追加するか、ロール／名前で絞り込みます。

agent-cu click 'role=button index=0' -a Music
agent-cu click 'role=button name="Save"' -a TextEdit

クリックは成功したが、何も起こらない

症状：{"success": true, "message": "clicked at (X,Y)"} と表示されても、期待した状態変化（新しいページ、再生、メニュー表示）が起きません。

次の順に診断してください。

1. AXPress が使われましたか、それとも座標指定にフォールバックしましたか？
   • pressed "Name" at (X,Y) = AXPress に成功しました（最善）。
   • clicked at (X,Y) = 座標指定でクリックしました。要素が移動していたり、覆われていたりする可能性があります。
2. 要素の状態は本当に想定どおりですか？ ツリーだけでなく、状態を示す要素（例：Music のトランスポートボタン）の name 属性を読み取ってください。
3. 操作にはフォーカスが必要ですか？ アプリによっては（特に Web UI）、アプリが最前面に表示されている必要があります。agent-cu open App --wait でアクティブにできます。

フォールバックの順序：

# Ladder 1: AXPress failed — try double-click
agent-cu click @e5 --count 2

# Ladder 2: Element offscreen — bring it in, then click
agent-cu scroll-to @e5
agent-cu click @e5

# Ladder 3: The clicked element isn't the one that triggers the action —
#   drill into the container and find the explicit action button
agent-cu snapshot -a Music -c | grep -E "play|pause|Next"
agent-cu click 'id="play"' -a Music

# Ladder 4: Keyboard shortcut fallback
agent-cu key Return -a Music          # activate selected item
agent-cu key space -a Music           # play/pause

入力が反映されない

症状：フィールドにテキストが表示されません。

原因と対処法：

# Cause: no ref — fell back to keyboard sim which needs app focus
agent-cu type "hello" -a Safari
# Fix: use selector path (AXSetValue, reliable)
agent-cu type "hello" -s @e3

# Cause: field wasn't focused when keyboard sim fired
agent-cu click @e3              # focus it first
agent-cu type "hello" -s @e3    # then type

# Cause: existing value not cleared
agent-cu type "new" -s @e3 --append   # wrong: keeps old text
agent-cu type "new" -s @e3            # right: clears first

検索を送信したが、結果がまだツリーにない

症状：--submit の直後に snapshot を実行すると、前のページが表示されます。

対処法：待機してからスナップショットを再取得します。sleep よりポーリングを優先してください。

agent-cu type "query" -s 'role=textField' -a Music --submit
agent-cu wait-for 'name~="Top Results"' --timeout 5
agent-cu snapshot -a Music -i -c

wait-for で安定した目印が見つからない場合は、sleep 2 を使ってください。

スナップショットが浅すぎて、要素が見つからない

深さを増やしてください。

agent-cu snapshot -a Safari -i -c -d 8
agent-cu snapshot -a Safari -i -c -d 12   # for deeply nested apps

Ref が間違った対象を指している

症状：@e5 をクリックしても、期待したものではありません。

原因：スナップショットが気づかないうちに再実行され（2つ取得したため）、Ref の番号が振り直されました。

修正方法：重要な操作を行う前に、必ず Ref が解決した要素を確認してください。

agent-cu get-value @e5 -a Safari
# confirm role, name, id are what you expect, THEN click

Electron アプリが CDP を使用していない

agent-cu は Electron アプリを自動検出します。CDP が機能しない場合：

agent-cu snapshot -a Slack -i -c -v        # verbose shows CDP status

アプリが --remote-debugging-port を使って再起動するため、初回の実行には約5秒かかります。以降の実行ではキャッシュされた接続が使用されます（約15ms）。

DSL セレクターの解析エラー

症状：unknown filter key: 'id_contains'。

修正方法：部分一致には id_contains= ではなく、id~=（チルダと等号）の構文を使用します。

agent-cu click 'id~="track-"' -a Music
agent-cu click 'name~="Submit"' -a Safari

出力形式

すべての出力は JSON です。

{"success": true, "message": "pressed \"7\" at (453, 354)"}
{"error": true, "type": "element_not_found", "message": "..."}
{"role": "button", "name": "Submit", "value": null, "position": {"x": 450, "y": 320}}