DarwinRelay

Превратите ChatGPT в локального агента для вашего Mac.

DarwinRelay — это среда выполнения MCP для macOS, ориентированная на исходный код, которая предоставляет ChatGPT и другим MCP-клиентам структурированный доступ к вашему Mac: оболочка и файлы, настоящие PTY, длительные задачи, фоновый Chrome, нативное управление рабочим столом и сохранённая история Codex.

Используйте сам ChatGPT как локального агента для кодинга: позвольте ему изучить репозиторий, воспроизвести сбой, изменить код, запустить тесты и проверить результат на вашей машине — без встраивания ещё одной модели кодинга между разговором и macOS.

[!CAUTION] DarwinRelay намеренно очень мощный. Это не песочница, и он не реализует белый список файловой системы или команд оболочки. Подключённый клиент может действовать с эффективными правами пользователя macOS, запускающего мост. Прочтите SECURITY.md перед подключением клиента или предоставлением доступа к среде выполнения за пределами localhost.

Используйте 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

Доступность пользовательских MCP-коннекторов ChatGPT контролируется OpenAI и может меняться независимо от DarwinRelay. План, рабочее пространство, развёртывание и поведение интерфейса могут отличаться от текущей документации, поэтому считайте набор инструментов, показанный в вашей учётной записи, авторитетным для того, что может использовать этот сеанс ChatGPT. При настройке подключения обратитесь к текущей документации OpenAI по режиму разработчика и MCP-приложениям.

Сам DarwinRelay остаётся нейтральным к MCP-клиентам и может использоваться другими клиентами, поддерживающими требуемый набор инструментов MCP.

Здесь «локальный агент» описывает рабочий процесс, а не отдельную функцию продукта Agent mode в ChatGPT. OpenAI в настоящее время заявляет, что Agent mode не использует пользовательские приложения; используйте DarwinRelay из обычного разговора ChatGPT с выбранным пользовательским приложением.

Related MCP server: OmniCommanderMCP

Что он умеет?

• Оболочка и файлы — запуск команд, просмотр или изменение файлов, применение патчей и управление локальными процессами.

• Настоящие PTY — интерактивные оболочки, REPL, SSH, запросы sudo, TUI и долго работающие терминальные программы.

• Задачи и жизненный цикл процессов — запуск работы, которая переживает один вызов инструмента, проверка её позже и возврат при завершении работы.

• Нативное использование компьютера — семантические запросы/действия Accessibility, окна, диалоги, панели файлов, скриншоты, OCR, запасной вариант клавиатуры/мыши и визуальные ожидания.

• Автоматизация браузера в фоне — выделенный профиль Chrome и пул вкладок, принадлежащих расширению, которые могут переходить по ссылкам, просматривать, заполнять и кликать, не отвлекая внимание.

• История Codex — чтение сохранённых потоков Codex без их возобновления или запуска нового хода модели.

• Аутентифицированный транспорт MCP — stdio локально или включённый HTTP/OAuth-интерфейс за туннелем, который вы контролируете.

• Элементы управления жизненным циклом с отказом по умолчанию — явная разблокировка полного доступа, метаданные аудита, возврат процессов, владение меню-одиночкой и обновления приложений с учётом отката.

Рабочий процесс разработчика

Первый полезный рабочий процесс DarwinRelay не должен требовать автоматизации браузера, разрешений нативного интерфейса или истории Codex.

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

Как только основной цикл кодинга заработает, добавляйте возможности только тогда, когда они нужны задаче:

• используйте PTY для интерактивного отладчика, REPL, SSH-сессии или TUI;

• используйте фоновый Chrome для веб-рабочих процессов;

• предоставьте разрешения нативного рабочего стола, когда ChatGPT должен управлять реальным приложением macOS;

• используйте историю Codex, когда хотите, чтобы ChatGPT просматривал или продолжал более раннюю работу Codex.

См. examples/README.md для готовых рабочих процессов.

Помимо кодинга

DarwinRelay может объединять локальный код, процессы, состояние браузера и нативный интерфейс macOS в одном цикле выполнения. Например, задача отладки настольного приложения может выглядеть так:

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 не содержат готового .app или .dmg, и платное членство в Apple Developer Program не требуется для текущей модели продукта.

1. Требования

Основная самосборка:

• macOS 13 или новее;

• Node.js 18 или новее (в CI используется Node.js 22);

• Xcode Command Line Tools / swiftc для приложения меню и нативного помощника.

