Работа в GitHub Codespaces¶

GitHub Codespaces — это облачные среды разработки. Окружение разворачивается на серверах GitHub, а вы подключаетесь к нему из VS Code или из IDE на платформе IntelliJ.

Окружение Codespaces настраивается тем же файлом devcontainer.json, что и Dev Containers, поэтому на стороне Koda поведение во многом совпадает.

Главное правило: Koda работает там же, где находится проект, — то есть в облачном окружении Codespaces. Команды, чтение и запись файлов, поиск, индексация и настройки выполняются на стороне окружения.

Как это устроено¶

VS Code IntelliJ

VS Code подключается к окружению Codespaces как к удалённой стороне. Koda работает там же:

чтение и запись файлов происходят в окружении;
инструменты агента — чтение, редактирование, поиск и запуск команд — видят файлы внутри окружения;
терминал открывается внутри окружения;
индекс кодовой базы и настройки хранятся в окружении.

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

К окружению Codespaces можно подключиться через Remote Development: бэкенд IDE запускается внутри облачного окружения, а на вашем компьютере работает только клиент JetBrains.

Подключиться к Codespaces можно из JetBrains Toolbox App, окна приветствия IntelliJ IDEA или JetBrains Gateway, выбрав GitHub Codespaces как провайдера облачной среды разработки.

Koda устанавливается в бэкенд и работает внутри окружения:

файлы читаются и записываются в окружении;
команды выполняются оболочкой окружения;
индекс кодовой базы и настройки хранятся в окружении.

Простая проверка

Попросите агента выполнить в терминале команду pwd. Если путь начинается с /workspaces/..., значит Koda работает внутри облачного окружения.

Что это значит на практике

Файлы вашего компьютера при работе в Codespaces Koda не затрагивает. Всё, что она делает с проектом, происходит внутри облачного окружения.

Что нужно сделать¶

Открыть проект в Codespaces — см. раздел Открытие проекта.
Установить Koda в окружение, а не только на свой компьютер — см. раздел Установка Koda.
Войти в аккаунт — так же, как при обычной работе.
Убедиться, что изнутри окружения доступен api.kodacode.ru — см. раздел Сеть.
При необходимости сохранить настройки и индекс между пересозданиями окружения — см. раздел Настройки.

Открытие проекта¶

VS Code IntelliJ

Сначала убедитесь, что выполнены предварительные условия:

Есть аккаунт GitHub с доступом к Codespaces.
Установлено расширение GitHub Codespaces (GitHub.codespaces).

Чтобы открыть проект в Codespaces:

Нажмите F1 и выберите Codespaces: Create New Codespace — или Codespaces: Connect to Codespace, если окружение уже создано.
Выберите репозиторий, ветку и размер машины.
Дождитесь сборки окружения — VS Code подключится к нему автоматически.

Также окружение можно создать на сайте GitHub: откройте репозиторий и выберите Code → Codespaces → Create codespace on main, а затем подключитесь к нему из VS Code.

В левом нижнем углу окна появится индикатор Codespaces, подтверждающий подключение.

Подключение к Codespaces идёт через Remote Development как к облачной среде разработки:

В окне приветствия IntelliJ IDEA выберите Remote Development. То же доступно из JetBrains Toolbox App и JetBrains Gateway.
Если провайдер ещё не установлен, откройте список провайдеров и установите нужный.
Выберите GitHub Codespaces как провайдера и нажмите подключение.
Авторизуйтесь в GitHub и выберите окружение или создайте новое.
Дождитесь запуска бэкенда IDE внутри окружения.
Откройте проект из файловой системы окружения.

Плагин Koda устанавливается уже в запущенный бэкенд — см. раздел Установка Koda.

Установка Koda¶

VS Code IntelliJ

Откройте проект в Codespaces — как описано в разделе Открытие проекта.
Откройте раздел Расширения.
Найдите Koda.koda и нажмите Установить в Codespaces.
Дождитесь установки и при необходимости перезагрузите окно.

Чтобы расширение ставилось само при каждом создании окружения, добавьте его в devcontainer.json — см. раздел Автоматическая настройка.

Установите плагин Koda в бэкенд IDE, работающий внутри окружения Codespaces. Плагин ставится из JetBrains Marketplace так же, как любой другой.

Общая инструкция по установке — на странице Установка плагина.

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

Окружение Codespaces описывается тем же файлом devcontainer.json, что и Dev Containers. Через него можно заранее описать всё нужное для работы Koda, чтобы при каждом создании окружения это настраивалось само.

Установить расширение Koda в окружение:

.devcontainer/devcontainer.json

{
  "customizations": {
    "vscode": {
      "extensions": ["Koda.koda"]
    }
  }
}

Установить плагин Koda в бэкенд JetBrains:

.devcontainer/devcontainer.json

{
  "customizations": {
    "jetbrains": {
      "plugins": ["Koda"]
    }
  }
}

Установить ripgrep для быстрого поиска по содержимому:

.devcontainer/devcontainer.json

{
  "postCreateCommand": "sudo apt-get update && sudo apt-get install -y ripgrep"
}

