Instalación

Apothem se instala en menos de dos minutos y funciona junto con la configuración de entorno que ya tienes. Cada vía ejecuta el mismo motor autónomo — el árbol de código fuente lleva sus dependencias incorporadas y se ejecuta desde un checkout sobre el Python 3.10 o posterior del sistema (consulta el tiempo de ejecución autónomo).

Todas las vías comparten dos requisitos previos: Python 3.10 o posterior del sistema en el PATH, con los paquetes click y rich importables bajo él. El shim de npm (canal 2), la extensión de la familia VS Code (canal 4) y los arranques de línea de comandos (canales 5–7) necesitan además Node.js 18 o posterior para ejecutar npx. Python 3.10 y Node.js 18 y 20 ya superaron el fin de vida en su proyecto de origen; siguen siendo admitidos y probados, pero se prefieren versiones más recientes (consulta Requisitos previos de un vistazo). La sección propia de cada canal, más abajo, repite sus requisitos previos exactos, un comando listo para copiar y un paso de verificación.

Elige un canalCopy Anchor Link

Hay ocho canales de instalación disponibles. Elige según cómo trabajas ya.

Cada vía es idempotente: volver a ejecutarla es seguro y converge al mismo estado.

1. Plugin de Claude CodeCopy Anchor Link

Requisitos previos: Claude Code y el Python 3.10+ del sistema en el PATH.

La vía del plugin se ejecuta por completo dentro de Claude Code. Empaqueta el motor de Apothem con sus comandos de barra, trabajadores delegados, skills, reglas y hooks, todos ejecutables desde el árbol autónomo del plugin:

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

Tras la instalación, el conjunto de comandos de Apothem, los trabajadores delegados incluidos, las skills y los cuatro output-styles (elige uno con /output-style o desde /config) están disponibles en cada sesión de Claude Code. El plugin distribuye cada comando como una skill, un SKILL.md con el detalle que carga bajo demanda en una carpeta references/ junto a él, así que Claude Code lo invoca con el prefijo del plugin: /apothem:plan-spec, /apothem:security-audit y el resto. Dos nombres los ocupa el propio Claude Code: /plan entra en el modo de plan y /code-review ejecuta la revisión integrada, así que escribe /apothem:plan y /apothem:code-review para los comandos de Apothem. Cuando el motor de Apothem se instala en Claude Code en lugar del plugin, las mismas skills se escriben en ~/.claude/skills/ sin prefijo, y una skill personal code-review reemplaza el /code-review integrado (su alias /review sigue ejecutando el integrado). Dos nombres, projectify y workflow, son también skills nativas; la skill nativa es la que distribuyen el plugin y la instalación del motor, no una skill derivada del comando. Consulta Claude Code para ver cómo se dividen los comandos, y Comandos de barra para ver el catálogo completo de comandos.

Verifica: ejecuta /plugin dentro de Claude Code y confirma que apothem aparece como instalado, o comprueba el informe de deriva desde una terminal:

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

2. Shim de npm (npx)Copy Anchor Link

Requisitos previos: Node.js 18+ (para npx) y el Python 3.10+ del sistema en el PATH. El shim localiza el intérprete y reenvía cada comando de la CLI al motor incluido — no se coloca nada de forma permanente en tu sistema. Prueba python3, python y después py -3, en ese orden; define APOTHEM_PYTHON con la ruta de un intérprete para probarlo primero, que es lo que necesitas cuando Python está instalado pero no está en el PATH, o cuando hay varias versiones instaladas y quieres una concreta. El intérprete que indiques sigue teniendo que superar la comprobación de Python 3.10+; cuando no la supera, el shim recurre a python3, python y después py -3.

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

En una máquina sin perfil, este primer install crea el perfil inicial en ~/.config/apothem/profile.yaml y lo indica. Sus campos de identidad son marcadores de posición: personalízalos (npx @ahmed-g-gad/apothem profile edit) y luego vuelve a ejecutar el comando con update en lugar de install para aplicarlos.

También se ejecuta directamente desde el repositorio:

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

Cada comando de la referencia de la CLI funciona en esta forma; escribe npx @ahmed-g-gad/apothem en lugar de apothem. Esta es también la vía de instalación para OpenCode y cualquier otra herramienta que no exponga un registro de plugins o extensiones propio — Apothem las sincroniza directamente en su directorio de configuración nativo (npx @ahmed-g-gad/apothem install --harness opencode).

