Andromeda CLI — Guía de inicio

Cómo instalar, configurar y ejecutar tu primer agente con Andromeda.

1. ¿Qué es Andromeda?

Andromeda es un arnés de ingeniería con IA de código abierto: una CLI y una TUI interactiva que ejecutan agentes de código sobre tu espacio de trabajo. Tres principios lo definen:

• Local-first y privado — sin nube propia ni telemetría. Las credenciales viven en el llavero del sistema operativo (Keychain, Secret Service o Windows Credential Manager) y nunca salen de tu máquina.
• Agnóstico del proveedor — una sola interfaz sobre Anthropic, OpenAI (API key o suscripción ChatGPT), Gemini, xAI, Groq, Cerebras, OpenRouter, Hugging Face y modelos locales (Ollama, vLLM). Cambias de proveedor con un flag.
• Seguro por defecto — toda acción con efectos (escribir, ejecutar comandos, red, mutaciones de git) es de solo lectura hasta que la apruebes.

Cómo funciona como harness de ingeniería

Un "harness" es el arnés que rodea al modelo: Andromeda no es el modelo, sino el sistema que lo conecta con tu repositorio de forma controlada. En cada ejecución arma un bucle de trabajo sobre tu workspace:

1. Contexto — reúne el objetivo, el contenido relevante del repo, tu AGENTS.md y la memoria del workspace, y lo entrega al modelo del proveedor que elijas.
2. Herramientas — expone acciones (leer, escribir, ejecutar comandos, red, git) que el modelo puede invocar, pero cada una pasa por la capa de permisos antes de ejecutarse.
3. Aprobación — toda acción con efectos se detiene para que la apruebes, salvo las pre-autorizadas en [permission] allow. Nada muta tu código sin tu visto bueno.
4. Iteración — el modelo observa el resultado (salida de tests, errores, diffs) y repite el ciclo hasta cumplir el objetivo, todo dentro de una sesión persistente.

La clave es que el modelo es intercambiable: el harness, los permisos y el contexto son siempre los mismos, elijas el proveedor que elijas. Por eso puedes mezclar modelos en una misma tarea (ver §5) sin cambiar tu forma de trabajar.

2. Instalación

macOS (recomendado)

brew install datamaia/tap/andromeda

Homebrew verifica el checksum y enlaza andromeda en tu PATH. Actualiza con brew upgrade andromeda. Si Homebrew rechaza el tap por no ser de confianza, ejecuta una vez brew trust datamaia/tap y reintenta.

Linux / macOS (script)

curl -fsSL https://andromedacli.com/install | bash

Detecta tu SO y arquitectura, descarga el binario e instala en /usr/local/bin (o ~/.local/bin). Personaliza con las variables ANDROMEDA_VERSION y ANDROMEDA_INSTALL_DIR.

Windows (PowerShell)

irm https://andromedacli.com/install.ps1 | iex

Descarga el archivo de la release, verifica su SHA256, instala andromeda.exe en %LOCALAPPDATA%\Programs\andromeda y lo añade a tu PATH.

Con Go (1.25+)

go install github.com/datamaia/andromeda/cmd/andromeda@latest

También hay binarios precompilados y checksums en la página de releases.

Verifica la instalación:

andromeda version
andromeda doctor   # diagnostica tu entorno

3. Primeros pasos

Lanza la TUI interactiva ejecutando andromeda sin argumentos:

andromeda

La primera ejecución te guía para elegir proveedor e iniciar sesión. La TUI incluye comandos slash, menciones de archivos con @, un flujo de planificar/aprobar e historial desplazable con el ratón.

Autenticación

Inicia sesión una sola vez; las credenciales quedan en el llavero del sistema:

andromeda auth login openai-chatgpt   # OAuth por navegador (cuenta ChatGPT)
andromeda auth add anthropic          # guarda una API key desde una variable de entorno
andromeda provider check              # valida la conectividad

Proveedores disponibles

Andromeda habla con un proveedor a la vez, seleccionado con --provider o por el default de andromeda.toml. Lista los soportados con andromeda provider list y los modelos de cada uno con andromeda model list. Cada uno tiene su propia forma de autenticarse:

andromeda auth login openai-chatgpt   # suscripción ChatGPT → OAuth
andromeda auth add openai             # API key de la plataforma OpenAI
andromeda auth add anthropic          # API key de Anthropic (no la suscripción)

