Установка

Apothem устанавливается менее чем за две минуты и работает рядом с вашей существующей конфигурацией окружения. Каждый путь запускает один и тот же самодостаточный движок — дерево исходного кода несёт свои вендоренные зависимости и запускается из чекаута на системном Python 3.10 или новее (см. самодостаточную среду выполнения).

Два предварительных требования общие для всех путей: системный Python 3.10 или новее в PATH, под которым импортируются пакеты click и rich. Для npm-шима (канал 2), расширения для семейства VS Code (канал 4) и загрузчиков командной строки (каналы 5–7) дополнительно нужен Node.js 18 или новее для запуска npx. У Python 3.10 и Node.js 18 и 20 закончился срок поддержки в upstream; они остаются поддерживаемыми и тестируемыми, но предпочтительны более новые версии (см. Предварительные требования кратко). Собственный раздел каждого канала ниже повторяет его точные предварительные требования, одну готовую к копированию команду и шаг проверки.

Выберите каналCopy Anchor Link

Доступно восемь каналов установки. Выбирайте по тому, как вы уже работаете.

Каждый путь идемпотентен: повторный запуск безопасен и приводит к тому же состоянию.

1. Плагин Claude CodeCopy Anchor Link

Предварительные требования: Claude Code и системный Python 3.10+ в PATH.

Путь плагина выполняется целиком внутри Claude Code. Он поставляет движок Apothem вместе с его слеш-командами, делегированными исполнителями, навыками, правилами и хуками — всё это запускается из самодостаточного дерева плагина:

/plugin marketplace add ahmed-g-gad/apothem
/plugin install apothem@apothem

После установки набор команд Apothem, входящие в комплект делегированные исполнители, навыки и четыре output-стиля (выберите один через /output-style или в /config) доступны в каждой сессии Claude Code. Плагин поставляет каждую команду как навык — файл SKILL.md, подробности к которому, загружаемые по требованию, лежат рядом в папке references/, — поэтому Claude Code вызывает её с префиксом плагина: /apothem:plan-spec, /apothem:security-audit и остальные. Два имени заняты самим Claude Code: /plan включает режим планирования, а /code-review запускает встроенное ревью, поэтому для команд Apothem вводите /apothem:plan и /apothem:code-review. Когда в Claude Code вместо плагина устанавливается движок Apothem, те же навыки записываются в ~/.claude/skills/ без префикса, а личный навык code-review заменяет встроенный /code-review (его псевдоним /review по-прежнему запускает встроенный). Два имени, projectify и workflow, также являются нативными навыками; плагин и установка движка поставляют именно нативный навык, а не навык, созданный из команды. О том, как разделены команды, см. Claude Code, а полный каталог команд — в разделе Слеш-команды.

Проверка: запустите /plugin внутри Claude Code и убедитесь, что apothem указан как установленный, либо проверьте отчёт о дрейфе из терминала:

npx @ahmed-g-gad/apothem verify --harness claude-code

2. npm-шим (npx)Copy Anchor Link

Предварительные требования: Node.js 18+ (для npx) и системный Python 3.10+ в PATH. Шим находит интерпретатор и передаёт каждую команду CLI встроенному движку — ничего не размещается в вашей системе постоянно. Он пробует python3, python, затем py -3 в этом порядке; задайте в APOTHEM_PYTHON путь к интерпретатору, чтобы он был опробован первым, — это нужно, когда Python установлен, но не находится в PATH, или когда установлено несколько версий и вам нужна конкретная. Указанный вами интерпретатор всё равно должен пройти проверку на Python 3.10+; если он её не проходит, шим переходит к python3, python, затем py -3.

npx @ahmed-g-gad/apothem install --harness claude-code

На машине без профиля эта первая команда install создаёт начальный профиль в ~/.config/apothem/profile.yaml и сообщает об этом. Его поля идентичности — заполнители: персонализируйте их (npx @ahmed-g-gad/apothem profile edit), затем повторите команду с update вместо install, чтобы применить их.

Он также запускается прямо из репозитория:

npx github:ahmed-g-gad/apothem install --harness claude-code

Каждая команда из справочника CLI работает в этой форме; замените apothem на npx @ahmed-g-gad/apothem. Это также путь установки для OpenCode и любого другого инструмента, который не предоставляет отдельного реестра плагинов или расширений, — Apothem синхронизирует их прямо в их нативный каталог конфигурации (npx @ahmed-g-gad/apothem install --harness opencode).

Проверка:

npx @ahmed-g-gad/apothem --version
npx @ahmed-g-gad/apothem verify --harness claude-code

3. Одношаговые установщикиCopy Anchor Link