Verifica:

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

3. Instaladores de un solo pasoCopy Anchor Link

Requisitos previos: el Python 3.10+ del sistema en el PATH (el instalador se ofrece a añadir por ti los requisitos previos click / rich); git y gpg para una instalación por red, que clona el código fuente y verifica su etiqueta de lanzamiento firmada (Git for Windows incluye ambos).

Los scripts del instalador resuelven la etiqueta de lanzamiento firmada más reciente, verifican su firma, colocan el árbol de código fuente de Apothem en ~/.apothem en esa etiqueta, crean un perfil inicial cuando no existe ninguno, materializan tu primer entorno y verifican el resultado, todo en una sola ejecución. El perfil inicial lleva campos de identidad que son marcadores de posición: edítalo y luego ejecuta apothem update --harness <name> para aplicar los tuyos. Volver a ejecutarlos es idempotente: en un árbol existente se vuelve a hacer checkout de la etiqueta resuelta y el entorno se vuelve a materializar. La instalación verificada y fijada a una etiqueta es la vía predeterminada y recomendada.

Importa primero la clave de firma del mantenedor, una sola vez. El instalador se detiene si la clave no está en tu llavero. Comprueba que la huella digital es 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163, el valor publicado en SECURITY.md. En Windows, git verify-tag lee el llavero del gpg que incluye Git for Windows, así que la importación se ejecuta mediante el propio bash de 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

Los mismos scripts se distribuyen en un checkout bajo scripts/installer/ — install, uninstall y update en las formas .sh, .ps1 y .bat —, de modo que puedes ejecutarlos directamente tras clonar:

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

Modelo de confianzaCopy Anchor Link

Sin APOTHEM_REF definido, el instalador resuelve la etiqueta de lanzamiento vMAJOR.MINOR.PATCH más alta y hace checkout de esa — nunca de la rama main en movimiento. Antes de materializar cualquier configuración, la firma de la etiqueta obtenida se verifica con git verify-tag; una etiqueta sin firmar, manipulada o no verificable aborta la instalación antes de escribir nada. Una etiqueta firmada cuya clave pública del mantenedor todavía no está en el llavero local aborta, en cambio, con indicaciones para importar la clave: importa la clave tal como se muestra arriba, comprueba su huella digital con el valor publicado en SECURITY.md, y vuelve a ejecutar. Fija un lanzamiento concreto con APOTHEM_REF:

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

Reemplaza vMAJOR.MINOR.PATCH por una etiqueta de la página de lanzamientos. La etiqueta de lanzamiento más antigua es una etiqueta ligera sin firma propia, por lo que la comprobación de la etiqueta aborta con ella aunque su commit esté firmado; todas las etiquetas de lanzamiento posteriores son anotadas y firmadas. La sección de firma de lanzamientos de SECURITY.md lista cada etiqueta y cómo verificarla.

Las anulaciones explícitas relajan el comportamiento predeterminado. APOTHEM_ALLOW_UNVERIFIED=1 degrada un fallo de verificación a una advertencia y continúa, para uso en sistemas aislados de la red o uso local, o para instalar un lanzamiento anterior a la firma de etiquetas. APOTHEM_REF=main hace checkout de la rama móvil sin verificación solo junto con APOTHEM_ALLOW_UNVERIFIED=1. Con APOTHEM_REF=main por sí solo, el instalador descarga main en APOTHEM_HOME y después aborta antes de materializar ninguna configuración, porque una rama no es una etiqueta de lanzamiento firmada. Un checkout local mediante APOTHEM_SOURCE no descarga nada y omite la verificación.

APOTHEM_VERIFY=checksum es la vía intermedia para un host que aún no tiene la clave pública del mantenedor: en lugar de clonar, el instalador descarga el archivo comprimido por plataforma del lanzamiento y su SHA256SUMS, aborta ante una discrepancia del digest antes de extraer nada y advierte de que un digest coincidente prueba que el archivo comprimido es el que lista el lanzamiento, no quién lo publicó.

