Installation

Apothem s'installe en moins de deux minutes et fonctionne aux côtés de votre configuration d'environnement existante. Chaque voie exécute le même moteur autonome — l'arborescence source porte ses dépendances vendorisées et s'exécute depuis un checkout sur le Python 3.10 ou plus récent du système (voir le runtime autonome).

Deux prérequis sont communs à toutes les voies : Python 3.10 ou plus récent du système sur le PATH, avec les paquets click et rich importables sous cet interpréteur. Le shim npm (canal 2), l'extension de la famille VS Code (canal 4) et les amorçages en ligne de commande (canaux 5–7) ont en plus besoin de Node.js 18 ou plus récent pour exécuter npx. Python 3.10 ainsi que Node.js 18 et 20 ont dépassé leur fin de vie en amont ; ils restent pris en charge et testés, mais les versions plus récentes sont à privilégier (voir Prérequis en un coup d'œil). La section propre à chaque canal ci-dessous reprend ses prérequis exacts, une commande prête à copier et une étape de vérification.

Choisir un canalCopy Anchor Link

Huit canaux d'installation sont disponibles. Choisissez selon votre façon de travailler actuelle.

Chaque voie est idempotente : la relancer est sans danger et converge vers le même état.

1. Plugin Claude CodeCopy Anchor Link

Prérequis : Claude Code, et Python 3.10+ du système sur le PATH.

La voie du plugin s'exécute entièrement dans Claude Code. Elle embarque le moteur Apothem avec ses commandes slash, ses travailleurs délégués, ses skills, ses règles et ses hooks, tous exécutables depuis l'arborescence autonome du plugin :

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

Après l'installation, l'ensemble des commandes Apothem, les travailleurs délégués inclus, les skills et les quatre output-styles (choisissez-en un avec /output-style ou depuis /config) sont disponibles dans chaque session Claude Code. Le plugin livre chaque commande comme une skill, un SKILL.md accompagné, dans un dossier references/ voisin, du détail qu'il charge à la demande ; Claude Code l'invoque donc avec le préfixe du plugin : /apothem:plan-spec, /apothem:security-audit et les autres. Deux noms sont pris par Claude Code lui-même : /plan active le mode plan et /code-review lance la revue intégrée ; tapez donc /apothem:plan et /apothem:code-review pour les commandes Apothem. Lorsque le moteur Apothem s'installe dans Claude Code à la place du plugin, les mêmes skills sont écrites dans ~/.claude/skills/, sans préfixe, et une skill personnelle code-review remplace le /code-review intégré (son alias /review exécute toujours la revue intégrée). Deux noms, projectify et workflow, sont aussi des skills natives ; la skill native est celle que livrent le plugin et l'installation par le moteur, et non une skill dérivée de la commande. Consultez Claude Code pour la façon dont les commandes sont découpées, et Commandes slash pour le catalogue complet des commandes.

Vérifiez : exécutez /plugin dans Claude Code et confirmez qu'apothem figure comme installé, ou consultez le rapport de dérive depuis un terminal :

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

2. Shim npm (npx)Copy Anchor Link

Prérequis : Node.js 18+ (pour npx) et Python 3.10+ du système sur le PATH. Le shim localise l'interpréteur et transmet chaque commande de la CLI au moteur inclus — rien n'est placé de façon permanente sur votre système. Il essaie python3, python, puis py -3, dans cet ordre ; définissez APOTHEM_PYTHON sur le chemin d'un interpréteur pour l'essayer en premier, ce dont vous avez besoin lorsque Python est installé mais absent du PATH, ou lorsque plusieurs versions le sont et que vous en voulez une précise. L'interpréteur que vous nommez doit tout de même passer la vérification Python 3.10+ ; lorsqu'il ne la passe pas, le shim se rabat sur python3, python, puis py -3.

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

Sur une machine sans profil, ce premier install crée le profil initial à ~/.config/apothem/profile.yaml et le signale. Ses champs d'identité sont des espaces réservés : personnalisez-les (npx @ahmed-g-gad/apothem profile edit), puis relancez la commande avec update à la place de install pour les appliquer.

Il s'exécute aussi directement depuis le dépôt :

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

Chaque commande de la référence de la CLI fonctionne sous cette forme ; remplacez apothem par npx @ahmed-g-gad/apothem. C'est aussi la voie d'installation pour OpenCode et pour tout autre outil qui n'expose aucun registre de plugins ou d'extensions distinct — Apothem les synchronise directement dans leur répertoire de configuration natif (npx @ahmed-g-gad/apothem install --harness opencode).

