Быстрый старт: за 5 минут освоить opencode-notify

Что вы сможете делать после этого урока

• Установить плагин opencode-notify за 3 минуты
• Триггернуть первое уведомление на рабочем столе и подтвердить успешную установку
• Понять различия между разными способами установки и их применимость

Ваша текущая ситуация

Вы поручили AI выполнить задачу и переключились на другие окна. Теперь каждые 30 секунд вы переключаетесь обратно, чтобы проверить: готово ли? Ошибка? Или ждёт разрешения? opencode-notify создан именно для решения этой проблемы.

Это постоянное переключение прерывает ваше мышление и тратит время.

Когда использовать этот подход

Включите opencode-notify в следующих сценариях:

• Вы часто переключаетесь на другие приложения, пока AI выполняет задачу
• Вы хотите быть немедленно уведомлены, когда AI нуждается в вас
• Вы хотите сохранять концентрацию, не упуская важные события

Основная идея

Принцип работы opencode-notify прост: слушать события OpenCode и отправлять нативные уведомления на рабочий стол в ключевые моменты.

Он уведомит вас о:

• ✅ Завершении задачи (Session idle)
• ✅ Ошибке выполнения (Session error)
• ✅ Необходимости разрешения (Permission updated)

Он не будет уведомлять вас о:

• ❌ Завершении каждой подзадачи (слишком шумно)
• ❌ Любых событиях при фокусе терминала (вы смотрите на терминал, уведомление не нужно)

🎒 Подготовка перед началом

Требования

• Установлен OpenCode
• Доступный терминал (macOS Terminal, iTerm2, Windows Terminal и т.д.)
• Система macOS/Windows/Linux (все три поддерживаются)

Следуйте за мной

Шаг 1: Выберите способ установки

opencode-notify предлагает два способа установки:

Способ	Применимость	Преимущества	Недостатки
Пакетный менеджер OCX	Большинство пользователей	Установка в один клик, автоматические обновления, полное управление зависимостями	Требуется предварительная установка OCX
Ручная установка	Особые требования	Полный контроль, не требует OCX	Необходимо вручную управлять зависимостями и обновлениями

Рекомендация: Используйте OCX для установки — проще и удобнее.

Шаг 2: Установка через OCX (рекомендуется)

2.1 Установка пакетного менеджера OCX

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

Установка OCX:

curl -fsSL https://ocx.kdco.dev/install.sh | sh

Вы должны увидеть: Скрипт установки отображает прогресс и в конце сообщает об успешной установке.

2.2 Добавление KDCO Registry

KDCO Registry — репозиторий плагинов, содержащий opencode-notify и множество других полезных плагинов.

Добавление registry:

ocx registry add https://registry.kdco.dev --name kdco

Вы должны увидеть: Сообщение "Registry added successfully" или аналогичное.

Опционально: глобальная конфигурация

Если вы хотите использовать один и тот же registry во всех проектах, добавьте параметр --global:

ocx registry add https://registry.kdco.dev --name kdco --global

2.3 Установка opencode-notify

Установка плагина:

ocx add kdco/notify

Вы должны увидеть:

✓ Added kdco/notify to your OpenCode workspace

Шаг 3: Установка всего рабочего пространства одной командой (опционально)

Если вы хотите получить полный опыт, вы можете установить рабочее пространство KDCO, которое включает:

• opencode-notify (уведомления на рабочем столе)
• Фоновые агенты (Background Agents)
• Специализированные агенты (Specialist Agents)
• Инструменты планирования (Planning Tools)

Установка рабочего пространства:

ocx add kdco/workspace

Вы должны увидеть: Сообщение о том, что несколько компонентов были успешно добавлены.

Шаг 4: Проверка установки

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

Метод проверки 1: Дать AI задачу на выполнение

В OpenCode введите:

Пожалуйста, вычислите сумму чисел от 1 до 10, а затем подождите 5 секунд и сообщите результат.

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

Метод проверки 2: Проверка конфигурационного файла

Проверьте, существует ли файл конфигурации:

# macOS/Linux
cat ~/.config/opencode/kdco-notify.json

# Windows PowerShell
type $env:USERPROFILE\.config\opencode\kdco-notify.json

Вы должны увидеть:

• Если файл не существует → используются настройки по умолчанию (нормально)
• Если файл существует → отображается ваша пользовательская конфигурация

Шаг 5: Ручная установка (альтернативный вариант)

Если вы не хотите использовать OCX, вы можете установить вручную.

5.1 Копирование исходного кода

Скопируйте исходный код opencode-notify в каталог плагинов OpenCode:

