Inicio Rápido (Quickstart)

Esta guía te conducirá paso a paso para compilar, instalar y ejecutar tu primera sesión de desarrollo con gz-ia en menos de 5 minutos.

---

1. Prerrequisitos

Antes de comenzar, asegúrate de contar con las siguientes herramientas en tu entorno:

• Sistema Operativo: Linux o macOS (soporte POSIX estándar).
• Git: Versión 2.20+ con soporte de git worktree.
• Go: 1.23.1+ (para compilar desde el código fuente).
• Al menos un agente de terminal soportado:
  • Google Antigravity (agy)
  • Anthropic Claude Code (claude)
  • OpenCode (opencode)
  • Pi Agent (pi-agent)

Verificación de Agentes

Si aún no tienes ningún agente instalado, consulta la sección Agentes Soportados para ver las instrucciones y atajos oficiales de instalación.

---

2. Instalación y Compilación

Opción A: Compilar desde el código fuente con Make

Clona el repositorio e invoca el target de compilación:

git clone https://git.pipis.app/tomasjs/gz-ia.git
cd gz-ia

# Compila el binario con metadatos de versión y commit
make build

# Verifica el ejecutable generado en ./bin/gz-ia
./bin/gz-ia version

Para instalarlo de forma global en tu $PATH del sistema:

sudo install -m 755 ./bin/gz-ia /usr/local/bin/gz-ia

Opción B: Actualización automática mediante Nexus

Si ya cuentas con una versión previa de gz-ia, puedes actualizar a la versión más reciente en un solo paso:

gz-ia update --check
gz-ia update --force

---

3. Comprobación de Estado

Comprueba que el binario responda adecuadamente con su información de versión:

$ gz-ia version
gz-ia version 0.0.1 (commit: a1b2c3d, built at: 2026-09-24T20:00:00Z)

---

4. Lanzar tu Primer Chat con un Agente

Para iniciar una sesión directa conectada al agente de IA predeterminado en modo supervisado:

# Iniciar sesión interactiva directa (detecta el primer agente disponible)
gz-ia chat

Especificar Motor y Nivel de Permiso

Puedes seleccionar explícitamente el agente y los privilegios de ejecución:

# Ejecutar Google Antigravity en modo supervisado (confirmación paso a paso)
gz-ia chat --provider agy --perm supervised

# Ejecutar Claude Code en modo autónomo dentro del Worktree aislado
gz-ia chat --provider claude --perm autonomous -i "Crea una función en utils/date.go que formatee fechas ISO"

¿Qué ocurre entre bastidores?

1. gz-ia genera un ID criptográfico único para la sesión (ej. 3f9a12c8).
2. Crea un Git Worktree efímero en .harness/worktrees/3f9a12c8 sobre una nueva rama harness/3f9a12c8.
3. Inicia el agente dentro del worktree, protegiendo tu rama principal de cualquier error.

---

5. Inspeccionar y Traer Cambios

Cuando el agente complete su trabajo dentro del worktree, puedes auditar lo realizado sin salir de tu terminal:

# 1. Listar todas las sesiones registradas
gz-ia session list

# 2. Ver las diferencias producidas por el agente en la sesión
gz-ia session diff 3f9a12c8

# 3. Inspeccionar el resumen estadístico de archivos modificados
gz-ia session read 3f9a12c8 --stat

# 4. Traer e integrar las modificaciones a tu directorio de trabajo actual
gz-ia session get 3f9a12c8

---

6. Probar la Interfaz Visual Interactiva (TUI)

Si prefieres una experiencia visual guiada con teclado:

gz-ia start
# o simplemente
gz-ia

La TUI te mostrará el banner del sistema estilo Fastfetch, el estado de cada agente instalado y menús desplegables para iniciar chats o reanudar sesiones anteriores.