Vérifiez :

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

3. Installateurs en une seule étapeCopy Anchor Link

Prérequis : Python 3.10+ du système sur le PATH (l'installateur propose d'ajouter les prérequis click / rich pour vous) ; git et gpg sont requis pour une installation réseau, qui clone le code source et vérifie l'étiquette de publication signée (Git for Windows fournit les deux).

Les scripts d'installation résolvent la dernière étiquette de publication signée, vérifient sa signature, placent l'arborescence source d'Apothem dans ~/.apothem à cette étiquette, créent un profil initial lorsqu'aucun n'existe, matérialisent votre premier environnement et vérifient le résultat, le tout en une seule exécution. Le profil initial contient des champs d'identité servant d'espaces réservés : modifiez-le, puis exécutez apothem update --harness <name> pour appliquer les vôtres. Relancer est idempotent : une arborescence existante est de nouveau extraite à l'étiquette résolue et l'environnement est rematérialisé. L'installation vérifiée, épinglée à une étiquette, est la voie par défaut et recommandée.

Importez d'abord la clé de signature du mainteneur, une seule fois. L'installateur s'arrête lorsque la clé n'est pas dans votre trousseau. Vérifiez que l'empreinte affiche 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163, la valeur que SECURITY.md publie. Sous Windows, git verify-tag lit le trousseau du gpg fourni avec Git for Windows ; l'importation passe donc par le bash de Git lui-même :

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

Les mêmes scripts sont livrés dans un checkout sous scripts/installer/ — install, uninstall et update sous les formes .sh, .ps1 et .bat — de sorte que vous pouvez les exécuter directement après le clonage :

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

Modèle de confianceCopy Anchor Link

Lorsque APOTHEM_REF n'est pas définie, l'installateur résout l'étiquette de publication vMAJOR.MINOR.PATCH la plus élevée et extrait celle-ci — jamais la branche mouvante main. Avant toute matérialisation de configuration, la signature de l'étiquette récupérée est vérifiée avec git verify-tag ; une étiquette non signée, altérée ou invérifiable interrompt l'installation avant toute écriture. Une étiquette signée dont la clé publique du mainteneur ne figure pas encore dans le trousseau local interrompt plutôt l'installation avec des instructions d'importation de la clé : importez la clé comme indiqué ci-dessus, comparez son empreinte à la valeur publiée dans SECURITY.md, puis relancez. Épinglez une publication précise avec APOTHEM_REF :

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

Remplacez vMAJOR.MINOR.PATCH par une étiquette de la page des publications. La plus ancienne étiquette de publication est une étiquette légère sans signature propre ; la vérification d'étiquette interrompt donc l'installation sur celle-ci, même si son commit est signé ; chaque étiquette de publication ultérieure est annotée et signée. La section de SECURITY.md consacrée à la signature des publications liste chaque étiquette et la manière de la vérifier.

Les dérogations explicites assouplissent le comportement par défaut. APOTHEM_ALLOW_UNVERIFIED=1 rétrograde un échec de vérification en simple avertissement et poursuit l'opération, pour un usage isolé du réseau ou local, ou pour installer une publication antérieure à la signature des étiquettes. APOTHEM_REF=main n'extrait la branche mouvante sans vérification qu'avec APOTHEM_ALLOW_UNVERIFIED=1. Avec APOTHEM_REF=main seul, l'installateur récupère main dans APOTHEM_HOME, puis s'interrompt avant que toute configuration ne soit matérialisée, car une branche n'est pas une étiquette de publication signée. Un checkout local via APOTHEM_SOURCE ne récupère rien et ignore la vérification.

APOTHEM_VERIFY=checksum est la voie intermédiaire pour une machine qui ne détient pas encore la clé publique du mainteneur : au lieu de cloner, l'installateur télécharge l'archive de plateforme de la publication et son SHA256SUMS, s'interrompt en cas de non-concordance du condensé avant d'extraire quoi que ce soit, et avertit qu'un condensé concordant prouve que l'archive est celle que liste la publication, et non qui l'a publiée.

Le moteur s'exécute ensuite directement depuis l'arborescence placée. Toutes les dépendances tierces, à l'exception de click et rich, sont vendorisées dans l'arborescence source, et le point d'entrée place lui-même ce répertoire de dépendances vendorisées sur sys.path :

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