Tras autenticarte, andromeda provider check confirma que la conexión funciona antes de lanzar un agente.

Tu primera tarea one-shot

También puedes ejecutar un agente directamente desde la línea de comandos:

andromeda run "add a health-check endpoint" --provider openai-chatgpt --allow-write

Sesiones persistentes

Las conversaciones se recuerdan entre turnos y se pueden retomar:

andromeda --continue        # reabre la sesión más reciente
andromeda --resume <id>     # retoma una sesión guardada
andromeda sessions list     # lista las sesiones guardadas

4. Configuración del proyecto

Ejecuta /init en la TUI para generar andromeda.toml, AGENTS.md y los directorios de capacidades .agents/. La configuración es TOML plano y se aplica en capas: global → workspace → proyecto → variables de entorno → flags.

[provider]
default = "openai-chatgpt"

# Comandos que el agente puede ejecutar SIN pedir aprobación,
# emparejados por prefijo de argv. Lo no listado sigue preguntando;
# lo que esté en `deny` se rechaza siempre.
[permission]
allow = ["git status", "git diff", "go build ./...", "go test ./..."]
deny  = ["git push --force", "rm -rf"]

Las indicaciones de proyecto escritas en AGENTS.md se incorporan al contexto del agente en cada ejecución.

5. Casos de uso: trabajar con agentes

En Andromeda no hay "archivos de agente" que mantener: cada ejecución instancia un agente definido por cuatro cosas — el objetivo (run <goal> o el prompt en la TUI), el proveedor/modelo (--provider o el default de andromeda.toml), los permisos (--allow-*) y el contexto del proyecto (AGENTS.md + memoria del workspace). Combinar estos cuatro ejes te da agentes distintos para tareas distintas.

Caso 1 — Explorar o auditar código (solo lectura)

Sin flags de permiso el agente no puede tocar nada: ideal para entender un repo nuevo, revisar un módulo o preparar un plan sin riesgo.

andromeda run "explica la arquitectura de internal/ y sus dependencias"
andromeda run "audita el manejo de errores en el paquete auth"

Complemento útil: andromeda ontology build genera un mapa estructural del repo y andromeda graph serve lo abre como grafo interactivo en localhost.

Caso 2 — Implementar una feature (escritura + ejecución)

Añade capacidades solo cuando la tarea las necesita: --allow-write para editar archivos, --allow-exec para que compile y corra tests, --allow-network solo si debe descargar dependencias.

andromeda run "añade un endpoint health-check con tests" \
  --allow-write --allow-exec

Las acciones no cubiertas por el allowlist de [permission] siguen pidiendo aprobación interactiva una a una.

Caso 3 — Varios agentes para una misma tarea

Como el proveedor se elige por ejecución, puedes encadenar agentes especializados sobre el mismo workspace: uno barato/local para explorar, uno potente para implementar y un tercero de otro vendor para revisar con "ojos frescos".

# 1. Explorar con un modelo local (gratis, privado, solo lectura)
andromeda run "resume el módulo de pagos y propón un plan" --provider ollama

# 2. Implementar con un modelo potente
andromeda run "ejecuta el plan propuesto para el módulo de pagos" \
  --provider anthropic --allow-write --allow-exec

# 3. Revisar con un proveedor distinto, de nuevo en solo lectura
andromeda run "revisa el diff actual y señala riesgos" --provider openai-chatgpt

Los tres pasos comparten contexto a través del propio repo, de AGENTS.md y de la memoria del workspace: usa andromeda memory add "el plan acordado es X" para dejar notas que cualquier agente posterior leerá.

Caso 4 — Trabajo largo e iterativo (TUI + sesiones)

Para refactors o features de varios días, trabaja en la TUI: menciona archivos con @, usa el flujo planificar/aprobar y retoma donde lo dejaste.

andromeda              # sesión interactiva
andromeda --continue   # retomar la última sesión al día siguiente
andromeda sessions list && andromeda --resume <id>

6. Referencia de comandos

7. Solución de problemas y recursos

• andromeda doctor revisa tu entorno y señala problemas comunes.
• andromeda provider check valida la conectividad con tu proveedor.
• Repositorio y releases: github.com/datamaia/andromeda
• Sitio web: andromedacli.com
• Licencia: Apache 2.0. Contribuciones bienvenidas — consulta CONTRIBUTING.md en el repo.