Después, el motor se ejecuta directamente desde el árbol colocado. Toda dependencia de terceros, excepto click y rich, está incorporada dentro del árbol de código fuente, y el propio punto de entrada coloca ese directorio de dependencias incorporadas en sys.path:

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

Ambos scripts leen las mismas variables de entorno de configuración (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); consulta Variables de entorno del instalador para ver la tabla completa y Tiempo de ejecución autónomo para ver cómo funciona el modelo de invocación python -m.

El comando apothem. Tras una instalación correcta, el instalador escribe un shim apothem que reenvía al motor incluido — en POSIX en $HOME/.local/bin, en Windows en %LOCALAPPDATA%\Microsoft\WindowsApps (un directorio de usuario que ya está en el PATH predeterminado de Windows). El instalador nunca edita tu PATH. Una vez que el directorio está en el PATH, ejecutas apothem <command> directamente, sin PYTHONPATH manual.

Verifica:

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. Extensión de la familia VS CodeCopy Anchor Link

Requisitos previos: VS Code, Node.js 18+ y el Python 3.10+ del sistema en el PATH.

La extensión Apothem for VS Code está en Visual Studio Marketplace como ahmed-g-gad.apothem-vscode: instálala desde la vista de Extensiones o con code --install-extension ahmed-g-gad.apothem-vscode. También se instala desde un paquete apothem.vsix: code --install-extension apothem.vsix, o el comando Install from VSIX… del editor. El flujo de trabajo de lanzamiento firma el paquete y lo adjunta a cada GitHub Release. Los lanzamientos publicados antes de que el flujo de trabajo empaquetara la extensión no incluyen ningún .vsix; cuando al último lanzamiento le falta, compila el paquete desde un checkout con la versión de vsce bloqueada en tools/vsce/ (esa versión de vsce requiere Node.js 22 o posterior): ejecuta npm ci --prefix tools/vsce --ignore-scripts y luego cd vscode-extension && ../tools/vsce/node_modules/.bin/vsce package --no-dependencies --out apothem.vsix. Una copia instalada desde un apothem.vsix anterior lleva el identificador ahmed-g-gad.apothem; desinstálala (code --uninstall-extension ahmed-g-gad.apothem) para que las dos copias no registren los mismos comandos. Una sola extensión cubre los editores de la familia VS Code. Sus comandos de la paleta (Apothem: Install, Verify, Update, Uninstall, Doctor) ejecutan el mismo motor a través del ejecutor configurado (npx @ahmed-g-gad/apothem@<extension version> de forma predeterminada, de modo que la extensión ejecuta la versión del motor con la que se distribuyó; apunta la configuración de usuario apothem.runner a un checkout local para ejecutar desde el código fuente). Install, Verify, Update y Uninstall preguntan sobre qué entorno actuar y ofrecen primero el entorno del propio editor; all es una opción, nunca el valor predeterminado. La configuración apothem.runner tiene alcance de máquina, así que un espacio de trabajo no puede cambiarla, y la extensión solo se ejecuta en un espacio de trabajo de confianza.

Verifica: ejecuta el comando Apothem: Verify desde la paleta de comandos del editor, o desde una terminal:

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

5. Arranque de línea de comandos (host de extensión)Copy Anchor Link

Requisitos previos: su herramienta anfitriona de línea de comandos, Node.js 18+ y el Python 3.10+ del sistema en el PATH.

Instala Apothem como extensión directamente desde el repositorio — el comando lleva el host y el slug de entorno exactos:

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

Esta extensión es un arranque, no la instalación completa por sí sola: carga un archivo de contexto de Apothem y añade un comando /apothem que delega en el motor (npx @ahmed-g-gad/apothem). Materializa el entorno completo ejecutando la instalación a través de ella:

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

Verifica:

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

6. Arranque de línea de comandos (host qwen-code)Copy Anchor Link

Requisitos previos: su herramienta anfitriona de línea de comandos, Node.js 18+ y el Python 3.10+ del sistema en el PATH.

Instala Apothem como extensión --harness qwen-code directamente desde el repositorio:

qwen extensions install ahmed-g-gad/apothem

Como la extensión del canal 5, esta es un arranque: carga un archivo de contexto de Apothem y delega en el motor. Materializa el entorno completo ejecutando la instalación a través de ella:

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

Verifica:

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

