umbriel

これは何ですか？

Umbriel は、目の前のアプリで実際に機能する手段を使い、人が操作するように Windows デスクトップを操作します。

1. ピクセルと OCR — アプリが UI ツリーをまったく公開していない場合（キャンバス、カスタム描画、ゲームなど）は、全画面キャプチャ、テンプレートマッチング、テキスト認識にフォールバックします。
2. セマンティック操作 — アプリが公開する UI Automation ツリーを読み取り、座標ではなく 名前 と ロール でコントロールを指定します。ピクセルベースのスクリプトを壊す DPI、レイアウト、テーマの変更にも対応できます。
3. 画面の確認とウィンドウ操作 — あらゆるウィンドウの ライブ ピクセルをキャプチャし（GPU 合成や他のウィンドウによる遮蔽がある場合も含む）、HWND の階層を直接調べ、ウィンドウの移動、前面表示、サイズ変更ができます。
4. 入力のルーティング — バックグラウンドで操作できるコントロールにはセマンティック UIA とメッセージ送信入力を使用します。HWND のないエディターや実際のポインタージェスチャーでフォアグラウンドが必要な場合に限り、検証済みの SendInput にフォールバックします。
5. GUI だけでなく OS を操作 — タスクの対象が マシンそのもの の場合は、直接操作します。レジストリの読み書き（値 と キー）、プロセスの一覧表示／強制終了／一時停止／優先度変更、サービスの照会／開始／停止／設定、スケジュールされたタスクの作成／削除／列挙、ファイアウォール規則の読み取り、ネットワークアダプターと稼働中の接続の列挙、セッション電源の操作（ロック／再起動／スリープ／休止状態）、ボリュームと空き容量の一覧表示、環境変数の取得と設定、イベントログの読み取り、ディスプレイモードの読み取り または変更 をすべてネイティブに行い、PowerShell やシェルの起動は不要です。

内部では、Bun 組み込みの FFI を使った数キロバイトの TypeScript で動作します。Appium サーバー、.NET、node-gyp、ビルド済みバイナリは不要です。

インストール

bun add umbriel

インストール手順はこれだけです。ビルドもコンパイルも必要ありません。

AI エージェント向けに構築

これこそが Umbriel の 用途 です。公開済みサーバーを Codex に登録します（ChatGPT デスクトップ、CLI、IDE ではこの設定が共有されます）。

codex mcp add umbriel -- bunx umbriel

または、Claude に登録します。

claude mcp add umbriel -- bunx umbriel

MCP に対応するエージェントなら、ステップごとに約 15 ms でアクセシビリティツリーを基盤に動作し、対象に応じてセマンティック方式、投稿メッセージ方式、合成入力方式、またはピクセルフォールバックを利用できます。従来型のコントロールの多くは、ウィンドウをバックグラウンドにしたまま操作できます。独自の HWND を持たない Chromium／WPF／WinUI エディターでは、実際に入力するために、短時間、ロック解除されたフォアグラウンドリースが必要です。Umbriel は入力を注入する前に対象ウィンドウを検証し、エディターの状態を検証することもでき、デフォルトでは以前のフォアグラウンドウィンドウを復元します。

スクリーンショットを使うエージェントは、ステップごとに画像トークンを消費します。そのうえ、ピクセルから状態を読み取れないため、自分の操作結果を確認するスクリーンショットにも 再び トークンを消費します。Umbriel はウィンドウ全体をプレーンテキストに変換し、一度キャッシュすれば複数のステップで再利用できます。また、そのマップから結果を直接読み取ります。これは Microsoft の UFO2 と OSWorld-Human ベンチマークが推奨するのと同じ基盤化方式（まず構造、次に視覚）を、コストをかけずに実現します。

umbriel.tree(app, { agentProfile: true });
// → one cached round-trip → { role, name, automationId, bounds, children }

⚡ ウィンドウを 約 13 ms でマッピング · トークンは画像ではなく、一度キャッシュして再利用するテキストです。ステップごとに画像を買い直す必要はありません · 3～26 秒かかるスクリーンショットパイプラインと比べ、基盤化を最大 約 2000 倍高速化

エージェントのステップごと	スクリーンショットを使うエージェント	Umbriel
トークン	画像 1.5～2.7k — さらに自己確認のため再撮影	テキスト約 3k — キャッシュして複数のステップで再利用
基盤化にかかる時間	3～26 秒	約 13 ms
状態を読み返せるか	いいえ — もう一度スクリーンショットを撮る必要あり	はい — スナップショットから直接読み取り

