usecomputer

usecomputer

AI エージェント向けのデスクトップ自動化 CLI です。macOS、Linux（X11）、Windows で動作します。スクリーンショットの撮影、クリック、入力、スクロール、ドラッグを、実行時に Node.js を必要とせず、Zig バイナリを介してネイティブプラットフォーム API で実行します。

まず必ず --help を実行してください

このツールを使う前に、必ず usecomputer --help を実行してください。 ヘルプ出力が、すべてのコマンド、オプション、使用例の正式な情報源です。コマンド構文を推測せず、最初にヘルプを確認してください。

ヘルプコマンドを実行するときは、省略されていない出力全体を読んでください。ヘルプを head、tail、sed にパイプしないでください。重要なオプションを見落とす可能性があります。

usecomputer --help
usecomputer screenshot --help
usecomputer click --help
usecomputer drag --help

インストール

npm install -g usecomputer

要件：

• macOS — ターミナルアプリでアクセシビリティ権限を有効にします
• Linux — DISPLAY が設定された X11 セッション（XWayland 経由の Wayland も動作します）
• Windows — 対話型デスクトップセッションで実行します

基本的なループ：スクリーンショット -> 操作 -> スクリーンショット

コンピューター操作のセッションは、すべて次のフィードバックループに従います。

screenshot -> send to model -> model returns action -> execute action -> screenshot again
     ^                                                                        |
     |________________________________________________________________________|

1. usecomputer screenshot --json でスクリーンショットを撮影します
2. スクリーンショット画像をモデルに送信します
3. モデルが座標または操作（クリック、入力、キー押下、スクロール）を返します
4. 手順 1 の 正確な --coord-map を渡して操作を実行します
5. 新しいスクリーンショットを撮影し、手順 2 に戻ります

一連の流れの例

# 1. take screenshot (always use --json to get coordMap)
usecomputer screenshot ./tmp/screen.png --json
# output: {"path":"./tmp/screen.png","coordMap":"0,0,3440,1440,1568,657",...}

# 2. send ./tmp/screen.png to the model
# 3. model says: "click the Save button at x=740 y=320"

# 4. click using the coord-map from the screenshot output
usecomputer click -x 740 -y 320 --coord-map "0,0,3440,1440,1568,657"

# 5. take a fresh screenshot to see what happened
usecomputer screenshot ./tmp/screen.png --json
# ... repeat

--coord-map を省略しないでください。 スクリーンショットは拡大縮小されます（最長辺は最大 1568px）。coord-map は、スクリーンショット上のピクセル座標を実際のデスクトップ座標に対応付けます。これがないと、クリック位置がずれてしまいます。

操作のたびに、必ず新しいスクリーンショットを撮影してください。 クリック、スクロール、キー入力のたびに UI が変化し、メニューが開いたり、ページがスクロールしたり、ダイアログが表示されたりします。古いスクリーンショットを再利用しないでください。

ウィンドウ単位のスクリーンショット

デスクトップ全体のスクリーンショットには、ドック、メニューバー、背面のウィンドウなど、すべてが含まれます。精度を高めるには、対象アプリケーションのウィンドウだけを撮影してください。画像が小さく、モデルが状況を把握しやすくなります。

手順 1：ウィンドウ ID を確認する

usecomputer window list --json

このコマンドは、表示中のウィンドウについて、id、ownerName、title、位置、サイズを含む配列を返します。対象とするウィンドウを見つけてください。

手順 2：そのウィンドウのスクリーンショットを撮影する

usecomputer screenshot ./tmp/app.png --window 12345 --json
# output: {"path":"./tmp/app.png","coordMap":"200,100,1200,800,1568,1045",...}

出力の coord-map は、画面上のそのウィンドウの領域に対応しています。

手順 3：coord-map を使って操作する

# model analyzes ./tmp/app.png and says click at x=400 y=220
usecomputer click -x 400 -y 220 --coord-map "200,100,1200,800,1568,1045"

coord-map によって、ウィンドウのスクリーンショット上のピクセル座標が、正しいデスクトップ座標に変換されます。スクリーンショットに表示されているのが 1 つのウィンドウだけでも、クリックは正しい位置に届きます。

領域のスクリーンショット

画面上の任意の矩形領域を撮影することもできます。

usecomputer screenshot ./tmp/region.png --region "100,100,800,600" --json

coord-map は同様に機能します。後続のポインターコマンドに渡してください。

Coord-map の説明