Сохранить настройки и индекс Koda между пересозданиями окружения — вынести каталог ~/.koda в отдельный том:

.devcontainer/devcontainer.json

{
  "mounts": [
    { "source": "koda-home", "target": "/home/vscode/.koda", "type": "volume" }
  ]
}

Путь зависит от пользователя окружения

В примере выше используется путь /home/vscode/.koda — для стандартного пользователя vscode. Если окружение работает под другим пользователем, укажите соответствующий домашний каталог (например, /root/.koda для root).

Свойства можно объединить

Все перечисленные свойства можно указать в одном файле devcontainer.json.

Файлы, пути и терминал¶

Koda работает с файлами проекта напрямую, поэтому пути указываются так, как они выглядят в окружении.

Относительные пути (например, src/index.ts) ищутся в корне проекта.
Абсолютные пути внутри окружения (например, /workspaces/my-app) разрешаются в файловой системе окружения.

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

Команды работают в том же окружении, что и проект, поэтому доступны все установленные в нём утилиты.
Терминал Koda переиспользуется: если команда активировала виртуальное окружение или изменила переменные, это сохраняется между вызовами.
Команды можно останавливать — Koda прерывает их и при необходимости закрывает терминал.
Слишком большой вывод команды сокращается до 2000 строк или 50 КиБ, а полный текст сохраняется в файл — см. «Большой вывод инструментов».

Файлы вне проекта

Инструменты работают в первую очередь с файлами открытого проекта. Если путь ведёт за пределы проекта, Koda может его не найти.

Поиск по коду¶

VS Code IntelliJ

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

ripgrep (rg) — быстрый поиск, как в локальном окружении;
обычный grep — запасной вариант, если ripgrep не установлен.

Ограничения запасного варианта

У grep нет части возможностей ripgrep: часть шаблонов поиска переводится в упрощённый вид, а очень длинные строки обрезаются. Для надёжного поиска по содержимому установите ripgrep внутри окружения — например, через postCreateCommand (см. раздел Автоматическая настройка).

Если ни ripgrep, ни grep не найдены, поиск по содержимому в проекте недоступен.

Поиск по содержимому работает обычным для JetBrains способом — через упакованный или системный ripgrep. Отдельно устанавливать ripgrep в окружение не нужно.

Поиск файлов по имени учитывает правила .gitignore и .kodaignore.

Индексация¶

Данные индексации хранятся на стороне окружения, в каталоге ~/.koda/index внутри окружения.

Впервые открыв проект в Codespaces, Koda построит индекс заново.
Если окружение пересоздаётся, каталог ~/.koda может быть потерян вместе с индексом — тогда проект нужно проиндексировать повторно.
Чтобы сохранить индекс между пересозданиями, вынесите ~/.koda в отдельный том — см. раздел Автоматическая настройка.

Индексация включается на вкладке Индексация в настройках — см. Настройки индексации. Подробнее о решении проблем с индексацией — на странице Индексация.

Настройки¶

В окружении Codespaces Koda читает настройки со стороны окружения — как если бы она была запущена в этой системе.

Глобальный файл config.yaml лежит в ~/.koda/config.yaml внутри окружения, а не в ~/.koda вашей системы.
Проектный файл .kodarc.json — в корне проекта внутри окружения.
Правила из файла .kodarules и игноры из .kodaignore — также в корне проекта в окружении.
Локальные навыки из .koda/skills, .claude/skills и .agents/skills ищутся относительно корня проекта в окружении.

Настройки у каждой стороны свои

У вашего компьютера и у окружения разные домашние каталоги, поэтому ~/.koda/config.yaml у них не общий. Настройки, сделанные на вашем компьютере, не переносятся в окружение автоматически. Если настройки нужны и там, скопируйте файл конфигурации в ~/.koda окружения или вынесите каталог в том.

Сеть¶

Запросы к моделям Koda выполняет та же сторона, где работает Koda, — то есть окружение Codespaces.

Изнутри окружения должен быть доступен api.kodacode.ru.
Учитывайте ограничения сети окружения: при закрытой сети запросы к моделям не пройдут.
Если вы используете прокси или VPN, настройте их доступность и внутри окружения.

Типичные проблемы¶

Koda не видит файлы проекта¶

Убедитесь, что Koda установлена в окружение, а проект открыт в Codespaces. Проверьте, что папка проекта действительно открыта как рабочая область.

Команды выполняются не там, где ожидается¶

Команды всегда выполняются на стороне окружения. Если вы ожидали команды на своём компьютере, откройте проект локально.

Поиск по содержимому ничего не находит¶

Проверьте, установлен ли ripgrep или grep внутри окружения. Также убедитесь, что искомый текст не исключён правилами .gitignore или .kodaignore.

После пересоздания окружения пропали настройки или индекс¶

Каталог ~/.koda внутри окружения не сохраняется между пересозданиями. Вынесите его в отдельный том через mounts в devcontainer.json — см. раздел Автоматическая настройка.

Koda не отвечает¶

Проверьте, что изнутри окружения есть доступ к api.kodacode.ru — см. раздел Сеть. Если вы используете прокси или VPN, они тоже должны быть доступны внутри окружения.