@purpleschool/ai-for-code

Мастер настройки «AI для кода» от PurpleSchool: подставляет ключ и base URL прокси PurpleSchool в нужные конфиги. Два провайдера:

• Claude — ANTHROPIC_API_KEY/ANTHROPIC_BASE_URL для Claude Code CLI, OpenCode, Pi, VS Code, Cursor, Windsurf, Cline (JetBrains) и Neovim (avante.nvim).
• OpenAI Codex — OPENAI_API_KEY и model_providers в ~/.codex/config.toml для Codex CLI.

Без ручной правки JSON/TOML/dotfiles.

Использование

npx @purpleschool/ai-for-code

Первый вопрос — «Установить» или «Удалить», второй — какого провайдера настраиваем (Claude или OpenAI Codex).

Установить

1. Спросит API-ключ (личный кабинет → раздел «API») и сразу проверит его живым запросом к proxy (GET /v1/models) — при 401/403 попросит ввести ключ заново, при недоступности сети спросит, продолжать ли без проверки.
2. Сам определит, какие инструменты уже установлены на машине, и предложит их отметить (можно доотметить вручную то, что не нашёл).
3. Предупредит, какие файлы будет менять, и попросит подтверждение.
4. Внесёт изменения, сохранив бэкап каждого тронутого файла в ~/.purpleschool-ai-backups/.

Удалить

Ключ не спрашивается — не нужен для отката. Мастер сам определяет, что похоже настроено именно им (по маркеру в shell rc, по нашим записям в settings.json, по файлу purpleschool-avante.lua), предлагает отметить нужное и точечно снимает только то, что сам добавлял — чужие настройки, комментарии в JSON и посторонние переменные окружения не трогает. Каждая правка тоже бэкапится перед изменением.

Все инструменты, которые пишут переменные окружения в shell rc (Claude Code CLI, OpenCode, Pi, Neovim, OpenAI Codex CLI), делят один и тот же маркированный блок, но удаление точечное — снимаются только переменные конкретного инструмента, ключи остальных в этом же блоке не трогаются. CLI-пакеты (@anthropic-ai/claude-code, @openai/codex) и расширения в IDE при удалении не трогаются — только конфиг подключения к прокси.

Флаг --dry-run в любом режиме показывает план действий без изменения файлов.

Что именно меняется

| Инструмент | Файл(ы) | Как | | --- | --- | --- | | Claude Code (CLI) | ~/.zshrc/~/.bashrc (или setx), ~/.claude/settings.json (env-блок), ~/.claude.json | env-блок в шелле, тот же креды в официальный env-блок настроек (работает сразу, без нового терминала), hasCompletedOnboarding, плюс пред-одобрение ключа (customApiKeyResponses.approved) — без него интерактивный claude пишет «Not logged in», пока не одобришь ключ вручную через /config | | OpenCode (CLI) | shell rc (или setx), ~/.config/opencode/opencode.json (на Windows — %APPDATA%\opencode\) | ANTHROPIC_API_KEY в shell rc; встроенный провайдер anthropic перенаправляется на прокси через provider.anthropic.options.baseURL + apiKey: "{env:ANTHROPIC_API_KEY}" — модели, blacklist/whitelist и другие провайдеры в файле не трогаются | | Pi (CLI) | shell rc (или setx), ~/.pi/agent/models.json | ANTHROPIC_API_KEY в shell rc; providers.anthropic.baseUrl + apiKey: "$ANTHROPIC_API_KEY" — блок models не пишем, поэтому весь встроенный список моделей Anthropic остаётся, просто ходит через прокси | | VS Code / Cursor / Windsurf | settings.json расширения Claude Code | мерджит claudeCode.environmentVariables по имени переменной и claudeCode.disableLoginPrompt, не трогая остальные настройки | | Cline (JetBrains) | — | автонастройка недоступна (нет стабильного пути к конфигу плагина) — пошаговая инструкция (View → Tool Windows → Cline → шестерёнка) + ключ в буфере обмена | | Neovim (avante.nvim) | shell rc + lua/plugins/purpleschool-avante.lua | env-переменные + файл-спека для lazy.nvim в актуальной схеме providers.claude | | OpenAI Codex (CLI) | shell rc (или setx), ~/.codex/config.toml | OPENAI_API_KEY в shell rc; model_providers.purpleschool (base_url, env_key, wire_api = "responses") и model_provider в config.toml |

