DarwinRelay

ChatGPT を Mac 用のローカルエージェントに変える。

DarwinRelay はソースファーストの macOS MCP ランタイムで、ChatGPT や他の MCP クライアントに、あなたがすでに使っている Mac への構造化されたアクセスを提供します。シェルとファイル、本物の PTY、長時間実行ジョブ、バックグラウンド Chrome、ネイティブデスクトップ制御、永続化された Codex 履歴などです。

ChatGPT 自体をローカルコーディングエージェントのように使えます。リポジトリを調べさせ、失敗を再現させ、コードを変更させ、テストを実行させ、あなたのマシン上で結果を検証させることができます。会話と macOS の間に別のコーディングモデルを挟む必要はありません。

[!CAUTION] DarwinRelay は意図的に強力です。サンドボックスではありません。ファイルシステムやシェルコマンドの許可リストは実装されていません。接続されたクライアントは、ブリッジを実行している macOS ユーザーの実効権限で動作できます。クライアントを接続したり、ランタイムを localhost の外に公開したりする前に、SECURITY.md をお読みください。

ChatGPT をローカルエージェントとして使う

典型的な開発者タスクは、次のように簡単に始められます。

Use DarwinRelay and work on ~/Projects/myapp.

Find why authentication is failing. Reproduce the problem, fix the underlying
cause, run the relevant tests, and verify the result locally.

ChatGPT が DarwinRelay の完全なツールサーフェスを公開している場合、同じ会話でタスク全体をローカルループで進められます。

understand → inspect → reproduce → modify → execute → verify → iterate

DarwinRelay はそのワークフローに Codex を必要としません。ChatGPT が推論クライアントであり、DarwinRelay はあなたの Mac 上の実行ランタイムです。

ChatGPT の利用可能性

ChatGPT のカスタム MCP の利用可能性は OpenAI によって制御されており、DarwinRelay とは独立に変更される可能性があります。プラン、ワークスペース、ロールアウト、UI の動作は現在のドキュメントと異なる場合があるため、その ChatGPT セッションで使用できるものについては、アカウントに表示されるツールサーフェスを信頼できる情報源として扱ってください。接続を設定する際は、現在の OpenAI の開発者モードと MCP アプリのドキュメント を参照してください。

DarwinRelay 自体は MCP クライアントに中立であり、必要な MCP ツールサーフェスをサポートする他のクライアントでも使用できます。

ここで「ローカルエージェント」とは、ChatGPT の別の Agent モード 製品機能ではなく、ワークフローを指します。OpenAI は現在、Agent モードはカスタムアプリを使用しないと述べています。通常の ChatGPT 会話でカスタムアプリを選択して DarwinRelay を使用してください。

Related MCP server: OmniCommanderMCP

何ができるか？

• シェルとファイル — コマンドの実行、ファイルの参照・変更、パッチの適用、ローカルプロセスの管理。

• 本物の PTY — 対話型シェル、REPL、SSH、sudo プロンプト、TUI、長時間実行するターミナルプログラム。

• ジョブとプロセスライフサイクル — 1 回のツール呼び出しを超えて続く作業を開始し、後で調べ、シャットダウン時に回収する。

• ネイティブコンピュータ使用 — セマンティックな Accessibility クエリ/アクション、ウィンドウ、ダイアログ、ファイルパネル、スクリーンショット、OCR、キーボード/マウスのフォールバック、視覚的な待機。

• バックグラウンドブラウザ自動化 — 専用の Chrome プロファイルと拡張機能が所有するタブプールで、通常はフォーカスを奪わずにナビゲート、検査、入力、クリックが可能。

• Codex 履歴 — 再開したり別のモデルターンを開始したりせずに、永続化された Codex スレッドを読み取る。

• 認証付き MCP トランスポート — ローカルでは stdio、またはあなたが制御するトンネルの背後にある同梱の HTTP/OAuth フロントエンド。

• フェイルクローズのライフサイクル制御 — 明示的なフルアクセスロック解除、監査メタデータ、プロセス回収、シングルトンメニュー所有権、ロールバック対応のアプリ更新。

開発者ワークフロー

最初に役立つ DarwinRelay ワークフローは、ブラウザ自動化、ネイティブ UI 権限、Codex 履歴を必要としないはずです。

ChatGPT
  ↓
DarwinRelay
  ↓
local repository
  ↓
read files / run commands / edit code / run tests
  ↓
verify the result on the same Mac

コアのコーディングループが機能したら、タスクが必要な場合にのみ機能を追加します。

• 対話型デバッガ、REPL、SSH セッション、TUI には PTY を使用する。