coord-map は、各スクリーンショットで出力される、カンマ区切りの 6 つの値です。

captureX,captureY,captureWidth,captureHeight,imageWidth,imageHeight

• captureX, captureY — デスクトップ座標における、撮影領域の左上の位置
• captureWidth, captureHeight — デスクトップ上のピクセル単位で表した、撮影領域のサイズ
• imageWidth, imageHeight — 出力 PNG のサイズ（拡大縮小後）

click、hover、drag、mouse move に --coord-map を渡すと、コマンドはこれらの値を使って、スクリーンショット上の x,y 座標を実際のデスクトップ上の位置に対応付けます。

debug-point による座標の検証

クリックする前に、クリック位置を検証できます。

usecomputer debug-point -x 400 -y 220 --coord-map "0,0,1600,900,1568,882"

このコマンドはスクリーンショットを撮影し、対応付けられた座標に赤いマーカーを描画します。出力画像をモデルに送り返すと、対象位置が正しいか確認し、必要に応じて調整できます。

使用例

# screenshot the primary display
usecomputer screenshot ./tmp/screen.png --json

# screenshot a specific display (0-indexed)
usecomputer screenshot ./tmp/screen.png --display 1 --json

# click at screenshot coordinates
usecomputer click -x 600 -y 400 --coord-map "0,0,1600,900,1568,882"

# right-click
usecomputer click -x 600 -y 400 --button right --coord-map "..."

# double-click
usecomputer click -x 600 -y 400 --count 2 --coord-map "..."

# click with modifier keys held
usecomputer click -x 600 -y 400 --modifier option --coord-map "..."
usecomputer click -x 600 -y 400 --modifier cmd --modifier shift --coord-map "..."

# type text
usecomputer type "hello from usecomputer"

# type long text from stdin
cat ./notes.txt | usecomputer type --stdin --chunk-size 4000 --chunk-delay 15

# press a key
usecomputer press "enter"

# press a shortcut
usecomputer press "cmd+s"
usecomputer press "cmd+shift+p"

# press with repeat
usecomputer press "down" --count 10 --delay 30

# scroll
usecomputer scroll down 5
usecomputer scroll up 3
usecomputer scroll down 5 --at "400,300"

# drag (straight line)
usecomputer drag 100,200 500,600

# drag (curved path with bezier control point)
usecomputer drag 100,200 500,600 300,50

# drag with coord-map
usecomputer drag 100,200 500,600 --coord-map "..."

# mouse position
usecomputer mouse position --json

# list displays
usecomputer display list --json

# list windows
usecomputer window list --json

# list desktops with windows
usecomputer desktop list --windows --json

正確なクリックのためのシステムプロンプトのヒント

GPT-5.4 または Claude でコンピューターを操作する場合は、システムプロンプトを短く、タスクに集中した内容にしてください。冗長なシステムプロンプトはクリックの精度を低下させます。

GPT-5.4： スクリーンショット入力には detail: "original" を使用してください。これはクリック精度に最も重要な設定です。detail: "high" や detail: "low" は使用しないでください。

Claude： computer_20251124 ツールタイプを使用し、display_width_px と display_height_px を coord-map の出力にあるスクリーンショットの寸法に合わせてください。

一般的なルール：

• アクションを実行するたびに、新しいスクリーンショットを撮影してください
• モデルが分析したスクリーンショットの coord-map を必ず渡してください
• クリック位置がずれる場合は、debug-point を使用して原因を調べてください
• モデルがスクリーンショットの寸法を超える座標を返した場合は、スクリーンショットを再送信し、画像サイズを伝えてください

トラブルシューティング

1. クリック位置がずれる — --coord-map を忘れたか、モデルが分析したものとは異なるスクリーンショットの coord-map を渡している可能性があります。必ず最新のスクリーンショットの coord-map を使用してください。

2. Retina ディスプレイ — usecomputer は coord-map を使って内部でスケーリングを処理します。ディスプレイのスケーリングを手動で考慮しないでください。

3. 古いスクリーンショット — バグの最も一般的な原因です。アクションのたびに必ず新しいスクリーンショットを撮影してください。UI は常に変化します。

4. macOS での権限エラー — システム設定 > プライバシーとセキュリティ > アクセシビリティで、ターミナルアプリのアクセシビリティ権限を有効にしてください。

5. Linux での X11 エラー — DISPLAY が設定されていることを確認してください。XWayland では、XShm が失敗するとスクリーンショットは自動的に XGetImage にフォールバックします。