_{Umbriel の数値は Windows 11、Bun 1.4 で計測しています（Calculator で 14.3 ms・約 3k トークン、単一プロパティの読み取りは約 58 µs）。bun run example/benchmark.ts で再現できます。スクリーンショットパイプラインの数値は、公開されているサードパーティの結果です（OSWorld-Human、コンピューター操作における画像トークンのコスト）。}

MCP サーバーは、デプロイ担当者が制御するポリシーのもと、スナップショット優先のツールを 99 個公開します（デフォルトの safe プロファイルでは 76 個、readonly では 41 個。os/fs ツール 23 個には full または UMBRIEL_OS=1 が必要です）。

UMBRIEL_PROFILE=readonly   # observe only
UMBRIEL_PROFILE=safe       # default — observe + cursor-free control + window management
UMBRIEL_PROFILE=full       # everything, including launch/run/file tools

desktop_snapshot は参照キー付きのビュー（Button "Five" [ref=e49#3] など）を返し、各アクションへの応答では、忠実性を保った最小限の更新を返します。変更が少ない場合はコンパクトな差分を、変更が多い場合は不要な情報を取り除いたスナップショットを返します。モデルはトークンに埋もれることなく、再び基盤化できます。

時系列順のチャットやログでは、desktop_snapshot { root: "Messages in general", tail: 20, maxDepth: 2 } を指定すると、最新の直下の子要素のみが返されます。これにより、返信が必要なメッセージにたどり着く前に、読み込まれた過去の行を何百件も処理するコストを避けられます。

ウィンドウハンドルがすでに分かっている場合は、最初の呼び出しで同じ範囲を指定できます。attach { hWnd: "0x123", root: "Messages in general", tail: 20, maxDepth: 2 } を使います。ほかの大きな初期ツリーを制限するには、root を指定せずに maxDepth／maxNodes を使います。

Discord の Slate コンポーザーのような制御されたウェブエディターでは、MCP の type ツールを method: "paste"、verify: true、submit: true とともに使います（既存の下書きを置き換えてよいと確認した後に限り、clear: true も指定します）。UIA set_value は、公開されている DOM の値を変更しても、アプリケーション内部のエディターモデルを更新しないことがあるため、バックグラウンドで送信する信頼できる方法ではありません。送信が不確かな場合は未検証として報告されます。決して確認せずに再試行しないでください。

コードから使う

Umbriel は、E2E テストやデスクトップ自動化向けの一流のライブラリでもあります。ウェブで getByRole を使うのと同じように、名前で検索 → 待機 → 操作 → アサートできます。

import { ControlType, umbriel } from 'umbriel';

const app  = await umbriel.launch(['notepad.exe'], { className: 'Notepad' });
const edit = await app.waitFor({ controlType: ControlType.Document });

edit.focus().type('nothing native compiles, and it just works');
console.log(edit.text()); // → nothing native compiles, and it just works

// Drive Calculator to 5 + 3 = 8 — by name, not pixels:
const calc = await umbriel.launch(['cmd', '/c', 'start', 'calc'], { title: 'Calculator' });

for (const name of ['Five', 'Plus', 'Three', 'Equals'])
  calc.find({ controlType: ControlType.Button, name })?.invoke();

console.log(calc.find({ automationId: 'CalculatorResults' })?.name); // → "Display is 8"

Umbriel を選ぶ理由

npm の Windows デスクトップ自動化分野は、ネイティブアドオンのビルド失敗、ペイウォール、放置されたデーモンがひしめく危険地帯です。Node や Bun 向けの、インストール不要で型付けされたプロセス内 Windows 自動化クライアントは、これまで存在しませんでした。Umbriel が登場するまでは。

Umbriel は Bun 独自の FFI を使った純粋な TypeScript なので、次の特長があります。

• ペイウォールを設けられません — サブスクリプションレジストリの背後に置くコンパイル済みバイナリがありません。
• ビルド工程がありません — ABI マトリックスも、MSVC や Python のツールチェーンも、node-gyp も不要です。
• プロセス内で Windows と通信します — 127.0.0.1:4723 への往復も、Appium デーモンも、開発者モードも、WinAppDriver も不要です。

代替ツールとの比較（npm の週間ダウンロード数、2026-06-05 の週）

ツール	週間 DL 数	注意点
FlaUI / pywinauto / AutoIt	n/a	別のランタイム（.NET / Python / 専用 EXE）をインストールして配布する必要があります。
@bright-fish/node-ui-automation	33	唯一の本格的な npm UIA ラッパーですが、2022 年以降更新されていません。
@nut-tree-fork/nut-js	32,360	現在はペイウォール化された元のパッケージのフォークです。ピクセル／画像マッチングのみで、セマンティックモデルはありません。
appium-windows-driver	30,749	Appium サーバーに加え、Microsoft が何年も保守していない別の WinAppDriver.exe が必要です。
robotjs / @jitsi/robotjs	11,375 / 15,333	node-gyp による C++ コンパイルが必要で、インストール失敗として最も多く報告されています。ピクセルとキーストロークに頼る方式で、要素モデルはありません。
uiohook-napi	21,965	活発に保守されていますが、グローバルフックは別のスレッドで実行され、セグメンテーション違反が起きる可能性があります。

主な特長

	機能	内容
🌐	Chromium と Electron	Chrome、Edge、Electron アプリ（Discord、Slack、Spotify、VS Code）のページ内 DOM を実際の要素として操作します。ネイティブコントロールと同じ API を使用できます。
🛠️	GUI だけでなく OS も操作	レジストリ（読み取り＋型付き書き込み＋キーの作成／削除）、プロセス（情報取得／強制終了／一時停止／優先度変更）、サービス（設定を含む）、スケジュールされたタスク（作成／削除を含む）、ファイアウォールルール、ネットワークアダプターと接続、セッションの電源管理、ボリュームと空き容量、環境変数、イベントログ、ディスプレイ（読み取り＋表示モード設定）に対応します。すべてネイティブで、PowerShell は不要です。
📋	クリップボード	1 文字ごとの入力による破損なしに長文を貼り付けられ、あらゆるアプリからコピーして読み取ることもできます。
🌑	バックグラウンドで操作	invoke / scroll / setValue / toggle はカーソルを動かさず、非表示、最小化、遮蔽、ロック中のウィンドウでも動作します。
🖼️	ピクセルと OCR によるフォールバック	キャンバスやゲーム向けに、座標クリック、画面全体のキャプチャ、テンプレートマッチング、テキスト認識を利用できます。
🔎	あらゆる情報を読み取り	MSAA ツリー、境界ボックス、データグリッドのセル、有効／チェック状態、ネイティブ HWND 階層、テキスト、値を読み取れます。
🌍	Unicode を正確に入力	日本語、韓国語、アクセント付きラテン文字、絵文字を 3 つの入力経路でやり取りできます。回帰テストで検証済みです。
👁️	見えないものも確認	Windows.Graphics.Capture を介して、GPU 合成されたウィンドウや遮蔽されたウィンドウのライブピクセルをキャプチャします。
🎯	セマンティックターゲティング	automationId、名前、ロールでコントロールを検索できます。対象アプリ内で完全一致に絞り込むため、高速です。
🧩	スタック全体に対応	Electron／Chromium、Java、Qt、WPF、Win32、WinForms、WinUI／UWP に対応し、それぞれ専用の回帰テストで保証されています。
⏳	waitFor	不安定なネイティブ UI に対する Playwright 形式の自動再試行機能です。タイムアウト時には、セレクターと最も近い候補を示します。

要件

• まずセマンティクスを優先し、構造がない場合はピクセルを使用 — カスタム描画、ゲーム、WebGL サーフェスでは、組み込みのピクセル＋OCR レイヤーにフォールバックします。ツリーがあるものはすべて、正確なセマンティックターゲティングが可能です。
• 合成入力と実際のクリックには、ロック解除されたデスクトップが必要です — invoke、読み取り、setValue はロック中のセッションでも機能するため、これらを優先してください。
• 最小化した状態での操作は、従来型の Win32 ウィンドウ向けです — invoke／setValue／toggle は、最小化または完全にバックグラウンド化された従来型の Win32／HWND ウィンドウでも引き続き機能します。一方、UWP／WinUI ストアアプリでは、最小化すると UI スレッドとアクセシビリティツリーが一時停止します（ツリーの読み取り結果は空になり、投稿されたアクションは復元するまで反映されません）。そのため、まず復元してください。
• Windows 10 または 11、Bun ≥ 1.1 — Windows 専用、Bun 専用です。依存関係ゼロとプロセス内での速度を実現するために選択した仕様です。

さらに詳しく

API の全容は AI.md に記載されています。エージェント（または開発者）がソースを読む必要がないほど詳細に書かれています。実行可能なデモは example/ にあります。

---