Для ChatGPT через путь HTTP/Server URL приложения меню также установите cloudflared и убедитесь, что он доступен в PATH вашей оболочки входа.

Дополнительные возможности:

• Разрешения Accessibility, Screen Recording и Input/Post Events — только для нативного управления рабочим столом;

• Полный доступ к диску — только когда задачам нужны защищённые 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 на месте: самособранное приложение намеренно разрешает свою среду выполнения из этого исходного пакета.

Сборка использует постоянную локальную подпись кода, когда она доступна, и в противном случае переходит к ad-hoc подписи. Сборки ad-hoc работают без платного членства в Apple Developer, но гранты TCC macOS могут потребовать повторного предоставления после пересборки, поскольку назначенное требование может измениться.

Для проверки компиляции/подписи без побочных эффектов установки используйте:

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, используя шаги установки выше; начиная с v0.6.5 используйте обновлятор для изменений между релизами.

Начиная с DarwinRelay v0.6.9, строка меню также предоставляет Update DarwinRelay…. Он запрашивает явное подтверждение, открывает тот же канонический обновлятор в отдельном окне Terminal и показывает прогресс во время перезапуска приложения. Нет тихого или автоматического пути обновления.

Вы можете запустить тот же обновлятор напрямую из обычного локального сеанса Terminal/iTerm (или другой независимой локальной оболочки), а не через соединение MCP DarwinRelay, которое собирается перезапуститься:

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

Это обновляет до последнего стабильного релиза vMAJOR.MINOR.PATCH. Чтобы выбрать точный опубликованный релиз:

./scripts/update.sh v0.6.5

Обновлятор рассматривает Git-каталог и /Applications/DarwinRelay.app как одну транзакцию. Он проверяет канонический источник GitHub, требует чистый каталог, привязанный к точному стабильному тегу релиза, проверяет целостность исходного кода, отклоняет перемещённые теги и понижения версий, атомарно устанавливает новое приложение с той же подписью, обновляет автозапуск, перезапускается с отказом по умолчанию и требует, чтобы настоящий MCP-доктор вернул CORE VERDICT: READY. Если активация не удаётся, он пытается восстановить как предыдущий каталог, так и сохранённое приложение для отката.

Он намеренно не использует git pull, git reset --hard и не удаляет локальную работу. Грязный/разработочный каталог отклоняется; храните изменения разработки в другой ветке/рабочем дереве, а не используйте производственную установку как каталог для кодинга.

Поскольку фоновое расширение Chrome загружается распакованным из этого каталога, релиз, изменяющий его манифест/исходный код, может потребовать одного ручного Reload со страницы расширений Chrome в выделенном профиле DarwinRelay. Обновлятор сообщает об этом, когда версия расширения меняется; никогда не подставляйте личный профиль.

Для сопровождающих проекта изменения обновлятора/жизненного цикла имеют дополнительный предрелизный шлюз: точный кандидат без тега проверяется на реальном 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

Доктор теперь даёт блокирующий вердикт Core / MCP coding path отдельно от дополнительных возможностей нативного рабочего стола, защищённой файловой системы, фонового Chrome и Codex. Он выполняет реальную локальную проверку initialize → bridge_status для выбранного транспорта и печатает следующее действие для блокирующих сбоев. Более глубокие диагностики жизненного цикла/браузера продолжают развиваться в дорожной карте.

Использование MCP только с исходным кодом

Для MCP-клиентов, которые могут подключаться к локальному stdio-серверу, мост также может работать напрямую без приложения меню. Полный доступ должен быть явно подтверждён:

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 и виртуальный курсор используют стабильные идентификаторы подписи кода, чтобы гранты TCC macOS могли пережить обычные пересборки, когда доступна постоянная подпись.

См. docs/ARCHITECTURE.md для компонентов, потока данных и границ доверия.

Для ИИ и агентов кодинга

Этот репозиторий намеренно включает документацию, ориентированную на агентов. Если вы дадите репозиторий 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;

• фоновый ввод, нацеленный на PID, где macOS это поддерживает, с семантической проверкой и ограниченным запасным вариантом переднего плана;

• ui_sequence для детерминированных многошаговых нативных серий;

• виртуальный курсор AI, который не перемещает физический указатель.

См. docs/DESKTOP_CONTROL.md для модели управления и ограничений.

Фоновое рабочее пространство Chrome

