Primeros pasos: de cero a un entorno funcional

Este tutorial te guía de principio a fin por tu primera configuración de Apothem. Empiezas sin nada instalado y terminas con una configuración de entorno real: generada a partir de un perfil que escribiste tú, verificada y confirmada como funcional. Calcula unos quince minutos. Cada comando de abajo es real y se puede copiar, pegar y ejecutar.

Al final habrás:

1. Instalado Apothem desde el instalador por script.
2. Editado el perfil compartido que dirige cada entorno.
3. Materializado la configuración nativa de un entorno.
4. Verificado esa configuración y confirmado una primera ejecución funcional.

Usaremos Claude Code como entorno de ejemplo a lo largo de todo el tutorial, porque es el predeterminado del instalador. Los mismos pasos se aplican a cualquier entorno admitido: cambia el nombre cuando llegues a la lista de entornos.

Lo que necesitas primeroCopy Anchor Link

• Una shell tipo Unix (macOS, Linux o WSL). El instalador de PowerShell cubre Windows; este tutorial muestra la ruta de bash.
• Python 3.10 o posterior en tu PATH. Compruébalo con python3 --version.
• Las dos bibliotecas de tiempo de ejecución que el motor importa de tu intérprete: click y rich. El resto de la pila (pyyaml, jsonschema) va incluido en el árbol, así que solo estas dos deben poder importarse. Si falta click o rich, el instalador se detiene e imprime el comando de instalación. El comando de una sola línea envía el script por una tubería a bash, así que no puede preguntar; define APOTHEM_AUTO_INSTALL_DEPS=1 (por ejemplo, curl -fsSL https://apothem.ahmedgad.com/install.sh | APOTHEM_AUTO_INSTALL_DEPS=1 bash) o instala primero los dos paquetes.

Apothem se distribuye como un árbol de código fuente empaquetado en lugar de como un paquete publicado: no hay ningún paso pip install. El instalador clona el árbol y ejecuta el motor directamente desde él.

Paso 1 — Instalar ApothemCopy Anchor Link

Ejecuta el instalador de red:

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

El instalador realiza estos pasos:

1. Comprobación de requisitos previos. El instalador localiza un intérprete real de Python 3.10+ y confirma que las dos bibliotecas de tiempo de ejecución (click y rich) se pueden importar. Si falta una, la nombra, se detiene e imprime el comando de instalación. Define APOTHEM_AUTO_INSTALL_DEPS=1 para instalar sin preguntar, ya que una ejecución por tubería no puede preguntar.
2. Colocación del código fuente. El árbol empaquetado se clona en ~/.apothem (puedes cambiarlo con la variable de entorno APOTHEM_HOME). Una nueva ejecución extrae la etiqueta de lanzamiento en el clon existente en lugar de duplicarlo.
3. Inicialización del perfil. Si todavía no tienes un perfil, el instalador copia el perfil de ejemplo en ~/.config/apothem/profile.yaml, instala y verifica Claude Code a partir de él en la misma ejecución, y advierte de que los campos de identidad son marcadores de posición.

Puedes dirigir la instalación con variables de entorno. Las que es más probable que uses:

# Install a different user-scope harness and name the profile path explicitly.
# Put the variables on the `bash` side of the pipe: a variable placed before
# `curl` reaches only curl, not the installer.
curl -fsSL https://apothem.ahmedgad.com/install.sh | \
  APOTHEM_HARNESS=codex \
  APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  bash

El instalador instala solo entornos de ámbito de usuario. Instala después un entorno de ámbito de proyecto, indicando el proyecto:

apothem install --harness cursor --project /path/to/project

Otras variables reconocidas son APOTHEM_REPO y APOTHEM_REF (qué remoto clonar y qué ref de git extraer: sin definir, resuelve y verifica la etiqueta de lanzamiento firmada más reciente; define una etiqueta para fijarla, o main para la rama móvil, que no es una etiqueta firmada y por eso también necesita APOTHEM_ALLOW_UNVERIFIED=1), APOTHEM_ALLOW_UNVERIFIED=1 (degrada un fallo de verificación de la firma de la etiqueta a una advertencia y permite una ref que no es etiqueta, como main), APOTHEM_SOURCE (usa un checkout local existente en lugar de clonar) y APOTHEM_SKIP_VERIFY=1 (omite la verificación posterior a la instalación, que queremos ejecutar, así que déjala sin definir).

Cuando el instalador termina una ejecución completa, imprime un banner que muestra cómo invocar el motor. Coloca un shim apothem en tu PATH (POSIX: $HOME/.local/bin; Windows: %LOCALAPPDATA%\Microsoft\WindowsApps), de modo que, una vez que ese directorio esté en el PATH, ejecutas el motor directamente:

apothem <command>

Si no se pudo colocar el shim —o su directorio aún no está en el PATH—, el banner imprime una alternativa autocontenida que no necesita ningún shim:

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

El resto de este tutorial escribe apothem <command>; si usas la forma alternativa, antepón el prefijo exacto que imprimió el banner de tu instalador.

Paso 2 — Haz tuyo el perfilCopy Anchor Link

El perfil compartido en ~/.config/apothem/profile.yaml es la única fuente de verdad. Cada adaptador de entorno lo lee y deriva de él la configuración nativa de ese entorno. Edítalo una vez y cada entorno que instales se mantiene coherente.

Ábrelo en el editor del motor, o en cualquier editor de texto:

apothem profile edit

Un perfil mínimo y válido tiene este aspecto:

identity:
  name: "Example User"
preferences:
  style: "concise"
rules:
  - "Validate external input before writing files."

Sustituye el name de marcador de posición por el tuyo y añade las reglas que quieras que aplique cada entorno. Mantén ficticios los valores de ejemplo: el perfil está pensado para poder compartirse de forma segura.

Confirma que el motor vuelve a leer tus ediciones sin problemas:

apothem profile show --json

Si el YAML está malformado, aquí es donde lo verás: corrígelo y vuelve a ejecutar antes de continuar.

Paso 3 — Materializar una configuración de entornoCopy Anchor Link

Si tu ejecución del Paso 1 creó el perfil, ya instaló Claude Code con la identidad de marcador de posición. Edita el perfil en el Paso 2 y aplica después tu identidad con:

apothem update --harness claude-code

apothem install --harness claude-code

Esto lee tu perfil y escribe la configuración nativa de Claude Code. Para ver todos los entornos a los que puedes apuntar:

apothem harnesses list

Algunos entornos son de ámbito de proyecto en lugar de ámbito de usuario, y esos necesitan una ruta --project para que el adaptador sepa dónde escribir:

apothem install --harness cursor --project .

Paso 4 — Verificar y confirmar una primera ejecuciónCopy Anchor Link

Materializar es solo la mitad de la historia. Ahora confirma que la configuración se escribió correctamente:

apothem verify --harness claude-code

verify comprueba que los archivos de configuración gestionados del entorno existen y se pueden analizar. Añade --profile PATH y también falla cuando un archivo instalado se ha desviado de lo que produciría ese perfil. Una ejecución limpia significa que la materialización tuvo éxito.

Para una comprobación de salud de toda la máquina en todos los adaptadores registrados, ejecuta:

apothem doctor

doctor comprueba cada entorno instalado (debe superar la verificación, y sus comandos de hook registrados deben arrancar) y sale con un código distinto de cero si falla alguna comprobación. Los entornos que no has instalado aparecen en la lista, pero no lo hacen fallar, por lo que es una puerta útil en un script de configuración.

Tu primera ejecución. Abre el entorno que acabas de configurar —Claude Code, en nuestro ejemplo— e inicia una sesión en cualquier proyecto. Las reglas y preferencias que escribiste en el perfil ya forman parte del comportamiento de esa herramienta. Esa es la primera ejecución funcional: el perfil que editaste en el Paso 2 está dando forma a una sesión real.

Lo que construisteCopy Anchor Link

Partiendo de una máquina vacía, instalaste Apothem, redactaste un perfil compartido, materializaste a partir de él la configuración nativa de un entorno, verificaste el resultado y confirmaste que funciona. El perfil es el artefacto duradero: cámbialo una vez y vuelve a ejecutar apothem update --harness <name> para llevar el cambio a cualquier entorno.

Hacia dónde seguirCopy Anchor Link

• Añade otra herramienta. La lista de entornos cubre cada plataforma admitida y su nombre de adaptador. Repite el Paso 3 con un nuevo --harness.
• Profundiza en una sola tarea. Las recetas prácticas cubren cómo añadir un entorno, editar el perfil y dirigir el instalador. Las guías de uso cubren cómo escribir reglas, redactar planes y ejecutar la puerta de conformidad.
• Consulta los detalles. La referencia documenta cada clase de artefacto y el esquema del perfil, y la referencia de la CLI cubre cada comando. Cada adaptador tiene su propia página en entornos.
• Planifica trabajo que sobrevive a una sesión. Planificación reanudable explica cómo Apothem externaliza el trabajo de larga duración a una suite .apothem/plans/ local del proyecto, de modo que una sesión nueva en cualquier máquina lo reanuda en su sitio.

Próximo paso recomendadoCopy Anchor Link

Ejecuta apothem doctor para comprobar tu configuración —informa del estado de cada adaptador registrado, de modo que el entorno que acabas de instalar aparece en buen estado mientras el resto aparece como aún no instalado— antes de pasar a añadir más entornos.