• Web ワークフローにはバックグラウンド Chrome を使用する。

• ChatGPT が実際の macOS アプリを操作する必要がある場合は、ネイティブデスクトップ権限を付与する。

• 以前の Codex 作業を ChatGPT に調べさせたり続けさせたりする場合は、Codex 履歴を使用する。

コピー＆ペーストのワークフローについては examples/README.md を参照してください。

コーディングを超えて

DarwinRelay は、ローカルコード、プロセス、ブラウザ状態、ネイティブ macOS UI を 1 つの実行ループで組み合わせることができます。たとえば、デスクトップアプリのデバッグタスクは次のようになります。

launch the app
→ reproduce the issue through the real UI
→ inspect logs and code
→ fix the implementation
→ restart the app
→ repeat the UI flow
→ verify the fix

ネイティブデスクトップレイヤーは Accessibility を優先し、必要に応じて ScreenCaptureKit/Vision と合成入力にフォールバックします。ブラウザレイヤーは、日常のプロファイルを静かに乗っ取るのではなく、デフォルトで専用のローカル Chrome プロファイルを使用します。

すでに Codex を使っていますか？

DarwinRelay は、別の Codex モデルターンを開始せずに、永続化された Codex 履歴を読み取ることができます。これにより、Codex は必須の中間層ではなく、便利な継続性ソースになります。

Find the latest Codex thread for this project.
Summarize the objective, branch, changed files, current errors, and unfinished step.
Then inspect the live repository and continue the work from ChatGPT.

クイックスタート

DarwinRelay は現在 ソースファースト / 自己ビルド です。GitHub Releases はプリビルドの .app や .dmg を提供しておらず、現在の製品モデルには有料の Apple Developer Program メンバーシップは必要ありません。

1. 要件

コアの自己ビルド:

• macOS 13 以降。

• Node.js 18 以降（CI では Node.js 22 を使用）。

• メニューアプリとネイティブヘルパー用の Xcode Command Line Tools / swiftc。

メニューアプリの HTTP/Server URL パス経由で ChatGPT を使用するには、cloudflared もインストールし、ログインシェルの PATH で利用できるようにしてください。

オプションの機能:

• Accessibility、Screen Recording、Input/Post Events の権限 — ネイティブデスクトップ制御のみ。

• Full Disk Access — タスクが macOS で保護されたファイルシステムの場所を必要とする場合のみ。

• Google Chrome — 管理された chrome_* バックグラウンドワークスペースのみ。

• Codex CLI/履歴 — codex_thread_* 継続性ツールのみ。

2. インストールパスを選ぶ

オプション A — ローカルコーディングエージェントでインストール

すでに Codex、Claude Code、またはシェル/ファイルシステムアクセスを持つ別のローカルコーディングエージェントを使っていますか？ 自己ビルドを実行させましょう。

Install DarwinRelay on this Mac from:
https://github.com/dcierra/darwinrelay

Read AGENTS.md and the installation documentation first.

Install or verify the required dependencies, then build and install DarwinRelay
using the documented source-first/self-build path. Configure everything that
can be configured without weakening the project's security model.

Do not bypass macOS security controls. Do not use my personal Chrome profile.

When macOS requires Accessibility, Screen Recording, Input/Post Events, Full
Disk Access, Keychain access, or another user-consent step, stop and tell me
exactly what I need to approve manually.

After installation, verify that DarwinRelay starts correctly and report what
remains to connect it to my MCP client.

エージェントは推測するのではなく、リポジトリに従うべきです。このパスで曖昧な依存関係、ビルドステップ、権限の引き継ぎが明らかになった場合、それは DarwinRelay のスクリプト/ドキュメントで修正すべきオンボーディングバグであり、より長いプロンプトでごまかすべきものではありません。

オプション B — 手動でインストール

git clone https://github.com/dcierra/darwinrelay.git
cd darwinrelay
npm run check
./menubar/build.sh
open /Applications/DarwinRelay.app

ビルドスクリプトは、可能な場合（~/Applications にフォールバック）ローカルでビルドしたメニューアプリを /Applications にインストールします。DarwinRelay チェックアウトはそのままにしておいてください。 自己ビルドアプリは意図的にそのソースパッケージからランタイムを解決します。

ビルドは、利用可能な場合は永続的なローカルコード署名 ID を使用し、それ以外の場合はアドホック署名にフォールバックします。アドホックビルドは有料の Apple Developer メンバーシップなしで動作しますが、指定要件が変更される可能性があるため、再ビルド後に macOS TCC の許可を再付与する必要がある場合があります。

