ZubrCode — кодинг-агент

ZubrCode (zubrcode) — кодинг-агент для терминала: правит код в вашем репозитории, запускает команды и тесты, объясняет чужой код. Модели — на платформе ZubrIQ: по умолчанию Zubr Pro (zubr-coder) — он работает у внешнего провайдера. Если код не должен покидать РБ, выберите zubr (Zubr Local) — он на наших GPU в Минске. Телеметрия наружу не уходит. Основа — opencode.

Раньше этим агентом был zq (ZubrIQ Code). ZubrCode ставится рядом, ключ и MCP-серверы из zq подхватывает сам — см. Переход с zq.

Установка

Одна команда. Ставится один файл zubrcode — Node, npm и права администратора не нужны.

# Linux, macOS, WSL
curl -fsSL https://zubriq.by/install.sh | sh

# Windows (PowerShell)
irm https://zubriq.by/install.ps1 | iex

Скрипт сам выбирает сборку под систему и процессор (в том числе для виртуальных машин без AVX2), сверяет архив с контрольной суммой и кладёт zubrcode в ~/.local/bin (на Windows — zubrcode.exe в %LOCALAPPDATA%\Programs\zubrcode\bin, эту папку скрипт сам добавит в PATH). Проверьте:

zubrcode --version

Если команда не найдена — добавьте ~/.local/bin в PATH (скрипт подскажет строку для ~/.profile) и откройте новый терминал. В cmd.exe вместо PowerShell: powershell -c "irm https://zubriq.by/install.ps1 | iex".

Вход

zubrcode auth login -p zubriq

Выберите «Войти через zubriq.by»: команда покажет ссылку на страницу подтверждения zubriq.by — та же учётка, что в чате. Открыть её можно на любом устройстве, в том числе с телефона, если вы работаете на сервере по SSH. После подтверждения ключ выпустится и сохранится сам.

Второй способ — готовый ключ из кабинета:

export ZUBRIQ_API_KEY=sk-zq-…   # ключ: zubriq.by/chat → Настройки → API-ключи
zubrcode

Ключ действует на те же модели, что и API платформы: по умолчанию агент работает на Zubr Pro — zubr-coder, у внешнего провайдера, — сменить можно командой /models, например на zubr (Zubr Local), чтобы код не покидал РБ. Список моделей приходит с платформы — там только те, что умеют работать агентом. Расход списывается с кошелька организации, как и любой запрос по ключу.

Обновление

zubrcode upgrade

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

Правила проекта: AGENTS.md

Инструкции для агента — стек, соглашения, что нельзя трогать — лежат в файле правил в корне проекта. ZubrCode читает AGENTS.md, CLAUDE.md и QWEN.md: проект, размеченный для другого агента или для zq, работает сразу. Глобальные правила — ~/.config/zubrcode/AGENTS.md.

/init создаёт AGENTS.md по содержимому репозитория.

Как работать

Запускайте zubrcode в каталоге проекта — агент работает с ним как с рабочей папкой.
Пишите задачу словами: «почини падающий тест», «добавь эндпоинт», «объясни, что делает этот модуль». Правки файлов агент показывает диффом, команды оболочки — спрашивает перед запуском.
Tab — переключить агента (build — правит код, plan — только планирует), Ctrl+P — все команды, Esc — прервать ход.
Без окна, одной командой: zubrcode run "почини падающий тест". Спросить разрешение здесь не у кого, поэтому команды оболочки в этом режиме отклоняются — правки файлов проходят. Для скриптов и CI разрешите команды заранее в opencode.json (см. «Разрешения»).

Команды в сессии

Команда	Что делает
`/init`	Создаёт `AGENTS.md` по содержимому репозитория
`/models`	Сменить модель (по умолчанию `zubr-coder`)
`/agents`	Переключить агента
`/new`, `/sessions`	Новая сессия, вернуться к прошлой
`/undo`, `/redo`	Откатить ход вместе с правками и вернуть
`/diff`	Показать текущие правки
`/compact`	Сжать длинную переписку, чтобы не упираться в контекст
`/mcps`	Включить и выключить MCP-серверы
`/export`	Выгрузить переписку в файл
`/help`	Все команды

Разрешения