Предварительные требования: системный Python 3.10+ в PATH (установщик предлагает добавить за вас предварительные требования click / rich); git и gpg нужны для сетевой установки, которая клонирует исходный код и проверяет подписанный тег релиза (Git for Windows поставляется с обоими).

Скрипты установщика определяют последний подписанный тег релиза, проверяют его подпись, размещают дерево исходного кода Apothem в ~/.apothem на этом теге, создают начальный профиль, если его нет, материализуют ваше первое окружение и проверяют результат — всё за один запуск. Начальный профиль содержит поля идентичности с заполнителями: отредактируйте его, затем выполните apothem update --harness <name>, чтобы применить свои значения. Повторный запуск идемпотентен: существующее дерево заново переключается на определённый тег, а окружение материализуется повторно. Проверенная установка, закреплённая за тегом, — путь по умолчанию и рекомендуемый путь.

Сначала однократно импортируйте ключ подписи сопровождающего. Установщик останавливается, если ключа нет в вашей связке ключей. Проверьте, что отпечаток равен 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163, то есть значению, которое публикует SECURITY.md. В Windows git verify-tag читает связку ключей gpg, которая поставляется с Git for Windows, поэтому импорт выполняется через собственный bash Git:

curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import
gpg --fingerprint 70396FED9C634163

& "$env:ProgramFiles\Git\bin\bash.exe" -c 'curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import && gpg --fingerprint 70396FED9C634163'

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

irm https://apothem.ahmedgad.com/install.ps1 | iex

Те же скрипты поставляются в чекауте в scripts/installer/ — install, uninstall и update в формах .sh, .ps1 и .bat, — так что вы можете запускать их напрямую после клонирования:

APOTHEM_HARNESS=claude-code sh scripts/installer/install.sh                                 # POSIX
$env:APOTHEM_HARNESS = 'claude-code'; pwsh -NoProfile -File scripts/installer/install.ps1   # Windows

Модель доверияCopy Anchor Link

Если APOTHEM_REF не задана, установщик определяет наивысший тег релиза vMAJOR.MINOR.PATCH и переключается именно на него — никогда не на подвижную ветку main. Перед материализацией любой конфигурации подпись полученного тега проверяется с помощью git verify-tag; неподписанный, подделанный или непроверяемый тег прерывает установку до того, как что-либо будет записано. Подписанный тег, для которого открытого ключа сопровождающего ещё нет в локальной связке ключей, вместо этого прерывает установку с указаниями по импорту ключа: импортируйте ключ, как показано выше, сверьте его отпечаток со значением, опубликованным в SECURITY.md, и запустите установку снова. Закрепите конкретный релиз с помощью APOTHEM_REF:

APOTHEM_REF=vMAJOR.MINOR.PATCH sh -c "$(curl -fsSL https://apothem.ahmedgad.com/install.sh)"

Замените vMAJOR.MINOR.PATCH на тег со страницы релизов. Самый старый тег релиза — легковесный тег без собственной подписи, поэтому проверка тега прерывается на нём, хотя его коммит подписан; каждый более поздний тег релиза аннотирован и подписан. Раздел о подписи релизов в SECURITY.md перечисляет каждый тег и способ его проверки.

Явные переопределения ослабляют поведение по умолчанию. APOTHEM_ALLOW_UNVERIFIED=1 понижает сбой проверки до предупреждения и продолжает работу — для работы в изолированной от сети среде или локально, либо чтобы установить релиз, вышедший до подписи тегов. APOTHEM_REF=main переключается на подвижную ветку без проверки только вместе с APOTHEM_ALLOW_UNVERIFIED=1. Если задан один лишь APOTHEM_REF=main, установщик загружает main в APOTHEM_HOME, а затем прерывает работу до материализации какой-либо конфигурации, поскольку ветка не является подписанным тегом релиза. Локальный чекаут через APOTHEM_SOURCE ничего не загружает и пропускает проверку.

APOTHEM_VERIFY=checksum — промежуточный путь для хоста, у которого ещё нет открытого ключа сопровождающего: вместо клонирования установщик скачивает платформенный архив релиза и его SHA256SUMS, прерывает работу при несовпадении дайджеста до извлечения чего-либо и предупреждает, что совпадающий дайджест доказывает, что архив — тот, который указан в релизе, но не то, кто его опубликовал.

Затем движок выполняется прямо из размещённого дерева. Каждая сторонняя зависимость, кроме click и rich, вендорена внутри дерева исходного кода, а точка входа сама добавляет этот каталог вендоренных зависимостей в sys.path:

PYTHONPATH="$HOME/.apothem/src" python -m apothem <command>

