Guía rápida

Este es el camino rápido desde cero hasta una configuración de entorno verificada: instalar, redactar el perfil compartido, materializar la configuración nativa de una herramienta, confirmarla y hacer tu primera edición. Cada comando es real y se puede copiar, pegar y ejecutar, y cada paso muestra lo que imprime una ejecución limpia. La instalación en sí termina en menos de dos minutos; editar el perfil es la única parte que lleva tanto tiempo como quieras dedicarle.

Al final tendrás una configuración de entorno funcional generada a partir de un perfil que escribiste tú — y conocerás el único comando que vuelve a enviar un cambio del perfil a una herramienta o a todas.

Usarás Claude Code como entorno de ejemplo — es el predeterminado del instalador. Cambia el nombre del adaptador en cualquier paso para apuntar a otra herramienta; la lista de entornos tiene todos los nombres admitidos.

1. Instalar ApothemCopy Anchor Link

Apothem se distribuye como un tiempo de ejecución autónomo: el motor se ejecuta directamente desde su árbol de código fuente con dependencias incorporadas. Un solo comando descarga el código fuente, coloca el motor y materializa tu primer entorno. Verifica primero el lanzamiento firmado, así que importa la clave de firma del mantenedor una sola vez antes de la primera instalación y comprueba que la huella digital es 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163:

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'

Después, ejecuta el instalador:

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

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

El instalador requiere un Python 3.10+ del sistema, además de git y gpg para la forma por red. Comprueba los requisitos previos y coloca el motor en ~/.apothem. Cuando falta click o rich, instala el paquete con tu confirmación o cuando se pasa --yes (-Yes en PowerShell) o se define APOTHEM_AUTO_INSTALL_DEPS=1, y en caso contrario se detiene con el comando de pip que hay que ejecutar (consulta Requisitos previos de un vistazo). Al terminar imprime un banner de próximos pasos; en POSIX, cuando el directorio del shim ya está en PATH, el banner tiene este aspecto:

Installation complete.

The 'apothem' command is on your PATH.

Recommended first step — the guided setup (profile -> preview -> install):

  apothem quickstart

La guía de instalación cubre las demás vías de instalación — el plugin de Claude Code (/plugin marketplace add ahmed-g-gad/apothem y después /plugin install apothem@apothem); las extensiones de la familia VS Code y otras extensiones nativas de cada herramienta; y la forma bajo demanda con npx (npx @ahmed-g-gad/apothem <command>) — junto con las opciones de variables de entorno.

2. Crear el perfil compartidoCopy Anchor Link

apothem profile init escribe el perfil más pequeño válido según el esquema en ~/.config/apothem/profile.yaml. Si ya hay un perfil allí, como cuando el instalador del Paso 1 copió el ejemplo, init se detiene con un error y deja el archivo sin cambios; pasa --force para sobrescribirlo, o conserva el archivo y edítalo como se muestra más abajo. Pasa --profile PATH cuando mantengas en otra ubicación un perfil específico de un proyecto o de CI.

apothem profile init
apothem profile show --json

El esqueleto usa datos de identidad ficticios como marcadores de posición y es seguro editarlo antes de instalar cualquier salida de entorno. show --json lo vuelve a leer e informa del perfil validado con todos los valores predeterminados rellenados, empezando por schema_version. El comando lo imprime en una sola línea; aquí se muestra expandido:

{
  "schema_version": 1,
  "identity": {
    "name": "Example User",
    "role": "senior software engineer",
    "email": "[email protected]",
    "github": "example-user"
  },
  "preferences": {
    "language": "python",
    "style": "concise"
  },
  "rules": [],
  "seriousness": "PERSONAL_USE",
  "enforcement": {
    "sprints": false,
    "agent_teams": false,
    "multitasking": false,
    "continuous_execution": false,
    "learning_loop": false
  },
  "mcp_servers": {},
  "agent_mcp_servers": {},
  "harnesses": {},
  "exclude_harnesses": [],
  "workspace": {
    "directory_name": ".apothem",
    "scope": "project-local"
  }
}