Перед командами оболочки агент спрашивает: в терминале — Allow once, Allow always (для похожих команд до перезапуска), Reject; в чате и ZubrCode Desktop — «Разрешить», «Разрешать всегда», «Запретить». Правки файлов — без вопросов, их видно диффом и можно откатить /undo. Настроить по-своему — в opencode.json проекта или ~/.config/zubrcode/opencode.json:

{ "permission": { "bash": "allow", "edit": "ask" } }

Инструменты и MCP

zubrcode mcp add          # добавить сервер (спросит имя и команду или URL)
zubrcode mcp list         # что подключено

Внутри сессии серверы включаются и выключаются /mcps.

Навыки ZuBrIQ

Те же навыки, что в чате: договоры, таблицы, презентации, PDF, разбор выписок и другие — каталог на zubriq.by/skills.

zubrcode skills list                        # каталог, ✓ — установленные
zubrcode skills add contract-review         # поставить навык (или обновить)
zubrcode skills add --shelf documents       # все навыки полки
zubrcode skills remove contract-review

Навык ставится в ~/.config/zubrcode/skills/ и подхватывается со следующей сессии: агент сам берёт его, когда задача подходит, или по просьбе — «используй навык xlsx». Навыки со скриптами (Word, Excel, PowerPoint, PDF, распознавание сканов) пользуются Python-библиотеками — openpyxl, python-docx, python-pptx, pdfplumber и другими; пересчёт таблиц и превью документов — через LibreOffice. Не хватает библиотеки — агент скажет, какой; в сессиях «Кода» в чате всё это уже стоит.

Переход с zq

Ставится рядом. Бинари разные (zq и zubrcode), настройки тоже (~/.qwen и ~/.config/zubrcode) — можно пробовать ZubrCode и возвращаться к zq.
Входить заново не нужно. Если вы входили в zq через браузер, ZubrCode возьмёт ключ из ~/.qwen/settings.json сам. MCP-серверы оттуда же подключатся автоматически.
Правила проекта (QWEN.md, AGENTS.md) работают без изменений.
История сессий zq не переносится.

Свой раннер: код на вашей машине, управление из чата

Как Remote Control у Claude Code: агент работает на вашем сервере или ноутбуке, а вести сессию можно из чата — с телефона, из другого места. В папке проекта:

zubrcode remote

Команда напечатает ссылку zubriq.by/sandbox/<id> — там лента, разрешения и диффы, как у обычной сессии, только файлы остаются у вас. Входящих портов не нужно, работает за NAT. Подробно: Свой раннер.

ZubrCode Desktop

Тот же агент в настольном приложении: несколько сессий во вкладках, правки диффом, разрешения, встроенный терминал. Вход — через zubriq.by, как в терминале: «Подключить провайдера» → ZubrIQ.

Windows — установщик. Сборка без подписи: SmartScreen попросит «Подробнее» → «Выполнить в любом случае».
Linux — AppImage (chmod +x и запуск) или .deb для Debian и Ubuntu.
macOS — Apple Silicon (M1–M4) или Intel: откройте .dmg и перетащите ZubrCode в «Программы». Сборка подписана и проверена Apple — открывается без предупреждений. Если на Mac стоит версия до 1.18.32-14, поставьте один раз заново поверх («Заменить»): старые обновляться не умеют.

Приложение обновляется само. Настройки и навыки у него общие с zubrcode в терминале (~/.config/zubrcode). Прежний ZuBrIQ Code Desktop (на движке zq) можно удалить — ZubrCode Desktop ставится отдельно.

Агент в чате, без терминала

Тот же агент есть в zubriq.by/chat — раздел «Код»: выбираете репозиторий на git.artcloud.by, ставите задачу, а агент работает в изолированном окружении и присылает ветку. Подробно — Сессии кода в чате.

Если что-то не так

«Нет ключа ZuBrIQ или он недействителен» — выполните zubrcode auth login -p zubriq или задайте ZUBRIQ_API_KEY (ключ — в zubriq.by/chat → Настройки → API-ключи).
«У организации закончился баланс или лимит ключа» — пополните баланс: zubriq.by/chat → Настройки → Биллинг.
403 key not allowed to access model — ключ выпущен на уровень без этой модели; проверьте уровень ключа в настройках чата (API-ключи) или выберите zubr-coder.
zubrcode: command not found — добавьте ~/.local/bin в PATH и откройте новый терминал.