DarwinRelay использует распакованное расширение Chrome и Native Messaging. Публичный идентификатор расширения стабилен; ожидаемый идентификатор расширения:

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, включите режим разработчика, выберите Load unpacked и укажите каталог chrome-extension/ этого репозитория. Вы можете передать --open установщику для этого одноразового шага настройки.

Расширение владеет встроенной в Chrome группой вкладок с именем DR. Обычные вызовы chrome_open арендуют предварительно созданные неактивные вкладки вместо создания произвольных вкладок на переднем плане. chrome_close возвращает вкладки рабочего пространства в пул.

Модель безопасности браузера

Ослабленные разрешения используются по умолчанию. Обычная работа HTTP/HTTPS через настроенное рабочее пространство chrome_* не требует разрешения терминала для каждого сайта. Включение строгих разрешений в приложении меню восстанавливает ограниченные по URL разрешения и одноразовые разрешения на нативные изменения в рамках приложения.

Прямая автоматизация Chrome через shell/AppleScript/JXA остается заблокированной мостом, поэтому обычная веб-работа остается на управляемом фоновом пути. Отдельная нативная поверхность ui_* по-прежнему может взаимодействовать с пользовательским интерфейсом Chrome на переднем плане, когда это действительно требуется для безопасности браузера/ОС.

Необязательный адаптер raw Browser Harness/CDP существует за DARWINRELAY_ADVANCED_BROWSER=1. Он отключен по умолчанию и закрывается при строгих разрешениях, поскольку произвольный CDP нельзя корректно свести к областям URL.

HTTP / OAuth транспорт

mcp-http.mjs привязывается к loopback и поддерживает HTTP-транспорт MCP со статическим bearer-токеном, а также потоки OAuth 2.1, используемые удаленными MCP-клиентами. Туннель, такой как Cloudflare, может публиковать loopback-сервис через HTTPS.

Приложение меню является предпочтительной точкой входа для обычного пути URL сервера ChatGPT. DEPLOY.md описывает ручную/расширенную настройку транспорта, включая путь OpenAI Secure MCP Tunnel, сохраненный из вышестоящего проекта.

Не открывайте HTTP-конечную точку, не прочитав модель угроз удаленного доступа в SECURITY.md. Учетные данные, принятые этим интерфейсом, в конечном итоге открывают локальное выполнение кода от имени вашего пользователя рабочего стола.

Разработка

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

Публичный CI намеренно показывает отдельные проверки вместо одной непрозрачной задачи test:

• Статические проверки — проверка синтаксиса/нативной сборки и полное сканирование gitleaks по всей истории;

• Тесты ядра и протокола — MCP, HTTP/OAuth, PTY, федерация, браузер и состязательные тесты;

• Тесты управления рабочим столом — детерминированные тесты протокола рабочего стола плюс компиляция нативных фикстур;

• Тесты установки и жизненного цикла — установщики, автозапуск, владение одиночным экземпляром, откат и поведение при удалении.

Настоящий изменяемый AppKit E2E требует вошедшего в систему Mac с разрешениями TCC и поэтому не считается надежным на одноразовых GUI-сессиях, размещенных на GitHub. Сопровождающие могут запускать его локально с помощью:

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

См. CONTRIBUTING.md перед открытием pull request. Текущие приоритеты разработки отслеживаются в ROADMAP.md.

Безопасность

Важная граница проста: DarwinRelay имеет полномочия учетной записи macOS, под которой он работает. Такие функции безопасности, как файл разблокировки, строгие разрешения, метаданные аудита, OAuth, маршрутизация фонового браузера и перехват процессов, снижают случайное или удаленное злоупотребление; они не превращают произвольный доступ к оболочке в песочницу.

Отчеты о безопасности следует отправлять через приватную систему отчетов об уязвимостях GitHub, а не через публичный issue. См. SECURITY.md.

Происхождение проекта

DarwinRelay поддерживается независимо и существенно отличается от Mac Developer Bridge Александра Родаля Бенца. Унаследованная история вышестоящего проекта намеренно сохранена, а исходное уведомление об авторских правах MIT остается в LICENSE. См. UPSTREAM.md для точного происхождения и политики атрибуции.

Публичный репозиторий dcierra/darwinrelay является каноническим источником разработки. См. docs/DEVELOPMENT_MODEL.md для модели разработки/релизов.

DarwinRelay не аффилирован с OpenAI, Apple, Google, Cloudflare или вышестоящим сопровождающим и не одобрен ими.

Лицензия

MIT. См. LICENSE и UPSTREAM.md.