Все правки — аддитивные и идемпотентные: повторный запуск не плодит дублирующиеся блоки и не трогает несвязанные настройки пользователя.

Доктор конфликтующих настроек

Перед записью в ~/.claude/settings.json мастер проверяет файл на настройки, которые, по документации Anthropic (или по отсутствию в ней), могут молча перебивать наш ключ:

• apiKeyHelper — если задан, его вывод имеет приоритет над env.ANTHROPIC_API_KEY и полностью его перебивает (документированное поведение).
• env.CLAUDE_CODE_DISABLE_GATEWAY — не встречается ни в одном официальном источнике Anthropic; судя по названию, может отключать трактовку ANTHROPIC_BASE_URL как шлюза.

Если что-то из этого найдено — мастер явно показывает находку и спрашивает разрешения убрать (с бэкапом, как обычно), не удаляет молча. Проверка сознательно не пытается угадывать «все подозрительные ключи» — Claude Code имеет много легитимных env-переменных (Bedrock/Vertex/ Foundry, кастомные заголовки и т.д.), и общая эвристика по имени ключа дала бы ложные срабатывания.

Кросс-платформенность

Работает под macOS, Windows и любой дистрибутив Linux (детект платформы, command -v вместо which, $XDG_CONFIG_HOME — всё уважает конкретный дистрибутив, а не только Ubuntu/Debian).

Отдельно на Linux для VS Code учитываются три способа установки: нативная (.deb/.rpm/ tarball), официальный Flatpak (com.visualstudio.code) и официальный Snap (code) — CLI сам находит, какой из них реально используется. Для Cursor и Windsurf это не сделано: у них нет подтверждённых официальных Flatpak/Snap-сборок, а гадать чужой app id не хотелось.

На Linux у Windsurf папка настроек — строчными буквами (~/.config/windsurf), в отличие от macOS/Windows (Windsurf) и в отличие от Cursor, у которого регистр везде одинаковый (Cursor) — учтено отдельно, файловая система на Linux регистрозависима.

Сверено с официальной документацией

Каждая настройка проверена по первоисточникам (Anthropic docs, GitHub-репозитории avante.nvim и Cline, а не только по инструкциям с сайта PurpleSchool). По итогам сверки:

• claudeCode.environmentVariables, claudeCode.disableLoginPrompt — подтверждены дословно официальной страницей Connect Claude Code to an LLM gateway и Use Claude Code in VS Code: формат массива {name, value} и сами имена ключей совпадают один в один.

• CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY — подтверждена, требует Claude Code ≥2.1.129, дёргает GET /v1/models у прокси — тем же эндпоинтом мы проверяем валидность ключа при вводе.

• ~/.claude.json + hasCompletedOnboarding — оказался недокументированным файлом (это файл OAuth-сессии/MCP/кеша, не settings.json); официально задокументированный способ решить ту же проблему («просит войти, хотя прокси отвечает») — env-блок в ~/.claude/settings.json. Мы теперь пишем оба: официальный env-блок (работает мгновенно) и hasCompletedOnboarding (сохранили как доп. подстраховку для более старых версий CLI, где встречался этот баг).

• avante.nvim: схема конфига провайдера сменилась. Актуальный формат — вложенный providers.claude = {...}, а не плоский claude = {...} рядом с provider. Старая схема, которую мы генерировали раньше, устарела — обновили генератор снипета под текущую.

• Cline (JetBrains) существует и общедоступен (GA с сентября 2025), но наша инструкция по доступу к настройкам была неточной («File → Settings → Tools → Cline» — такой страницы нет). Верно: View → Tool Windows → Cline открывает панель плагина, дальше — значок настроек внутри неё, поле «Use custom base URL».

• OpenCode и Pi: base URL нужен уже с /v1. В отличие от ANTHROPIC_BASE_URL (там /v1 дописывает сам Anthropic SDK), оба инструмента используют baseURL/baseUrl как есть: @ai-sdk/anthropic в OpenCode имеет дефолт https://api.anthropic.com/v1, а в примерах pi прокси тоже указан с /v1. Поэтому в их конфиги пишется .../ai-proxy/anthropic/v1.