インストールの副作用なしのコンパイル/署名スモークテストには、次を使用します。

DARWINRELAY_APP_OUTPUT=/tmp/DarwinRelay.app ./menubar/build.sh --build-only

DarwinRelay の更新

./scripts/update.sh は DarwinRelay v0.6.5 以降に含まれています。既存のインストールが v0.6.4 以前の場合は、上記のインストール手順を使用して v0.6.5 への最後のソースファーストの手動アップグレード/再インストールを 1 回実行してください。v0.6.5 以降は、リリース間の変更にはアップデータを使用してください。

DarwinRelay v0.6.9 以降、メニューバーには Update DarwinRelay… も表示されます。明示的な確認を求め、独立した Terminal ウィンドウで同じ標準アップデータを開き、アプリが再起動している間進行状況を表示します。サイレントまたは自動更新パスはありません。

同じアップデータを、再起動しようとしている DarwinRelay MCP 接続を介さずに、通常のローカル Terminal/iTerm セッション（または別の独立したローカルシェル）から直接実行できます。

cd /path/to/darwinrelay
./scripts/update.sh

これにより、最新の安定版 vMAJOR.MINOR.PATCH リリースに更新されます。代わりに正確な公開リリースを選択するには:

./scripts/update.sh v0.6.5

アップデータは Git チェックアウトと /Applications/DarwinRelay.app を 1 つのトランザクションとして扱います。正規の GitHub オリジンを検証し、正確な安定版リリースタグに固定されたクリーンなチェックアウトを要求し、ソースの整合性をチェックし、移動されたタグとダウングレードを拒否し、同じ署名 ID で新しいアプリを原子的にインストールし、自動起動を更新し、フェイルクローズで再起動し、実際の MCP ドクターが CORE VERDICT: READY を返すことを要求します。アクティベーションに失敗した場合は、以前のチェックアウトと保持されたロールバックアプリの両方を復元しようとします。

これは意図的に git pull、git reset --hard を使用せず、ローカルの作業を削除しません。ダーティ/開発チェックアウトは拒否されます。開発の変更は、本番インストールをコーディングチェックアウトとして使用するのではなく、別のブランチ/ワークツリーに保持してください。

バックグラウンド Chrome 拡張機能はこのチェックアウトから未パックで読み込まれるため、マニフェスト/ソースを変更するリリースでは、専用の DarwinRelay プロファイルの Chrome の拡張機能ページで手動で Reload を 1 回行う必要がある場合があります。アップデータは拡張機能のバージョンが変更されたときにこれを報告します。個人プロファイルに置き換えないでください。

プロジェクトメンテナ向けに、アップデータ/ライフサイクルの変更には追加のプレリリースゲートがあります。公開タグが作成される前に、正確な未タグ候補が実際の Mac で scripts/test-update-candidate.sh を使用して実行されます。これはユーザー向けアップデータとは意図的に分離されており、任意のコミットが通常の更新ターゲットになることはありません。

3. ChatGPT を接続する

DR メニューバー項目を開き、Start を押します。MCP トランスポートが実行されているときは、Copy ChatGPT Setup を選択し、docs/CHATGPT.md に従ってください。

最初のコーディングワークフローには、Chrome、Codex 履歴、Accessibility、Screen Recording、Input 権限は必要ありません。タスクで実際に必要になったときに、後で設定してください。

4. 何かを変更する前に検証する

読み取り専用チェックから始めます。

Use DarwinRelay. Call bridge_status first.
Then list ~/Projects/myapp and read its top-level README/package metadata.
Do not modify files or run shell commands yet.

次に、ChatGPT がアカウントで DarwinRelay の書き込み/実行ツールを公開している場合は、実際のワークフローを試します。

Use DarwinRelay and work on ~/Projects/myapp.
Run the test suite, find one failing test, fix the underlying issue, rerun the
relevant tests, and verify the result. Do not deploy or force-push anything.

トラブルシューティングには、次を実行します。

./scripts/doctor.sh

ドクターは現在、オプションのネイティブデスクトップ、保護されたファイルシステム、バックグラウンド Chrome、Codex 機能とは別に、ブロッキングな Core / MCP コーディングパス の判定を提供します。選択したトランスポートに対して実際のローカル initialize → bridge_status スモークチェックを実行し、ブロッキングな失敗に対する次のアクションを出力します。より深いライフサイクル/ブラウザ診断はロードマップで進化し続けます。

ソースのみのローカル MCP 使用

ローカル stdio サーバーに接続できる MCP クライアントの場合、ブリッジはメニューアプリなしで直接実行することもできます。フルアクセスを明示的に確認する必要があります。