7. Arranque de línea de comandos (host de plugin)Copy Anchor Link

Requisitos previos: su herramienta anfitriona de línea de comandos, Node.js 18+ y el Python 3.10+ del sistema en el PATH.

Añade el repositorio como marketplace de plugins y luego instala el plugin — el comando lleva el host y el slug de entorno exactos:

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

Las dos rutas --sparse obtienen solo el listado del marketplace y el plugin, no el repositorio completo; un clon completo puede superar el límite de clonado de 30 segundos del host en un disco lento, como una unidad de Windows bajo WSL.

Como las extensiones de los canales 5 y 6, este es un arranque que delega en el motor. El plugin incluye una skill de entrada; su manifiesto es un plugin.json en la raíz, y la página de entorno del host de plugin describe la estructura y lo que el plugin deja al motor. Materializa el entorno completo ejecutando la instalación a través de él:

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

Verifica:

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

8. Motor directo (python -m apothem)Copy Anchor Link

Requisitos previos: el Python 3.10+ del sistema con los paquetes click y rich importables, más un checkout del repositorio. No se requiere Node.js.

Ejecuta el motor directamente desde un clon. El punto de entrada coloca las dependencias incorporadas (src/apothem/_vendor) en sys.path, así que, con click y rich importables, PYTHONPATH=src es toda la configuración:

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

Igual que con el shim de npm, un primer install en una máquina sin perfil crea el perfil inicial en ~/.config/apothem/profile.yaml y continúa.

Verifica:

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

Verifica cualquier instalaciónCopy Anchor Link

Cada canal anterior nombra su propio comando de verificación. Las dos formas generales son:

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

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

Reemplaza el nombre del entorno por el adaptador que hayas instalado; consulta la lista de entornos para ver todos los nombres admitidos. Para comprobar a la vez cada adaptador instalado (su verificación y sus comandos de hook), ejecuta doctor en lugar de verify --harness NAME, en la forma que hayas usado arriba: apothem doctor, PYTHONPATH="$HOME/.apothem/src" python -m apothem doctor o npx @ahmed-g-gad/apothem doctor. Para la vía del plugin, ejecuta /plugin dentro de Claude Code y confirma que apothem aparece como instalado.

Requisitos previos de un vistazoCopy Anchor Link

• Python 3.10 o posterior — las vías que lo localizan lo hacen por nombre, y los nombres difieren según la vía. El shim de npm prueba python3, python y después py -3. Los instaladores prueban python3, python y los nombres con versión desde python3.14 hasta python3.10.
• click y rich importables bajo ese intérprete — las dos dependencias orientadas a la terminal que el motor no incorpora. Los instaladores comprueban ambas, nombran lo que falte y se ofrecen a instalarlo por ti — con tu confirmación, o automáticamente con --yes (-Yes en PowerShell) o APOTHEM_AUTO_INSTALL_DEPS=1. En cualquier otro canal, un paquete que falte detiene el motor con un error (código de salida 1) que nombra el comando exacto para el intérprete que encontró, con las restricciones de versión con las que se prueba Apothem (<interpreter> -m pip install "click==…" "rich>=…"); con --json, el mismo error llega como un sobre JSON con el código runtime.dependency_missing.
• Node.js 18 o posterior — solo las vías que ejecutan npx: el shim de npm (2), la extensión de la familia VS Code (4) y los arranques de línea de comandos (5–7).
• Tiempos de ejecución en fin de vida. Python 3.10 alcanzó el fin de vida en su proyecto de origen el 2026-10-01, y Node.js 18 y 20, el 2025-04-30 y el 2026-04-30. Apothem todavía los admite como sus versiones mínimas declaradas y prueba cada uno en CI, pero ya no reciben correcciones de seguridad de su proyecto de origen, así que prefiere Python 3.11 o posterior y Node.js 22 o posterior. La política de versiones mínimas de tiempo de ejecución explica cómo se eleva una versión mínima.
• Git — solo la vía del instalador, y solo para la forma por red (el script clona el código fuente; un checkout local no necesita clonar).
• Claude Code — solo la vía del plugin. VS Code y la herramienta anfitriona propia de cada arranque de línea de comandos solo se necesitan para su propio canal (4–7).

Próximas guíasCopy Anchor Link