Aquí es también donde aflora una edición malformada: si el YAML no es válido, show lo informa en este punto, antes de que se escriba cualquier configuración de entorno. Haz tuyo el perfil con apothem profile edit (lo abre en tu editor) o establece una sola clave in situ:

apothem profile set identity.name "Your Name"

3. Instalar adaptadores de entornoCopy Anchor Link

Materializa el adaptador de tu entorno principal. Esto lee tu perfil y escribe la configuración nativa de esa herramienta:

apothem install --harness claude-code

✓ Installed claude-code -> /home/you/.claude/settings.json

Los adaptadores de ámbito de proyecto escriben su archivo de reglas dentro de un proyecto, por lo que necesitan un --project PATH; siete de ellos también escriben skills y reglas compartidas en carpetas de tu directorio personal, y --project no cambia adónde van. Previsualiza cualquier instalación sin escribir archivos con --dry-run:

apothem install --harness cursor --project . --dry-run
apothem install --harness cursor --project .

Instala de una vez todo el conjunto respaldado por el registro con --harness all. Como esa selección escribe archivos tanto de ámbito de proyecto como de ámbito de usuario, el comando imprime los destinos concretos agrupados por ubicación. En una terminal interactiva, pide confirmación antes de escribir fuera de la raíz del proyecto. Una ejecución sin terminal, una ejecución con --yes o una ejecución con --format json escribe sin preguntar; --dry-run no escribe nada. Ejecuta el conjunto completo con:

apothem install --harness all --project .

Consulta la lista completa de entornos para ver todos los nombres admitidos, y la referencia de install para el conjunto completo de opciones.

4. VerificarCopy Anchor Link

Materializar es solo la mitad del trabajo — verify confirma que los archivos de configuración esperados del entorno se escribieron y son válidos:

apothem verify --harness claude-code

✓ claude-code is verified at /home/you/.claude/settings.json

verify termina con un código distinto de cero si falta un destino gestionado, si un archivo gestionado está vacío o si una configuración JSON o YAML no se analiza. Añade --profile PATH para que también falle cuando un archivo instalado difiera de ese perfil, lo que convierte a verify en una comprobación de deriva; sin él, una configuración obsoleta sigue superando la verificación. El código de salida distinto de cero permite que verify sirva de puerta en un script de configuración. Para una comprobación del estado de toda la máquina en todos los adaptadores registrados, ejecuta:

apothem doctor

doctor comprueba cada entorno instalado: debe superar la verificación, y cada comando de hook que registró su instalación debe arrancar. Un entorno que no has instalado aparece en la lista, pero no cuenta como fallo, por lo que doctor termina con 0 cuando ninguna comprobación falla, aunque solo haya un entorno instalado.

5. Tu primera ejecuciónCopy Anchor Link

Abre el entorno que acabas de configurar — Claude Code, en este ejemplo — e inicia una sesión en cualquier proyecto. El perfil que configuraste en el Paso 2 ya forma parte del comportamiento de esa herramienta. Esa es la primera ejecución funcional: un perfil que da forma a una sesión real.

Cuando cambies el perfil más adelante, vuelve a aplicarlo sin reinstalar:

apothem update --harness claude-code

Indica otro adaptador para volver a aplicar el perfil a esa herramienta (añade --project PATH para un adaptador de ámbito de proyecto), o pasa --harness all --project . para volver a aplicarlo a todos los entornos admitidos.

Próximos pasosCopy Anchor Link

• Añadir más entornos — repite el Paso 3 para cada herramienta.
• Escribir tu primera regla — la unidad que hereda cada entorno.
• Redactar un plan — conduce una misión completa a través de la canalización de planes determinista.
• Referencia de la CLI — cada comando, opción y código de salida.