3. Primeros pasos

Vamos a abrir tu primera sesión, hacer un cambio real en un proyecto y entender qué está pasando bajo el capó.

Pre-requisito: Goose instalado y goose configure corrido al menos una vez con un provider válido. Si no, capítulo 2.

---

Crear un proyecto de prueba

mkdir hello-goose && cd hello-goose
git init
echo 'console.log("hola");' > index.js
git add . && git commit -m "init"

Cualquier directorio sirve, pero mantenelo en git para poder revertir si Goose hace cambios que no querés.

---

Tu primera sesión

goose session

Salida típica:

🪿 starting goose session
provider: claude-code
model: claude-sonnet-4-5
extensions: developer, fetch

> Type your message. Use /help for commands.

Estás en una sesión interactiva. Escribí algo concreto:

> ¿Qué archivos tiene este directorio?

Goose va a:

1. Leer tu mensaje.
2. Decidir que necesita la herramienta list_files o shell.
3. Ejecutarla.
4. Recibir el output.
5. Responderte con el resultado.

Tenés un archivo: index.js
Su contenido es: console.log("hola");

Listo, primer ciclo agente cerrado.

---

El agent-loop en una imagen

sequenceDiagram
    participant U as Vos
    participant G as Goose
    participant M as Modelo LLM
    participant T as Herramientas
    U->>G: que archivos hay
    G->>M: prompt + tools disponibles
    M-->>G: tool_use list_files
    G->>T: list_files()
    T-->>G: ["index.js"]
    G->>M: result + history
    M-->>G: respuesta final
    G-->>U: "tenés index.js"

Cada turno pasa por este ciclo. Si el modelo decide que necesita varias herramientas, el ciclo se repite hasta que da una respuesta final sin más tool calls.

---

Hacer un cambio real

> Agregá un script en package.json que corra index.js, y cambiá index.js para que imprima 5 saludos en lugar de uno.

Goose va a:

1. Leer index.js y package.json (si existe) o crearlo.
2. Mostrarte el diff propuesto.
3. Pedir confirmación antes de escribir.
4. Aplicar el cambio.

Ejemplo de output:

📝 Voy a hacer estos cambios:

  index.js:
- console.log("hola");
+ for (let i = 0; i < 5; i++) {
+   console.log("hola");
+ }

  package.json (nuevo):
+ {
+   "name": "hello-goose",
+   "scripts": { "start": "node index.js" }
+ }

¿Continuar? [Y/n]

Decís Y, los archivos se escriben, listo.

El nivel de confirmación que Goose pide depende de tu permission mode. Los modos los cubrimos en el capítulo 12.

---

Comandos slash dentro de la sesión

Mientras estás en sesión, comandos especiales empiezan con /:

Comando	Qué hace
/help	Lista comandos disponibles
/clear	Limpia history (mantiene config)
/save <nombre>	Guarda la sesión con un nombre
/extensions	Lista extensions activas
`/mode <plan	act>`
/model <nombre>	Cambia el modelo en uso
/exit o Ctrl+D	Salir

Cobertura completa en el capítulo 7.

---

Modo planning

Antes de que Goose modifique nada, podés pedirle un plan:

> /mode plan
> Quiero refactorizar este proyecto a TypeScript. ¿Qué pasos seguís?

En modo plan el agente no toca archivos. Solo te explica qué haría. Cuando estás conforme:

> /mode act
> Adelante, ejecutá el plan

El plan es ideal para tareas grandes donde no querés sorpresas.

---

Conceptos clave del primer uso

Extensions activas

goose session --with-extension developer --with-extension fetch

O preguntá dentro de sesión:

> /extensions

Para esta sesión están activas, por ejemplo:

• developer: filesystem, shell, edit
• fetch: HTTP requests
• memory: notas persistentes

Permisos

Por defecto Goose te pregunta antes de cada operación destructiva. Podés bajar la fricción con permisos pre-aprobados:

goose session --auto-approve-tools edit,shell

Cuidado con esto: pierde una capa de control.

Sesión persistente

Si querés volver a la misma conversación más tarde:

goose session --name fix-auth
# trabajás...
# /exit

# días después
goose session --resume fix-auth

Esto trae history, archivos abiertos, contexto y todo.

---

Errores que te van a aparecer

”rate limit reached”

El provider te limitó. Esperás unos minutos o cambiás de modelo:

> /model claude-haiku-4-5

“tool execution failed: permission denied”

Estás corriendo Goose desde un directorio donde no tiene permisos de escritura. Movete a un directorio tuyo o ajustá perms.

”context length exceeded”

La conversación se pasó del límite del modelo. Solución corta:

> /clear

Solución larga: técnicas de context engineering que cubrimos en el capítulo 8.

”no provider available”

Tu config se rompió. Corré goose configure de nuevo.

---

El flujo de trabajo “honesto”

Después de unas horas de uso, los users serios convergen a este patrón:

flowchart LR
    A["Pensar la tarea en tu cabeza"] --> B["Empezar en plan mode"]
    B --> C["Aprobar plan"]
    C --> D["Act mode con permisos restringidos"]
    D --> E["Revisar diff"]
    E --> F["git commit"]

No es “decile a Goose arreglá esto y andate a tomar café”. Es dirigir al agente con plan claro, controlar sus cambios, integrarlo a tu git workflow.

Esa disciplina es la diferencia entre un agente útil y un agente que rompe cosas en silencio.

---

¿Qué viene?

Tu primer ciclo está cerrado. En el próximo capítulo cubrimos la pieza más importante de Goose: cómo se conecta con cada provider, qué CLI providers soporta, qué es ACP y cuándo usar API keys directas vs CLIs externas.