• Ключ в их конфиги не попадает. У обоих есть родная подстановка переменных окружения ({env:ANTHROPIC_API_KEY} у OpenCode, $ANTHROPIC_API_KEY у pi) — в файле лежит только ссылка, сам ключ живёт в shell rc / setx.

• Оба переопределяют встроенного провайдера, а не заводят свой. Список моделей Anthropic берётся из самого инструмента (/models в OpenCode, /model в pi) — нам не нужно хардкодить и поддерживать актуальный перечень моделей.

Известные ограничения (сознательно не покрыты в v1):

• ANTHROPIC_API_KEY общий у Claude Code CLI, OpenCode, Pi и Neovim. Это одна и та же переменная в одном блоке shell rc, поэтому удаление любой из этих целей убирает её и у остальных (конфиги самих инструментов при этом не трогаются). Если сняли лишнее — просто прогоните «Установить» ещё раз.
• WSL + VS Code на Windows-хосте. Если запустить мастер внутри WSL, а VS Code использует Remote-WSL с хостовым settings.json на Windows-стороне, правки попадут не в тот файл. Запускай мастер там же, где физически лежит нужный settings.json.
• Корпоративные HTTP(S)-прокси. Проверка ключа не читает HTTP_PROXY/HTTPS_PROXY — за прокси она просто скажет «не смог проверить» и предложит продолжить без неё (не блокирует настройку, только сам шаг верификации).
• sudo. Запуск через sudo заблокирован явным сообщением — $HOME в этом случае указывает на /root, а не на реальный профиль пользователя.
• ~/.codex/config.toml — комментарии не сохраняются. В отличие от правок settings.json (сохраняют комментарии через jsonc-parser), TOML-библиотека без CST-редактора: файл парсится в объект, правится и сериализуется заново. Бэкап оригинала сохраняется перед каждой правкой, но ручные комментарии в config.toml после этого пропадут.
• /compact в Codex для стороннего провайдера. У Codex CLI команда /compact бьёт в POST /v1/responses/compact только при разговоре с api.openai.com; для любого кастомного model_provider (включая наш) Codex сам переключается на локальный fallback — суммаризацию через обычный /v1/responses. Поэтому эндпоинт .../openai/v1/responses/compact на прокси можно не поднимать: Codex CLI его не вызывает при работе через кастомного провайдера.

FAQ

«Запускаю claude, а он не видит API-ключ / пишет "Not logged in · Please run /login", хотя настройка вроде прошла».

С версии 0.2.0 мастер сам решает эту проблему при установке (см. customApiKeyResponses в таблице выше). Если всё равно видишь это сообщение — например, ключ был прописан вручную или машина настраивалась старой версией мастера:

1. Запусти claude интерактивно.
2. Введи /config.
3. Найди пункт «Use custom API key» и включи его.
4. Задай вопрос заново — статус login должен пропасть.

Причина: Claude Code требует одноразового интерактивного подтверждения кастомного API-ключа. Без него headless-запросы (claude --print "...") работают нормально, а интерактивная сессия держит баннер «не залогинен», даже если сам ключ рабочий. Официально задокументировано в troubleshooting-таблице Connect Claude Code to an LLM gateway.

«В ~/.claude/settings.json появились apiKeyHelper или CLAUDE_CODE_DISABLE_GATEWAY, и всё сломалось».

См. «Доктор конфликтующих настроек» выше — при следующем запуске «Установить» мастер сам это найдёт и предложит убрать. Вручную: удали apiKeyHelper и env.CLAUDE_CODE_DISABLE_GATEWAY из файла, оставь только env.ANTHROPIC_API_KEY и env.ANTHROPIC_BASE_URL.

Разработка

npm install
npm run dev        # запуск через tsx без сборки
npm run typecheck
npm run build       # сборка в dist/cli.js (ESM, с shebang)

Публикация

npm run build
npm publish --access public

Требуется npm-аккаунт с доступом к организации @purpleschool.