Les deux scripts lisent les mêmes variables d'environnement de configuration (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) ; consultez Variables d'environnement de l'installateur pour le tableau complet et Runtime autonome pour le fonctionnement du modèle d'invocation python -m.

La commande apothem. Après une installation réussie, l'installateur écrit un shim apothem qui transmet au moteur inclus — sous POSIX dans $HOME/.local/bin, sous Windows dans %LOCALAPPDATA%\Microsoft\WindowsApps (un répertoire utilisateur déjà présent dans le PATH Windows par défaut). L'installateur ne modifie jamais votre PATH. Une fois le répertoire dans le PATH, vous exécutez apothem <command> directement, sans PYTHONPATH manuel.

Vérifiez :

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. Extension de la famille VS CodeCopy Anchor Link

Prérequis : VS Code, Node.js 18+, et Python 3.10+ du système sur le PATH.

L'extension Apothem for VS Code est disponible sur le Visual Studio Marketplace sous l'identifiant ahmed-g-gad.apothem-vscode : installez-la depuis la vue Extensions ou avec code --install-extension ahmed-g-gad.apothem-vscode. Elle s'installe aussi depuis un paquet apothem.vsix : code --install-extension apothem.vsix, ou la commande Install from VSIX… de l'éditeur. Le flux de travail de publication signe le paquet et le joint à chaque GitHub Release. Les publications parues avant que le flux de travail n'empaquette l'extension ne contiennent aucun .vsix ; lorsque la dernière publication en est dépourvue, construisez le paquet depuis un checkout avec la version de vsce verrouillée dans tools/vsce/ (cette version de vsce requiert Node.js 22 ou ultérieur) : exécutez npm ci --prefix tools/vsce --ignore-scripts, puis cd vscode-extension && ../tools/vsce/node_modules/.bin/vsce package --no-dependencies --out apothem.vsix. Une copie installée depuis un apothem.vsix antérieur porte l'identifiant ahmed-g-gad.apothem ; désinstallez-la (code --uninstall-extension ahmed-g-gad.apothem) afin que les deux copies n'enregistrent pas toutes deux les mêmes commandes. Une seule extension couvre les éditeurs de la famille VS Code. Ses commandes de palette (Apothem: Install, Verify, Update, Uninstall, Doctor) exécutent le même moteur via le lanceur configuré (npx @ahmed-g-gad/apothem@<extension version> par défaut, si bien que l'extension exécute la version du moteur avec laquelle elle a été livrée ; pointez le paramètre utilisateur apothem.runner vers un checkout local pour exécuter depuis les sources). Install, Verify, Update et Uninstall demandent sur quel environnement agir, en proposant d'abord celui de l'éditeur ; all est un choix possible, jamais la valeur par défaut. Le paramètre apothem.runner a une portée machine, si bien qu'un espace de travail ne peut pas le modifier, et l'extension ne s'exécute que dans un espace de travail approuvé.

Vérifiez : exécutez la commande Apothem: Verify depuis la palette de commandes de l'éditeur, ou depuis un terminal :

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

5. Amorçage en ligne de commande (hôte à extensions)Copy Anchor Link

Prérequis : son outil hôte en ligne de commande, Node.js 18+, et Python 3.10+ du système sur le PATH.

Installez Apothem comme extension directement depuis le dépôt — la commande porte l'hôte et le slug d'environnement exacts :

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

Cette extension est un amorçage, pas l'installation complète à elle seule : elle charge un fichier de contexte Apothem et ajoute une commande /apothem qui délègue au moteur via le shell (npx @ahmed-g-gad/apothem). Matérialisez l'environnement complet en exécutant l'installation par son intermédiaire :

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

Vérifiez :

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

6. Amorçage en ligne de commande (hôte qwen-code)Copy Anchor Link

Prérequis : son outil hôte en ligne de commande, Node.js 18+, et Python 3.10+ du système sur le PATH.

Installez Apothem comme extension --harness qwen-code directement depuis le dépôt :

qwen extensions install ahmed-g-gad/apothem

Comme l'extension du canal 5, il s'agit d'un amorçage : elle charge un fichier de contexte Apothem et délègue au moteur via le shell. Matérialisez l'environnement complet en exécutant l'installation par son intermédiaire :

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

Vérifiez :

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

7. Amorçage en ligne de commande (hôte à plugins)Copy Anchor Link

Prérequis : son outil hôte en ligne de commande, Node.js 18+, et Python 3.10+ du système sur le PATH.

Ajoutez le dépôt comme marketplace de plugins, puis installez le plugin — la commande porte l'hôte et le slug d'environnement exacts :

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

Les deux chemins --sparse ne récupèrent que la liste du marketplace et le plugin, et non le dépôt entier ; un clone complet peut dépasser la limite de clonage de 30 secondes de l'hôte sur un disque lent, tel qu'un lecteur Windows sous WSL.

Comme les extensions des canaux 5 et 6, il s'agit d'un amorçage qui délègue au moteur via le shell. Le plugin embarque une skill d'entrée ; son manifeste est un plugin.json à la racine, et la page d'environnement de l'hôte à plugins décrit cette disposition et ce que le plugin laisse au moteur. Matérialisez l'environnement complet en exécutant l'installation par son intermédiaire :

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

Vérifiez :

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

8. Moteur direct (python -m apothem)Copy Anchor Link

Prérequis : Python 3.10+ du système avec les paquets click et rich importables, plus un checkout du dépôt. Node.js n'est pas requis.

Exécutez le moteur directement depuis un clone. Le point d'entrée place les dépendances vendorisées (src/apothem/_vendor) sur sys.path ; avec click et rich importables, PYTHONPATH=src constitue donc toute la configuration :

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

Comme avec le shim npm, un premier install sur une machine sans profil crée le profil initial à ~/.config/apothem/profile.yaml et poursuit.

Vérifiez :

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

Vérifier n'importe quelle installationCopy Anchor Link

Chaque canal ci-dessus nomme sa propre commande de vérification. Les deux formes générales sont :

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

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

Remplacez le nom de l'environnement par celui de l'adaptateur que vous avez installé ; consultez la liste des environnements pour tous les noms pris en charge. Pour contrôler d'un coup chaque adaptateur installé (sa vérification et ses commandes de hook), exécutez doctor à la place de verify --harness NAME, sous la forme que vous avez utilisée ci-dessus : apothem doctor, PYTHONPATH="$HOME/.apothem/src" python -m apothem doctor ou npx @ahmed-g-gad/apothem doctor. Pour la voie du plugin, exécutez /plugin dans Claude Code et confirmez qu'apothem figure comme installé.

Prérequis en un coup d'œilCopy Anchor Link

• Python 3.10 ou ultérieur — les voies qui le localisent le font par son nom, et les noms diffèrent selon la voie. Le shim npm essaie python3, python, puis py -3. Les installateurs essaient python3, python et les noms versionnés, en ordre décroissant de python3.14 à python3.10.
• click et rich importables sous cet interpréteur — les deux dépendances orientées terminal que le moteur ne vendorise pas. Les installateurs vérifient les deux, nomment ce qui manque et proposent de l'installer pour vous — avec votre confirmation, ou automatiquement avec --yes (-Yes sous PowerShell) ou APOTHEM_AUTO_INSTALL_DEPS=1. Sur tous les autres canaux, un paquet manquant arrête le moteur avec une erreur (code de sortie 1) qui nomme la commande exacte pour l'interpréteur trouvé, avec les contraintes de version sur lesquelles Apothem est testé (<interpreter> -m pip install "click==…" "rich>=…") ; avec --json, la même erreur arrive sous la forme d'une enveloppe JSON portant le code runtime.dependency_missing.
• Node.js 18 ou ultérieur — uniquement les voies qui exécutent npx : le shim npm (2), l'extension de la famille VS Code (4) et les amorçages en ligne de commande (5–7).
• Runtimes en fin de vie. Python 3.10 a atteint sa fin de vie en amont le 2026-10-01, et Node.js 18 et 20 respectivement le 2025-04-30 et le 2026-04-30. Apothem les prend toujours en charge en tant que planchers déclarés et teste chacun d'eux en CI, mais ils ne reçoivent plus de correctifs de sécurité en amont ; privilégiez donc Python 3.11 ou plus récent et Node.js 22 ou plus récent. La politique des planchers d'exécution explique comment un plancher est relevé.
• Git — voie de l'installateur uniquement, et seulement pour la forme réseau (le script clone le code source ; un checkout local ne nécessite aucun clonage).
• Claude Code — voie du plugin uniquement. VS Code et l'outil hôte propre à chaque amorçage en ligne de commande ne sont nécessaires que pour leur propre canal (4–7).

Guides suivantsCopy Anchor Link