Оба скрипта читают одни и те же конфигурационные переменные окружения (APOTHEM_HOME, APOTHEM_REPO, APOTHEM_REF, APOTHEM_ALLOW_UNVERIFIED, APOTHEM_VERIFY, APOTHEM_RELEASE_BASE, APOTHEM_SOURCE, APOTHEM_HARNESS, APOTHEM_PROFILE, APOTHEM_SKIP_VERIFY, APOTHEM_AUTO_INSTALL_DEPS, APOTHEM_BIN_DIR); полную таблицу см. в разделе Переменные окружения установщика, а как работает модель вызова python -m — в разделе Самодостаточная среда выполнения.

Команда apothem. После успешной установки установщик записывает шим apothem, который перенаправляет вызовы встроенному движку, — в POSIX в $HOME/.local/bin, в Windows в %LOCALAPPDATA%\Microsoft\WindowsApps (пользовательский каталог, который уже есть в стандартном PATH Windows). Установщик никогда не редактирует ваш PATH. Как только каталог окажется в PATH, вы запускаете apothem <command> напрямую, без ручной настройки PYTHONPATH.

Проверка:

apothem verify --harness claude-code

# or, before the shim is on PATH, from the bundled source:
PYTHONPATH="$HOME/.apothem/src" python -m apothem verify --harness claude-code

4. Расширение для семейства VS CodeCopy Anchor Link

Предварительные требования: VS Code, Node.js 18+ и системный Python 3.10+ в PATH.

Расширение Apothem for VS Code доступно в Visual Studio Marketplace как ahmed-g-gad.apothem-vscode: установите его из представления «Расширения» или командой code --install-extension ahmed-g-gad.apothem-vscode. Оно также устанавливается из пакета apothem.vsix: code --install-extension apothem.vsix или командой редактора Install from VSIX…. Релизный рабочий процесс подписывает пакет и прикладывает его к каждому GitHub Release. Релизы, опубликованные до того, как рабочий процесс начал упаковывать расширение, не содержат .vsix; если в последнем релизе его нет, соберите пакет из чекаута с версией vsce, зафиксированной в tools/vsce/ (этой версии vsce нужен Node.js 22 или новее): выполните npm ci --prefix tools/vsce --ignore-scripts, затем cd vscode-extension && ../tools/vsce/node_modules/.bin/vsce package --no-dependencies --out apothem.vsix. Копия, установленная из более раннего apothem.vsix, имеет идентификатор ahmed-g-gad.apothem; удалите её (code --uninstall-extension ahmed-g-gad.apothem), чтобы обе копии не регистрировали одни и те же команды. Одно расширение охватывает редакторы семейства VS Code. Его команды палитры (Apothem: Install, Verify, Update, Uninstall, Doctor) запускают тот же движок через настроенное средство запуска (по умолчанию npx @ahmed-g-gad/apothem@<extension version>, поэтому расширение запускает ту версию движка, с которой оно поставлялось; укажите в пользовательской настройке apothem.runner локальный чекаут, чтобы запускать из исходного кода). Install, Verify, Update и Uninstall спрашивают, с каким окружением работать, и первым предлагают окружение самого редактора; all — один из вариантов выбора, но никогда не вариант по умолчанию. Настройка apothem.runner действует на уровне машины, поэтому рабочая область не может её изменить, а расширение работает только в доверенной рабочей области.

Проверка: запустите команду Apothem: Verify из палитры команд редактора или из терминала:

npx @ahmed-g-gad/apothem verify --harness claude-code

5. Загрузчик командной строки (хост расширений)Copy Anchor Link

Предварительные требования: его хост-инструмент командной строки, Node.js 18+ и системный Python 3.10+ в PATH.

Установите Apothem как расширение прямо из репозитория — команда содержит точный slug хоста и окружения:

gemini extensions install https://github.com/ahmed-g-gad/apothem

Это расширение — загрузчик, а не полная установка сама по себе: оно загружает контекстный файл Apothem и добавляет команду /apothem, которая через оболочку вызывает движок (npx @ahmed-g-gad/apothem). Материализуйте полное окружение, запустив установку через него:

npx @ahmed-g-gad/apothem install --harness gemini-cli --project .

Проверка:

npx @ahmed-g-gad/apothem verify --harness gemini-cli --project .

6. Загрузчик командной строки (хост qwen-code)Copy Anchor Link

Предварительные требования: его хост-инструмент командной строки, Node.js 18+ и системный Python 3.10+ в PATH.

Установите Apothem как расширение --harness qwen-code прямо из репозитория:

qwen extensions install ahmed-g-gad/apothem

Как и расширение канала 5, это загрузчик: оно загружает контекстный файл Apothem и через оболочку вызывает движок. Материализуйте полное окружение, запустив установку через него:

