# Зависимости плагинов Claude Code ## 1. Зависимости от других плагинов — есть полноценно В `.claude-plugin/plugin.json` есть поле `dependencies`: ```json { "name": "deploy-kit", "version": "3.1.0", "dependencies": [ "audit-logger", { "name": "secrets-vault", "version": "~2.1.0" }, { "name": "other-plugin", "marketplace": "another-marketplace" } ] } ``` Поля объекта-зависимости: - `name` (обязательно) — имя плагина. - `version` (опционально) — semver-диапазон (`^`, `~`, `>=`, `=2.1.0` и т.п.). Версии резолвятся через Node's `semver`. - `marketplace` (опционально) — имя другого marketplace, если зависимость не из текущего. Зависимости подтягиваются автоматически при `claude plugin install` — Claude Code сам разрешает дерево и выводит список добавленных в конце установки. Для cross-marketplace зависимостей: маркетплейс, из которого ставят корневой плагин, должен явно разрешить целевой маркетплейс через `allowCrossMarketplaceDependenciesOn` в своём `marketplace.json`: ```json { "name": "acme-tools", "owner": { "name": "Acme" }, "allowCrossMarketplaceDependenciesOn": ["acme-shared"], "plugins": [ ... ] } ``` Иначе зависимость из чужого маркетплейса не установится — защита от «тихого» подтягивания непроверенного кода. --- ## 2. MCP-серверы — поставляются вместе с плагином Способа два: - файл `.mcp.json` в корне плагина; - поле `mcpServers` в `plugin.json` (inline или путь к файлу). ```json { "mcpServers": { "plugin-db": { "command": "${CLAUDE_PLUGIN_ROOT}/servers/db", "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"], "env": { "DATA": "${CLAUDE_PLUGIN_DATA}" } } } } ``` MCP-серверы стартуют автоматически при включении плагина и появляются как обычные MCP-инструменты. Полезные переменные (подставляются в `command`, `args`, `env` MCP-конфига, а также в hooks, monitors, LSP, контент skill/agent): - `${CLAUDE_PLUGIN_ROOT}` — абсолютный путь к директории установленного плагина. **Эфемерный**: меняется при обновлении (старая версия живёт ~7 дней и удаляется). Сюда нельзя писать состояние. - `${CLAUDE_PLUGIN_DATA}` — персистентная директория плагина, переживает обновления. Резолвится в `~/.claude/plugins/data/{id}/`. Сюда кладут `node_modules`, venv, кэши, сгенерированный код. --- ## 3. Внешние бинари / runtime — декларации нет В схеме `plugin.json` нет полей `requires`, `engines`, `bin` или подобных для декларации требований к среде (наличия `python3`, `node`, конкретной версии и т.п.). Проверять/устанавливать бинарь нужно вручную через `SessionStart`-hook. Если бинаря нет, ошибки отображаются в `/doctor` и во вкладке Errors интерфейса `/plugin` (например, `Executable not found in $PATH` для LSP). Уточнение: папка `bin/` в плагине — это файловая конвенция (исполняемые файлы добавляются в PATH Bash-инструмента), а не декларация требований. --- ## 4. npm-пакеты — нет авто-установки, паттерн через hook `package.json` в плагине сам по себе не устанавливается Claude Code. Официально рекомендованный паттерн (`plugins-reference`, раздел Persistent data directory) — `SessionStart`-hook, который сверяет `package.json` плагина с копией в `${CLAUDE_PLUGIN_DATA}` и при изменениях ставит зависимости туда: ```json { "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\"" } ] } ] } } ``` Важно: - `node_modules` ставится в `${CLAUDE_PLUGIN_DATA}`, **не** в `${CLAUDE_PLUGIN_ROOT}` — иначе модули потеряются при обновлении плагина. - Чтобы код плагина видел установленные модули, в `env` MCP-сервера/hook'а указывается `NODE_PATH=${CLAUDE_PLUGIN_DATA}/node_modules`. ```json { "mcpServers": { "routines": { "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"], "env": { "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules" } } } } ``` Тот же паттерн применим к Python (venv в `${CLAUDE_PLUGIN_DATA}`), pip и т.п. --- ## 5. Версия Claude Code — декларации нет В схеме `plugin.json` отсутствуют поля `engines`, `claudeCodeVersion`, `minVersion` или эквивалентные. Поле `dependencies` работает только для других плагинов. Команды `claude plugin install` / `update` не проверяют совместимость плагина с версией Claude Code. Совместимость указывается автором плагина только текстом — в README, описании, документации. Это значит, что плагин теоретически может молча сломаться на старой версии Claude Code. Сама документация при этом ссылается на минимальные версии для отдельных фич — например: - `displayName` — Claude Code v2.1.143+. - `monitors` — Claude Code v2.1.105+. - `claude plugin prune` — v2.1.121+. - `--plugin-dir` для `.zip` — v2.1.128+. Но это информационные требования к читателю, а не машинная проверка. --- ## 6. Прочее ### LSP-серверы Поле `lspServers` в `plugin.json` или файл `.lsp.json`: ```json { "lspServers": { "go": { "command": "gopls", "args": ["serve"], "extensionToLanguage": { ".go": "go" } } } } ``` Плагин поставляет **только конфиг** — сам бинарь языкового сервера (`gopls`, `pyright` и т.п.) пользователь ставит отдельно. Если бинаря нет, во вкладке `/plugin` Errors появляется `Executable not found in $PATH`. ### Monitors (фоновые процессы) Поле `monitors` в `plugin.json` (или `experimental.monitors`) — фоновые команды, которые Claude Code запускает автоматически при включении плагина. Требует Claude Code v2.1.105+. ```json { "monitors": [ { "name": "error-log", "command": "tail -F ./logs/error.log" } ] } ``` ### userConfig Поле `userConfig` объявляет значения, которые Claude Code запрашивает у пользователя при включении плагина: ```json { "userConfig": { "api_token": { "type": "string", "title": "API token", "description": "API authentication token", "sensitive": true } } } ``` Значения подставляются через `${user_config.<key>}` в hooks, MCP-конфигах, LSP-конфигах и monitor-командах: ```json "command": "${CLAUDE_PLUGIN_ROOT}/scripts/poll-deploy.sh ${user_config.api_endpoint}" ``` Технически это не «зависимость», а требование к конфигурации пользователя. --- ## Итоговая таблица | Тип зависимости | Авто-разрешение | Где декларируется | |---|---|---| | Другие плагины | ✅ | `dependencies` в `plugin.json` | | MCP-серверы | ✅ | `mcpServers` или `.mcp.json` | | LSP — конфиг | ✅ | `lspServers` или `.lsp.json` | | LSP — бинарь | ❌ | пользователь ставит сам | | Внешние бинари / runtime | ❌ | только через `SessionStart`-hook | | npm / pip пакеты | ❌ | `SessionStart`-hook + `${CLAUDE_PLUGIN_DATA}` | | Версия Claude Code | ❌ | README (текстом) | | Конфигурация пользователя | ✅ (запрос) | `userConfig` + `${user_config.xxx}` | Полноценная система зависимостей с авто-разрешением есть **только для самих плагинов**. Всё остальное — либо «приложено внутрь плагина» (MCP, LSP-конфиг, monitors), либо разруливается вручную через hooks и переменные `${CLAUDE_PLUGIN_ROOT}` / `${CLAUDE_PLUGIN_DATA}`. --- ## Источники (официальная документация) - `docs.claude.com/en/docs/claude-code/plugin-dependencies` — система `dependencies`, semver, cross-marketplace. - `docs.claude.com/en/docs/claude-code/plugins-reference` — полная схема `plugin.json`, MCP, LSP, monitors, userConfig, persistent data, переменные окружения. - `docs.claude.com/en/docs/claude-code/plugins` — общее руководство по созданию плагинов.