export DARWINRELAY_FULL_ACCESS_ACK=I_UNDERSTAND_THIS_GRANTS_FULL_ACCESS
node bridge.mjs

デフォルトのランタイム状態:

~/Library/Application Support/DarwinRelay
~/Library/Logs/DarwinRelay

DARWINRELAY_DATA_DIR、DARWINRELAY_LOG_DIR、DARWINRELAY_SHELL、DARWINRELAY_AUDIT_MODE などの環境変数を使用して、開発/テストインスタンスを分離します。

仕組み

flowchart LR
    A[MCP client] --> B[DarwinRelay bridge]
    B --> C[Shell / filesystem / jobs]
    B --> D[PTY helper]
    B --> E[Codex persisted history]
    B --> F[MacUIHelper]
    F --> G[Accessibility / ScreenCaptureKit / Vision / CGEvent]
    B --> H[Chrome native host]
    H --> I[DarwinRelay Chrome extension]
    I --> J[Background DR tab pool]

ネイティブデスクトップヘルパーは、特権デーモンではなく、意図的に短命です。メニューアプリ、MacUIHelper、仮想カーソルは安定したコード署名 ID を使用するため、永続的な署名 ID が利用可能な場合、macOS TCC の許可は通常の再ビルド後も維持できます。

コンポーネント、データフロー、信頼境界については docs/ARCHITECTURE.md を参照してください。

AI およびコーディングエージェント向け

このリポジトリには、意図的にエージェント向けのドキュメントが含まれています。リポジトリを Codex、Claude、ChatGPT、または別のコーディングエージェントに渡す場合は、まず AGENTS.md を指してください。リポジトリマップ、不変条件、開発コマンド、テストの期待、署名/ブラウザのルール、リリース制約が説明されています。

ソースを変更するのではなく、すでにインストールされている DarwinRelay ランタイムを操作するエージェントには、docs/AGENT_OPERATIONS.md を使用してください。完全なツールファミリーマップ、推奨される決定順序、一般的な失敗状態、安全なランタイムワークフローが含まれています。

ネイティブデスクトップ制御

DarwinRelay はセマンティックな Accessibility 操作を優先し、視覚/生の入力をフォールバックとして使用します。コア機能には以下が含まれます。

• ui_observe、ui_tree、ui_ax_query、ui_ax_at;

• フィンガープリント付きAX参照と、古い参照の検出機能;

• ui_action、ui_wait_for、ui_assert;

• ui_app_*、ui_window_*、ダイアログ、ファイルパネル;

• ScreenCaptureKitによるスクリーンショットとVision OCR;

• macOSがサポートする場合の、PIDを指定したバックグラウンド入力（セマンティック検証と、フォアグラウンドへのフォールバックに上限付き）;

• 決定的なマルチステップのネイティブ操作を実現するui_sequence;

• 物理ポインタを動かさない、クリックスルー型の仮想AIカーソル。

制御モデルと制限事項については、docs/DESKTOP_CONTROL.mdを参照してください。

バックグラウンドChromeワークスペース

DarwinRelayは、展開前のChrome拡張機能とNative Messagingを使用します。公開されている拡張機能のIDは安定しており、想定される拡張機能IDは次のとおりです:

pfhahlehpahegefejooendokpkklgmgd

インストーラは、デフォルトで**サインアウト済みのローカルChromeプロファイル（名前はDarwinRelay）**を作成するか、再利用します。これにより、エージェントのブラウジング状態が日常的なGoogleプロファイルから分離されます:

# Recommended/default: dedicated local profile named DarwinRelay
./scripts/install-background-chrome.sh

# Explicit alternatives only when you want them
./scripts/install-background-chrome.sh --profile 'Some Existing Profile'
./scripts/install-background-chrome.sh --use-current-profile

DarwinRelayプロファイルがまだ存在しない場合は、インストーラを実行する前にChromeを一度終了して、ChromeがLocal Stateを同時に書き換えないようにしてください。プロファイルが存在すれば、通常の再インストールはChromeを開いたまま実行できます。DarwinRelayをアンインストールしても、ブラウザプロファイルの内容はユーザーデータであるため、そのプロファイルは意図的に残されます。

次に、選択したプロファイル内でのみ、chrome://extensionsを開き、デベロッパーモードを有効にして、パッケージ化されていない拡張機能を読み込むを選択し、このリポジトリのchrome-extension/ディレクトリを選択します。この1回限りのセットアップ手順では、インストーラに--openを渡すことができます。

