Inicio Rápido (Quickstart)

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

---

1. Prerrequisitos y Plataformas

• Plataformas Soportadas:
  • Linux nativo: Distribuciones modernas con kernel Linux 4.x+ (Ubuntu, Debian, Fedora, Arch).
  • Windows bajo WSL2: En sistemas Windows corporativos, se recomienda ejecutar bajo WSL2 (Windows Subsystem for Linux 2) para compatibilidad con el sistema de archivos de Git y señales POSIX.
• Git: Versión 2.20+ con soporte de git worktree.
• Al menos un agente de terminal instalado:
  • Google Antigravity (agy)
  • Anthropic Claude Code (claude)
  • OpenCode (opencode)
  • Pi Agent (pi-agent)

---

2. Instalación

Opción 1: Descarga directa binaria desde Nexus (Recomendada)

No requiere tener instalado Go ni Node en tu máquina. Descarga e instala el binario compilado para Linux x86_64:

curl -fsSL https://nexus.pipis.app/repository/raw-releases/gz-ia/latest/gz-ia-linux-amd64.tar.gz | tar -xz
sudo install -m 755 gz-ia /usr/local/bin/

Opción 2: Compilación desde fuentes (Para desarrolladores)

Requiere Go 1.23.1+ instalado:

git clone https://git.pipis.app/tomasjs/gz-ia.git
cd gz-ia
make build
sudo cp bin/gz-ia /usr/local/bin/

Actualización de instalaciones existentes

Una vez que dispones de gz-ia instalado, puedes verificar y aplicar nuevas versiones directamente con el comando de auto-actualización:

# Comprobar si hay versiones más recientes en Nexus / Forgejo
gz-ia update --check

# Descargar e instalar la actualización in-place
gz-ia update

---

3. Comprobación de Instalación

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

$ gz-ia version
✦ gz-ia v0.0.1 (commit: a1b2c3d, date: 2026-09-24T20:00:00Z)

---

4. Lanzar una Sesión de Chat

Para iniciar una sesión interactiva directa conectada al primer motor de IA detectado:

# Detecta el primer agente disponible en PATH
gz-ia chat

Especificar Motor, Nivel de Permiso y Objetivo

# Ejecutar Google Antigravity en modo supervisado con un prompt inicial
gz-ia chat -p agy -m supervised -i "Añadir validación de email con pruebas unitarias"

Salida en terminal:

🚀 Iniciando chat con Google Antigravity (Permiso: supervised | Workspace: Worktree desacoplado (.harness/worktrees/7e2a9b1c))...

Mecanismo interno:

1. gz-ia genera un identificador aleatorio de sesión (ej. 7e2a9b1c).
2. Crea un Git Worktree efímero en .harness/worktrees/7e2a9b1c sobre una rama dedicada harness/7e2a9b1c.
3. El agente opera dentro de ese worktree; tus archivos abiertos en el editor permanecen inalterados.

---

5. Inspeccionar y Traer Cambios

Cuando el agente complete su trabajo, puedes auditar las modificaciones antes de integrarlas:

1. Listar las sesiones

$ gz-ia session list
ID          ESTADO        PID       PERMISO       MODO        INICIO                DURACIÓN  
──────────────────────────────────────────────────────────────────────────────────────────
7e2a9b1c    RUNNING       41892     supervised    Worktree    2026-09-25 00:30:15   4m 12s    
3f9a12c8    COMPLETED     -         autonomous    Worktree    2026-09-25 00:15:02   2m 45s

2. Inspeccionar el resumen estadístico de cambios (--stat)

$ gz-ia session read 7e2a9b1c --stat
 internal/validator/email.go      | 42 ++++++++++++++++++++++++++++++++++++++++++
 internal/validator/email_test.go | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 100 insertions(+)

3. Visualizar las diferencias completas de código

$ gz-ia session diff 7e2a9b1c

4. Integrar las modificaciones al workspace activo

La integración de código es una acción exclusiva del desarrollador:

$ gz-ia session get 7e2a9b1c --no-commit
✓ Cambios del worktree traídos e integrados con éxito para la sesión '7e2a9b1c'.
Archivos integrados:
  • internal/validator/email.go
  • internal/validator/email_test.go
Nota: Los cambios quedaron preparados en el stage sin comitear (--no-commit).

---

6. Consideraciones Prácticas de Entorno

Exclusión de .harness/ en herramientas de análisis

Para evitar que linters, Jest, compiladores TypeScript o watchers de IDE indexen los archivos duplicados en los worktrees:

• tsconfig.json: Agrega ".harness" al array "exclude":

  {
    "exclude": ["node_modules", ".harness"]
  }

• .gitignore: gz-ia registra automáticamente .harness/ en el .gitignore del proyecto.
• ESLint / IDE Watchers: Incluye .harness/** en los patrones ignorados para reducir consumo de recursos.

Gestión de Dependencias (Proyectos Node / Frontend)

Dado que cada worktree es un árbol de archivos separado, no comparte automáticamente la carpeta node_modules:

• En proyectos con dependencias pesadas, se recomienda usar gestores con cache y enlaces globales como pnpm para evitar ejecuciones lentas de npm install.
• Opcionalmente, puedes crear un symlink al node_modules de la raíz del repositorio hacia el worktree de la sesión.

---

7. Interfaz Visual Interactiva (TUI)

Si prefieres navegar tus sesiones con interfaz de terminal:

gz-ia start
# o simplemente
gz-ia