Интеграция с Kitty¶

Koda CLI добавляет в терминал Kitty чат о текущем окне терминала — только для чтения.

Ctrl + Shift + K открывает пустой чат об истории терминала;
Ctrl + Shift + / открывает чат с уже заданным вопросом о последней неудачной команде.

Быстрое исправление — не отдельный режим, а первый ход того же чата. Ответ поступает потоком: его можно отменить, повторить и продолжить уточняющими вопросами. Автоматическое открытие после ошибки по умолчанию выключено.

Интеграция работает через watcher Kitty, поэтому не зависит от конкретной оболочки: поддерживаются zsh, bash и fish при включённой shell-интеграции Kitty.

Требования¶

Kitty 0.48.0 или новее;
shell-интеграция Kitty с метками приглашения (prompt marks);
установленный и настроенный Koda CLI — см. установку;
локальная shell-сессия: команды внутри SSH-сессий не анализируются.

Установка¶

Установите или обновите Koda CLI, затем выполните:

koda integrations kitty install

Перед первой установкой CLI запрашивает согласие на передачу данных. Обновление с версии, которая поддерживала только быстрое исправление, запрашивает согласие повторно: чат может отправить до 64 КиБ истории терминала. Для неинтерактивной установки:

koda integrations kitty install --accept-data-sharing

Параметры чата можно задать сразу при установке:

koda integrations kitty install \
  --accept-data-sharing \
  --chat-model koda-base \
  --chat-reasoning high \
  --chat-max-tokens 2048 \
  --chat-timeout-seconds 30

По умолчанию используются модель koda-base, уровень размышлений high, 2048 токенов ответа и 30-секундный тайм-аут отсутствия входящих данных. Тайм-аут анализа первой команды по умолчанию тоже составляет 30 секунд:

koda integrations kitty install --timeout-seconds 45

Допустимый диапазон — от 1 до 600 секунд. Значение сохраняется в runtime.json и применяется к запросу обработчика и шкале прогресса. Повторная установка без нового значения сохраняет ранее настроенный тайм-аут.

Полный список опций — в справочнике аргументов.

Что устанавливается¶

Установщик:

копирует watcher в ~/.config/kitty/koda/koda_hints.py;
создаёт управляемый файл ~/.config/kitty/koda.conf;
создаёт ~/.config/kitty/koda/runtime.json с путями к обработчику и интерфейсу чата;
устанавливает пользовательский фоновый сервис koda-kitty-quick-fix;
добавляет сочетания клавиш Ctrl + Shift + / (быстрое исправление) и Ctrl + Shift + K (чат) — они не вводят текст в оболочку;
добавляет отмеченный блок include koda.conf в kitty.conf;
сохраняет резервную копию существующего kitty.conf перед изменением.

На Linux обработчик запускается как пользовательская служба systemd, на macOS — как LaunchAgent. Он обслуживает быстрое исправление и чат в течение пользовательской сессии и заранее инициализирует среду Koda, поэтому каждый запрос не запускает полный CLI заново.

Определение службы создаётся:

на Linux: ~/.config/systemd/user/koda-kitty-quick-fix.service;
на macOS: ~/Library/LaunchAgents/ru.kodacode.koda-cli.kitty-quick-fix.plist.

Установка идемпотентна: повторный запуск обновляет watcher, среду выполнения и определение службы, сохраняя настройку автоматических подсказок.

Проверка установки¶

Откройте новое окно Kitty после установки и выполните:

koda integrations kitty status
koda integrations kitty service status

Корректная установка показывает, что подсказки установлены, сервис готов, а автоматические подсказки выключены.

Для первой проверки выполните заведомо ошибочную команду, например git statsu, затем нажмите Ctrl + Shift + /. Откроется панель чата, и Koda автоматически проанализирует ошибку: первым сообщением появятся диагноз и предлагаемое исправление. Ctrl + P вставит предложенную команду в исходный терминал без выполнения, Ctrl + Y скопирует её в буфер обмена.

Чат с историей терминала¶

Нажмите Ctrl + Shift + K: Kitty локально получает текстовое содержимое экрана и прокрутки активного окна, скрывает распространённые учётные данные и оставляет последние 64 КиБ. Снимок создаётся один раз до открытия панели; новые строки в исходном окне не попадают в уже открытый чат.

Открывается нижняя панель размером 50 % текущей вкладки — без новой вкладки или окна ОС. Запрос к модели начинается только после ввода вопроса и Enter. В панели доступны:

Сочетание	Действие
`Enter`	отправить вопрос
`↑` / `↓`	прокрутить диалог на одну строку
`PageUp` / `PageDown`	прокрутить диалог на одну страницу
`Ctrl` + `Y`	скопировать последнюю предложенную команду из ответа в буфер обмена Kitty
`Ctrl` + `P`	вставить последнюю предложенную команду в исходное окно терминала
`Ctrl` + `O`	переключить модель
`Ctrl` + `R`	переключить уровень размышлений
`Ctrl` + `B`	скрыть или показать рамку панели
`Ctrl` + `C`	отменить текущий ответ
`Esc`	закрыть панель