npx @ahmed-g-gad/apothem install --harness qwen-code

Проверка:

npx @ahmed-g-gad/apothem verify --harness qwen-code

7. Загрузчик командной строки (хост плагинов)Copy Anchor Link

Предварительные требования: его хост-инструмент командной строки, Node.js 18+ и системный Python 3.10+ в PATH.

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

codex plugin marketplace add ahmed-g-gad/apothem --sparse .agents/plugins --sparse plugins/apothem
codex plugin add apothem@apothem

Два пути --sparse загружают только листинг маркетплейса и плагин, а не весь репозиторий; полное клонирование может превысить 30-секундный лимит клонирования хоста на медленном диске, например на диске Windows под WSL.

Как и расширения каналов 5 и 6, это загрузчик, который через оболочку вызывает движок. Плагин включает один входной навык; его манифест — корневой plugin.json, а страница окружения хоста плагинов описывает структуру и то, что плагин оставляет движку. Материализуйте полное окружение, запустив установку через него:

npx @ahmed-g-gad/apothem install --harness codex

Проверка:

npx @ahmed-g-gad/apothem verify --harness codex

8. Прямой движок (python -m apothem)Copy Anchor Link

Предварительные требования: системный Python 3.10+ с импортируемыми пакетами click и rich, а также чекаут репозитория. Node.js не требуется.

Запустите движок прямо из клона. Точка входа добавляет вендоренные зависимости (src/apothem/_vendor) в sys.path, поэтому, когда click и rich импортируются, PYTHONPATH=src — это вся настройка:

git clone https://github.com/ahmed-g-gad/apothem
cd apothem
PYTHONPATH=src python -m apothem install --harness claude-code

Как и в случае npm-шима, первая команда install на машине без профиля создаёт начальный профиль в ~/.config/apothem/profile.yaml и продолжает работу.

Проверка:

PYTHONPATH=src python -m apothem verify --harness claude-code

Проверка любой установкиCopy Anchor Link

Каждый канал выше называет свою собственную команду проверки. Две общие формы таковы:

PYTHONPATH="$HOME/.apothem/src" python -m apothem verify --harness claude-code

npx @ahmed-g-gad/apothem verify --harness claude-code

Замените имя окружения на тот адаптер, который вы установили; все поддерживаемые имена см. в списке окружений. Чтобы проверить сразу каждый установленный адаптер (его действие verify и его команды хуков), запустите doctor вместо verify --harness NAME в той же форме, которую вы использовали выше: apothem doctor, PYTHONPATH="$HOME/.apothem/src" python -m apothem doctor или npx @ahmed-g-gad/apothem doctor. Для пути плагина запустите /plugin внутри Claude Code и убедитесь, что apothem указан как установленный.

Предварительные требования краткоCopy Anchor Link

• Python 3.10 или новее — пути, которые находят его сами, ищут его по имени, и имена различаются от пути к пути. npm-шим пробует python3, python, затем py -3. Установщики пробуют python3, python и имена с номером версии от python3.14 до python3.10 по убыванию.
• Импортируемые click и rich под этим интерпретатором — две обращённые к терминалу зависимости, которые движок не вендорит. Установщики проверяют обе, называют всё недостающее и предлагают установить это за вас — с вашего подтверждения или автоматически с --yes (-Yes в PowerShell) либо APOTHEM_AUTO_INSTALL_DEPS=1. На любом другом канале отсутствующий пакет останавливает движок с ошибкой (код выхода 1), которая называет точную команду для найденного интерпретатора с ограничениями версий, на которых тестируется Apothem (<interpreter> -m pip install "click==…" "rich>=…"); с --json та же ошибка приходит в виде JSON-конверта с кодом runtime.dependency_missing.
• Node.js 18 или новее — только пути, которые запускают npx: npm-шим (2), расширение для семейства VS Code (4) и загрузчики командной строки (5–7).
• Среды выполнения с истёкшим сроком поддержки. Срок поддержки Python 3.10 в upstream закончился 2026-10-01, а Node.js 18 и 20 — 2025-04-30 и 2026-04-30. Apothem по-прежнему поддерживает их как свои объявленные минимальные версии и тестирует каждую в CI, но они больше не получают исправлений безопасности из upstream, поэтому отдавайте предпочтение Python 3.11 или новее и Node.js 22 или новее. Политика минимальных версий сред выполнения объясняет, как повышается минимальная версия.
• Git — только путь установщика и только для сетевой формы (скрипт клонирует исходный код; локальному чекауту клонирование не нужно).
• Claude Code — только путь плагина. VS Code и собственный хост-инструмент каждого загрузчика командной строки нужны только для их собственного канала (4–7).

Следующие руководстваCopy Anchor Link