この拡張機能は、DRという名前のChromeネイティブタブグループを所有します。通常のchrome_open呼び出しは、任意のフォアグラウンドタブを作成する代わりに、事前に作成されたアイドルタブをリースします。chrome_closeはワークスペースタブをプールに戻します。

ブラウザのセキュリティモデル

緩和された承認がデフォルトです。設定されたchrome_*ワークスペースを通じた通常のHTTP/HTTPS作業には、サイトごとのターミナル許可は必要ありません。メニューアプリで厳格な承認を有効にすると、スコープ付きURL許可と、アプリスコープのネイティブ変更に対する1回限りの承認が復元されます。

シェル/AppleScript/JXAによる直接のChrome自動化はブリッジによって引き続きブロックされるため、通常のWeb作業は管理されたバックグラウンドパス上に維持されます。ブラウザ/OSのセキュリティサーフェスが本当にそれを必要とする場合、別個のネイティブui_*サーフェスは、フォアグラウンドのChrome UIと対話できます。

オプションの生のBrowser Harness/CDPアダプタがDARWINRELAY_ADVANCED_BROWSER=1の背後に存在します。これはデフォルトで無効になっており、任意のCDPをURLスコープに健全に還元できないため、厳格な承認の下ではフェイルクローズドになります。

HTTP / OAuthトランスポート

mcp-http.mjsはループバックにバインドされ、静的ベアラートークンと、リモートMCPクライアントが使用するOAuth 2.1フローを備えたMCP HTTPトランスポートをサポートします。Cloudflareなどのトンネルを使用すると、ループバックサービスをHTTPS経由で公開できます。

通常のChatGPT Server URLパスでは、メニューアプリが推奨されるエントリポイントです。DEPLOY.mdには、上流プロジェクトから引き継がれたOpenAI Secure MCP Tunnelパスを含む、手動/高度なトランスポート設定が記載されています。

SECURITY.mdのリモートアクセスの脅威モデルを読まずにHTTPエンドポイントを公開しないでください。このフロントエンドが受け入れる認証情報は、最終的にはデスクトップユーザーとしてのローカルコード実行を許可します。

開発

npm run check
npm run test:core
npm run test:desktop
npm run test:lifecycle
# or all groups
npm test

公開CIは、1つの不透明なtestジョブではなく、意図的に個別のチェックを公開しています:

• 静的チェック — 構文/ネイティブビルドの検証と、全履歴のgitleaksスキャン;

• コアおよびプロトコルテスト — MCP、HTTP/OAuth、PTY、フェデレーション、ブラウザ、および敵対的テスト;

• デスクトップ制御テスト — 決定的なデスクトッププロトコルテストと、ネイティブフィクスチャのコンパイル;

• インストールおよびライフサイクルテスト — インストーラ、自動起動、シングルトン所有権、ロールバック、およびアンインストールの動作。

実際の可変AppKit E2Eには、TCC権限を持つログイン済みMacが必要なため、使い捨てのGitHubホスト型GUIセッションでは信頼できるものとして扱われません。メンテナはローカルで次のコマンドを実行できます:

DARWINRELAY_RUN_NATIVE_DESKTOP_E2E=1 node tests/desktop-control-native.mjs

プルリクエストを開く前に、CONTRIBUTING.mdを参照してください。現在の開発優先事項はROADMAP.mdで追跡されています。

セキュリティ

重要な境界は単純です: DarwinRelayは、それを実行するmacOSアカウントの権限を持ちます。 ロック解除ファイル、厳格な承認、監査メタデータ、OAuth、バックグラウンドブラウザルーティング、プロセス再利用などのセキュリティ機能は、偶発的またはリモートでの悪用を減らします。これらは、任意のシェルアクセスをサンドボックスに変えるものではありません。

セキュリティレポートは、公開issueではなく、GitHubのプライベート脆弱性報告を使用してください。SECURITY.mdを参照してください。

プロジェクトの系譜

DarwinRelayは独立してメンテナンスされており、Alexander Rådahl BenzによるMac Developer Bridgeから大幅に分岐しています。継承された上流の履歴は意図的に保存されており、元のMIT著作権表示はLICENSEに残っています。正確な系譜と帰属ポリシーについては、UPSTREAM.mdを参照してください。

公開されているdcierra/darwinrelayリポジトリが正規の開発ソースです。開発/リリースモデルについては、docs/DEVELOPMENT_MODEL.mdを参照してください。

DarwinRelayは、OpenAI、Apple、Google、Cloudflare、または上流メンテナとは提携しておらず、その承認も受けていません。

ライセンス

MIT。LICENSEおよびUPSTREAM.mdを参照してください。