Guía de inicio de Andromeda

Tu compañero de terminal para enviar buen software. Andromeda es un arnés de ingeniería con IA local-first y agnóstico del proveedor: una CLI y una TUI interactiva que ejecutan agentes de código sobre tu workspace.

Instalación

Elige el método para tu sistema. Después verifica con andromeda doctor.

brew install datamaia/tap/andromeda

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

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

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

Primeros pasos

Lanza la TUI interactiva ejecutando andromeda sin argumentos. La primera ejecución te guía para elegir proveedor e iniciar sesión.

andromeda                                    # TUI interactiva
andromeda run "añade un endpoint health-check" \
  --provider openai-chatgpt --allow-write      # tarea one-shot

Las capacidades son opt-in por ejecución: --allow-write, --allow-exec, --allow-network. Sin ellas, el agente es de solo lectura.

Proveedores

Andromeda habla con un proveedor a la vez, seleccionado con --provider o por el default de andromeda.toml. Cada uno se autentica de forma distinta.

Listar lo disponible

andromeda provider list     # proveedores soportados
andromeda model list        # modelos del proveedor configurado

Autenticación

Inicia sesión una vez; las credenciales quedan en el llavero del SO (Keychain / Secret Service / Windows Credential Manager). Después valida la conexión antes de lanzar un agente.

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)
andromeda provider check              # valida la conectividad

El 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.

La clave: 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 sin cambiar tu forma de trabajar.

Trabajar con agentes

No hay "archivos de agente" que mantener: cada ejecución instancia un agente definido por cuatro ejes — objetivo, proveedor/modelo, permisos y contexto (AGENTS.md + memoria). Combinarlos te da agentes distintos para tareas distintas.

Caso 1 — Explorar o auditar (solo lectura)

Sin flags de permiso el agente no toca nada: ideal para entender un repo o preparar un plan sin riesgo.

andromeda run "explica la arquitectura de internal/ y sus dependencias"
andromeda ontology build     # mapas del repo: estructura (project.ttl) + grafo de código AST (code.ttl)
andromeda graph open         # visor 3D offline del workspace (se abre desde el filesystem, sin servidor)

Caso 2 — Implementar una feature

Añade capacidades solo cuando la tarea las necesita.

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

Caso 3 — Varios agentes para una misma tarea

Como el proveedor se elige por ejecución, encadena agentes especializados sobre el mismo workspace: uno local para explorar, uno potente para implementar, uno de otro vendor para revisar.

# 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 del módulo de pagos" \
  --provider anthropic --allow-write --allow-exec

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

Comparten contexto por el propio repo, AGENTS.md y la memoria: usa andromeda memory add "…" para dejar notas que cualquier agente posterior leerá.

Caso 4 — Trabajo largo (TUI + sesiones)

andromeda              # sesión interactiva
andromeda --continue   # retomar la última sesión
andromeda sessions list && andromeda --resume <id>

Configuración

Ejecuta /init en la TUI para generar andromeda.toml, AGENTS.md y los directorios .agents/. Es TOML plano en capas: global → workspace → proyecto → env → flags.

[provider]
default = "openai-chatgpt"

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

Referencia de comandos

Solución de problemas

• andromeda doctor revisa tu entorno y señala problemas comunes.
• andromeda provider check valida la conectividad con tu proveedor.
• Si anthropic falla al autenticar, confirma que tienes una API key (no solo la suscripción de Claude).
• Homebrew rechaza el tap: ejecuta brew trust datamaia/tap una vez y reintenta.
• Windows / Microsoft Defender: si Defender bloquea andromeda.exe (SmartScreen «editor desconocido» o la regla ASR «Usar protección avanzada contra ransomware»), es un falso positivo: el binario aún no está firmado y, como agente, escribe muchos archivos en tu workspace. En un equipo propio, permítelo con Add-MpPreference -ControlledFolderAccessAllowedApplications "$env:LOCALAPPDATA\Programs\andromeda\andromeda.exe"; en un equipo gestionado, pide a IT una exclusión ASR — plantilla lista en el README.