# Копирование из исходников в отдельный каталог
mkdir -p ~/.opencode/plugin/kdco-notify
cp src/notify.ts ~/.opencode/plugin/kdco-notify/
cp -r src/plugin/kdco-primitives ~/.opencode/plugin/kdco-notify/

5.2 Установка зависимостей

Установите необходимые зависимости вручную:

cd ~/.opencode/plugin/
npm install node-notifier detect-terminal @opencode-ai/plugin @opencode-ai/sdk

Важные замечания

• Управление зависимостями: необходимо вручную устанавливать и обновлять node-notifier и detect-terminal
• Сложность обновления: каждое обновление требует ручного копирования исходного кода
• Не рекомендуется: если нет особых требований, рекомендуется использовать установку через OCX

Контрольная точка ✅

После завершения описанных выше шагов, пожалуйста, подтвердите:

• [ ] OCX успешно установлен (ocx --version выводит номер версии)
• [ ] KDCO Registry добавлен (ocx registry list отображает kdco)
• [ ] opencode-notify установлен (ocx list отображает kdco/notify)
• [ ] Получено первое уведомление на рабочем столе
• [ ] Уведомление отображает правильный заголовок задачи

Если какой-либо шаг не удался:

• Посмотрите раздел Устранение неполадок для получения помощи
• Проверьте, работает ли OpenCode нормально
• Убедитесь, что ваша система поддерживает уведомления на рабочем столе

Возможные проблемы

Проблема 1: Уведомления не отображаются

Причина:

• macOS: системные уведомления отключены
• Windows: разрешение на уведомления не предоставлено
• Linux: notify-send не установлен

Решение:

Платформа	Решение
macOS	Системные настройки → Уведомления → OpenCode → Разрешить уведомления
Windows	Параметры → Система → Уведомления → Включить уведомления
Linux	Установить libnotify-bin: sudo apt install libnotify-bin

Проблема 2: Ошибка установки OCX

Причина: Проблемы с сетью или недостаточно прав

Решение:

1. Проверьте сетевое подключение
2. Используйте sudo для установки (требуются права администратора)
3. Загрузите скрипт установки вручную и выполните его

Проблема 3: Ошибка установки зависимостей

Причина: Несовместимая версия Node.js

Решение:

• Используйте Node.js версии 18 или выше
• Очистите кэш npm: npm cache clean --force

Резюме урока

В этом уроке мы выполнили:

• ✅ Установку пакетного менеджера OCX
• ✅ Добавление KDCO Registry
• ✅ Установку плагина opencode-notify
• ✅ Получение первого уведомления на рабочем столе
• ✅ Изучение метода ручной установки

Ключевые моменты:

1. opencode-notify использует нативные уведомления на рабочем столе, нет необходимости часто переключать окна
2. OCX — рекомендуемый способ установки, автоматически управляет зависимостями и обновлениями
3. По умолчанию уведомляются только родительские сессии, избегая шума от подзадач
4. Уведомления автоматически подавляются, когда терминал в фокусе

Следующий урок

В следующем уроке мы изучим Как это работает.

Вы узнаете:

• Как плагин прослушивает события OpenCode
• Рабочий процесс механизма интеллектуальной фильтрации
• Принцип обнаружения терминала и фокусировки
• Различия в функциональности на разных платформах

---

Приложение: Справочник по исходному коду

Нажмите, чтобы развернуть и посмотреть расположение исходного кода

Обновлено: 2026-01-27

Функция	Путь к файлу	Строки
Главный вход плагина	src/notify.ts	1-407
Загрузка конфигурации	src/notify.ts	90-114
Отправка уведомлений	src/notify.ts	280-308
Обнаружение терминала	src/notify.ts	145-176
Проверка тихих часов	src/notify.ts	181-199
Конфигурация по умолчанию	src/notify.ts	30-48

Ключевые константы:

• DEFAULT_CONFIG.sounds.idle = "Glass": звук по умолчанию при завершении задачи
• DEFAULT_CONFIG.sounds.error = "Basso": звук по умолчанию при ошибке
• DEFAULT_CONFIG.sounds.permission = "Submarine": звук по умолчанию при запросе разрешения
• DEFAULT_CONFIG.notifyChildSessions = false: по умолчанию уведомляются только родительские сессии

Ключевые функции:

• NotifyPlugin(): входная функция плагина, возвращает обработчик событий
• loadConfig(): загружает файл конфигурации, объединяет с значениями по умолчанию
• sendNotification(): отправляет нативное уведомление на рабочий стол
• detectTerminalInfo(): обнаруживает тип терминала и Bundle ID
• isQuietHours(): проверяет, находится ли текущее время в тихих часах
• isParentSession(): определяет, является ли сессия родительской
• isTerminalFocused(): обнаруживает, находится ли терминал на переднем плане