Ответ поступает потоком. Панель явно показывает подключение, ожидание, потоковую передачу, завершение, отмену, тайм-аут и ошибку, а также прошедшее время. История чата существует только в процессе панели и удаляется при закрытии. Koda не запускает инструменты, не читает файлы проекта и не исполняет команды; чат не загружает память проекта, навыки, расширения и MCP-серверы. Текст терминала передаётся модели как недоверенные данные, а не как инструкции.

Под диалогом Koda показывает панель «Предлагаемое исправление»: команду в отдельной рамке, а под ней действия — Ctrl + P (вставить в исходный терминал) и Ctrl + Y (скопировать). После успешной вставки фокус возвращается в исходное окно Kitty, где команда уже набрана, но не выполнена: остаётся проверить её и нажать Enter. Koda никогда не выполняет исправление автоматически.

Командой считается последний блок кода в ответе; если блоков нет — последняя команда в обратных кавычках. Если команда не проходит проверки безопасности (sudo, rm, git reset, конвейер в оболочку и подобные), панель помечается как «проверьте перед запуском», но действие остаётся доступным: вставка не исполняет команду.

Вместо сочетания клавиш можно выполнить в локальной shell-сессии:

koda integrations kitty chat

Сочетание работает и для вывода удалённой shell-сессии: чат остаётся только для чтения. Ограничение быстрого исправления для SSH при этом не меняется.

Для компактной нижней панели должна быть доступна раскладка splits; установщик не изменяет пользовательский список раскладок.

Подсказка после неудачной команды¶

После ненулевого кода завершения watcher локально сохраняет команду, рабочий каталог и ограниченный вывод последней команды. Запрос к модели не выполняется, пока вы не нажмёте Ctrl + Shift + / или не включите автоматический режим. Сохранённая ошибка уходит в модель структурированным блоком вместе со снимком истории и только в первом вопросе; последующие вопросы — обычный чат.

Перед запросом к модели:

домашний каталог заменяется на ~;
распространённые API-ключи, токены, пароли и учётные данные в URL скрываются;
вывод ограничивается 24 КиБ: первые 8 КиБ и последние 16 КиБ.

Анализ выполняется асинхронно и не блокирует оболочку. Новый запуск в том же окне отменяет устаревший анализ.

В качестве альтернативы сочетанию клавиш можно выполнить в том же окне Kitty:

koda integrations kitty suggest

Если предыдущей ошибки в окне не было, панель сообщит об этом первым сообщением. Дальше можно продолжить диалог в той же панели.

Автоматический режим¶

Автоматические подсказки можно включить:

koda integrations kitty auto enable

И снова выключить:

koda integrations kitty auto disable

Изменение применяется к уже открытым окнам Kitty. В автоматическом режиме ожидаемые проверки вроде test, command -v, grep -q, diff и cmp отбрасываются локально, а одинаковые ошибки не анализируются повторно в течение 60 секунд. Панель чата открывается сразу после ошибки, но не забирает фокус у оболочки.

Фоновый сервис¶

Проверить состояние обработчика и управлять им можно командами:

koda integrations kitty service status
koda integrations kitty service start
koda integrations kitty service stop
koda integrations kitty service restart

Команда koda integrations kitty status также показывает состояние сервиса, идентификатор процесса и параметры чата. При повторной установке интеграции определение службы обновляется вместе с пакетом.

Изменение параметров чата¶

Параметры можно изменить без переустановки и перезапуска обработчика:

koda integrations kitty configure \
  --chat-model koda-base \
  --chat-reasoning high \
  --chat-max-tokens 2048 \
  --chat-timeout-seconds 30

Допустимые значения уровня размышлений: none, high; бюджет токенов ответа — 128–8192; тайм-аут отсутствия данных — 1–600 секунд.

Удаление¶

koda integrations kitty uninstall

Команда останавливает и удаляет пользовательский фоновый сервис, затем удаляет только управляемые Koda файлы и отмеченный блок из kitty.conf. Перед изменением kitty.conf создаётся резервная копия. Другие файлы в каталоге koda сохраняются.

Установка через сессию CLI¶

Когда Koda CLI запущен внутри Kitty, доступна слеш-команда /kitty-integration: без аргументов она диагностирует интеграцию, устанавливает её при отсутствии и проверяет итоговое состояние; с аргументом передаёт ваш запрос встроенному навыку kitty-integration.

Устранение проблем¶

Если status сообщает, что метки приглашения отключены, удалите disabled или no-prompt-mark из настройки shell_integration в kitty.conf, перезапустите Kitty и повторите установку.

Если status сообщает, что фоновый сервис остановлен, выполните:

koda integrations kitty service restart

Команда не сохраняется для быстрой подсказки при:

успешных командах;
завершениях с кодами 130 и 143;
работе через SSH или удалённую оболочку.

Автоматические подсказки дополнительно не запускаются для ожидаемых команд-проверок. Результат не показывается для ошибок без простого безопасного исправления, а также при недостаточной уверенности ответа модели или после тайм-аута.