Local Kiklet — menubar-приложение для macOS:

• записывает голос;
• делает локальную транскрибацию (Whisper на вашем Mac);
• вставляет текст в активное поле ввода (или копирует в буфер как fallback);
• опционально применяет текстовые действия через OpenAI API.

Этот README описывает полный путь: «увидел репозиторий -> скачал DMG -> установил -> выдал разрешения -> начал пользоваться».

1. Перейдите в раздел Releases этого репозитория.
2. Скачайте файл LocalKiklet.dmg из последнего релиза.

Если релизов пока нет, используйте раздел «Сборка из исходников» ниже.

1. Откройте LocalKiklet.dmg.
2. Перетащите LocalKiklet.app в Applications.
3. Закройте окно DMG и извлеките диск.

Важно: запускайте приложение именно из /Applications/LocalKiklet.app.

1. Откройте Applications и запустите LocalKiklet.
2. Пройдите онбординг разрешений.

Приложение запросит:

• Microphone — для записи речи;
• Accessibility — для вставки текста в другие приложения;
• Input Monitoring — для глобальных горячих клавиш (особенно modifier-only, например только ⌥).

В онбординге и настройках есть кнопки:

• Запросить;
• Открыть настройки;
• Проверить разрешения.

Также при запуске утилиты macOS может показать окно Keychain с запросом пароля login для доступа к записи LocalKiklet. В этом окне нажмите Always Allow (Разрешить всегда) — это нужно для хранения и использования API-ключа OpenAI.

Если Input Monitoring не выдался автоматически, добавьте приложение вручную:

1. Откройте System Settings -> Privacy & Security -> Input Monitoring.
2. Нажмите + внизу слева.
3. В списке приложений найдите и выберите LocalKiklet (из папки Applications).
4. Включите переключатель рядом с LocalKiklet.
5. Вернитесь в приложение и нажмите Проверить разрешения.

Откройте Settings и проверьте:

1. Горячие клавиши
   • Hold-to-record (нажал и держишь — идет запись);
   • Toggle record (нажал — старт, нажал снова — стоп).
2. Распознавание
   • язык: для стабильной русской диктовки лучше выбрать Русский;
   • Auto тоже поддерживается, но на смешанной речи может ошибаться;
   • качество: Быстрее или Точнее.
3. Вставка/буфер
   • Умный режим (по умолчанию);
   • Всегда вставлять;
   • Всегда в буфер.
4. OpenAI (опционально)
   • вставьте API-ключ;
   • нажмите Проверить ключ.

Важно: API-ключ OpenAI нужен только для действий над текстом. Без API-ключа приложение всё равно стабильно работает в локальном режиме (запись + транскрибация через локальный Whisper + вставка/буфер).

1. Зажмите горячую клавишу Hold-to-record.
2. Продиктуйте текст.
3. Отпустите клавишу.
4. Приложение:
   • распознает речь локально;
   • применит выбранное действие (если нужно);
   • вставит текст в активный инпут или скопирует в буфер.

1. Нажмите Toggle record один раз — старт.
2. Нажмите второй раз — стоп и обработка.

• индикатор состояния в menubar;
• HUD-статус около курсора (Идет запись, Транскрибирую..., и т.д.);
• уведомление о результате (Вставлено в ... / Скопировано в буфер).

Важно: для OpenAI-действий используется Keychain. Если macOS спросит пароль связки ключей, выберите Always Allow (Разрешить всегда), иначе приложение не сможет стабильно читать сохранённый API-ключ.

Действия нужны, чтобы делать с текстом «нестандартные» операции: например, перевод, переформулирование, изменение стиля, сжатие, извлечение задач и любые другие кастомные сценарии. Практически это ограничено только фантазией пользователя и качеством инструкции действия.

Текущая модель для OpenAI-действий в этом проекте: gpt-4o-mini.

Где посмотреть информацию и цены:

• Документация по модели (gpt-4o / gpt-4o-mini): OpenAI Models Docs
• Актуальный прайсинг: OpenAI API Pricing
• За последние 3 месяца очень активного использования этой модели в Kiklet я потратил менее $2

Встроенные действия включают:

• Без обработки (только транскрипция)
• Перевести на английский
• Перевести на русский
• Сделать формально-деловым стилем
• Сделать проще/дружелюбнее
• Сжать в 1–2 предложения
• Список задач (to-do)
• Краткое резюме

Можно добавлять собственные действия в Настройки -> Действия.

В History сохраняются последние результаты:

• исходная транскрипция;
• результат действия;
• время;
• имя действия.

Для записи доступны операции:

• скопировать транскрипцию;
• скопировать результат;
• повторить действие;
• удалить запись.

1. Удалите старую копию из /Applications.
2. Установите заново из свежего LocalKiklet.dmg.
3. Снимите quarantine (при необходимости):

xattr -dr com.apple.quarantine /Applications/LocalKiklet.app
open /Applications/LocalKiklet.app

1. Проверьте, что выдан Input Monitoring.
2. Проверьте Accessibility.
3. В приложении нажмите Проверить разрешения.
4. Если используете modifier-only хоткей (например, только ⌥), Input Monitoring обязателен.
5. Если Input Monitoring не добавляется автоматически, добавьте LocalKiklet вручную через кнопку + в System Settings -> Privacy & Security -> Input Monitoring.

1. Проверьте Accessibility.
2. Попробуйте режим Всегда вставлять.
3. Убедитесь, что курсор стоит в реальном editable-поле.

1. В Настройки -> Распознавание выставьте язык явно (Русский или English), а не Auto.
2. Для смешанной речи это дает более стабильный результат.

1. Проверьте путь к whisper-cli.
2. Проверьте наличие моделей (fast/accurate).
3. Нажмите Установить локальный Whisper.
4. Проверьте микрофон и уровень входного сигнала.

• Лог-файл: ~/Library/Application Support/LocalKiklet/logs/localkiklet.log
• В настройках есть кнопка Экспорт логов.

• macOS 13+
• Xcode Command Line Tools
• Swift 6+

swift build
swift run LocalKiklet

./scripts/build_app.sh

Результат: dist/LocalKiklet.app

./scripts/build_dmg.sh

Результат: dist/LocalKiklet.dmg

• Вставка в некоторые защищенные поля macOS может быть недоступна — тогда используется fallback в буфер.
• Для OpenAI-действий нужен API-ключ и интернет.
• Для production-дистрибуции рекомендуется Developer ID signing + notarization.

Проект распространяется под лицензией MIT. Полный текст: LICENSE.