6. Sesiones y proyectos

Goose distingue tres niveles de organización: sesión (conversación con history), proyecto (workspace con config) e instrucciones persistentes (las que el agente lee en cada turno). Dominar los tres cambia cómo trabajás con el agente.

---

Anatomía de una sesión

Una sesión es una conversación con state:

~/.config/goose/sessions/<session-id>/
├── history.jsonl     # mensajes y tool calls
├── metadata.yaml     # nombre, modelo, extensions activas
└── files/            # archivos abiertos / generados

Las sesiones persisten al cerrar Goose. Eso es importante: una conversación larga sobre un refactor de varios días no se pierde.

---

Crear, listar, retomar sesiones

Crear con nombre

goose session --name fix-auth

Sin nombre, Goose le asigna un ID auto-generado (session-2026-05-10-abc123).

Listar sesiones

goose session --list

# fix-auth        2026-05-10  modificada hace 2h     32 turns
# refactor-orders 2026-05-08  modificada hace 2d     128 turns
# session-abc123  2026-05-07  modificada hace 3d     5 turns

Retomar

goose session --resume fix-auth

Trae el history completo, las extensions activas y el modelo que tenías. Continuás como si nunca hubieses cerrado.

Borrar

goose session --delete session-abc123

O purgar viejas:

goose session --prune --older-than 30d

---

El problema del history largo

Una sesión activa tres días seguidos puede acumular decenas de miles de tokens en history. Eventualmente choca con el context_window del modelo.

Goose tiene mecanismos para manejarlo:

1. Compactación automática

Cuando se acerca al límite, Goose resume los mensajes viejos en un summary y los reemplaza:

[summary of turns 1-50: discutimos arquitectura, decidimos hexagonal,
 creamos estructura de carpetas, ...]
turn 51: tu mensaje
turn 52: respuesta del agente
...

Esto preserva información clave perdiendo detalle. Ajustable:

session:
  auto_compact: true
  compact_threshold: 0.85  # comprime a 85% del context window

2. Compactación manual

> /compact
✓ history compactado: 12k → 3k tokens

Útil cuando notás que las respuestas se vuelven lentas o el modelo empieza a olvidar cosas viejas.

3. Reset

> /clear

Borra todo el history pero conserva la sesión. Útil cuando empezás una sub-tarea que no requiere lo previo.

---

Projects

Un proyecto es un directorio + configuración asociada. Permite que cada repositorio tenga su propio:

• Modelo default (Sonnet para repo crítico, Haiku para experimentos).
• Extensions específicas (MCP servers que solo aplican a ese repo).
• Persistent instructions.
• gooseignore.

Crear un proyecto

Dentro del directorio del repo:

cd /home/artiko/proyectos/mi-app
goose project init

Crea:

.goose/
├── config.yaml          # config específica del proyecto
├── persistent.md        # instrucciones que se inyectan cada turno
├── gooseignore          # archivos que el agente no debe tocar
└── recipes/             # recipes locales del proyecto

Comandos de proyecto

goose project list             # lista proyectos registrados
goose project info             # info del proyecto actual
goose project use mi-app       # cambiar al proyecto mi-app

Heredencia de configuración

flowchart LR
    G["~/.config/goose/config.yaml<br/>(global)"] --> P[".goose/config.yaml<br/>(proyecto)"]
    P --> S[Sesión actual]
    S --> R["Override en runtime<br/>--model, /model, env vars"]

El más específico gana: runtime > proyecto > global.

---

Persistent instructions

Archivo .goose/persistent.md que se re-inyecta en cada turno del agente. Es lo equivalente a CLAUDE.md en Claude Code o AGENTS.md en otros agentes.

Ejemplo:

# Convenciones del proyecto

- Lenguaje: TypeScript con strict mode
- Tests: Vitest, no Jest
- Formato: Prettier con 2 spaces
- Imports: orden alfabético, agrupados (externos / internos / tipos)
- Mensajes de commit: `feat:`, `fix:`, `refactor:` (Conventional)

# Estructura

- `src/domain/`: lógica de negocio pura
- `src/infrastructure/`: adapters (DB, HTTP)
- `src/application/`: use cases / handlers
- Nunca import de domain hacia infrastructure

# Comandos comunes

- `bun dev` para servidor de desarrollo
- `bun test` para correr tests
- `bun build` para producción

El agente lee esto en cada turno. Mantenelo:

• Conciso: cada token cuesta. Evitá repetir cosas que el código ya dice claramente.
• Específico: convenciones, no aspiraciones.
• Actualizado: si el proyecto cambia, actualizá el archivo.

Cuándo modificar persistent.md

Cuando notás que el agente comete el mismo error dos veces, agregá la regla. Convertir frustración en feedforward es la práctica clave del harness engineering aplicada a Goose.

---

Hierarchical persistent instructions

En monorepos, podés tener instrucciones por subdirectorio:

proyecto/
├── .goose/persistent.md           # general
├── frontend/.goose/persistent.md  # solo cuando trabajás en frontend
└── backend/.goose/persistent.md   # solo cuando trabajás en backend

Goose detecta el directorio actual de la sesión y carga las instrucciones más específicas + las del root.

---

File management

Goose distingue entre archivos del proyecto y archivos abiertos en sesión.

Archivos del proyecto

Cualquier archivo bajo el directorio del proyecto que el agente puede leer/escribir, según permisos y gooseignore.

Archivos abiertos

Archivos que el agente cargó en su context activo. Visibles con:

> /files
- src/app.ts (1.2 KB, leído hace 5 minutos)
- README.md (3.4 KB, leído hace 12 minutos)

Cerrar uno (libera tokens):

> /close src/app.ts

---

Workflow recomendado de sesiones

Para tareas chicas (< 30 min)

Sesión sin nombre, ejecutás, salís:

goose session
> arreglá el bug en X
> /exit

Si después necesitás re-abrir, el ID auto-generado está en --list.

Para tareas medianas (1 día)

Sesión nombrada:

goose session --name feat-checkout
# trabajás...
# /exit

# horas después
goose session --resume feat-checkout

Para refactors grandes (varios días / semanas)

• Sesión nombrada + project con persistent instructions.
• /compact periódico para mantener tamaño razonable.
• Notas en el persistent.md cada vez que el agente comete un error nuevo.

Para CI / scripts

Sin sesión interactiva — usás goose run con recipes (cubierto en el capítulo 10).

---

Errores comunes

”Sesión no encontrada”

Verificá el nombre exacto:

goose session --list | grep <nombre>

“Context window exceeded” persistente

/compact no alcanza, tenés muchísima history acumulada. Solución:

• Empezá nueva sesión y migrá manualmente lo importante a persistent.md.
• Activá auto_compact: true con threshold más agresivo.

Persistent instructions ignoradas

• Verificá la ruta: el archivo debe ser exactamente .goose/persistent.md.
• Verificá que estás en el proyecto correcto: goose project info.
• A veces el modelo “se distrae” del archivo; reforzá con un /reload-persistent (si tu versión de Goose lo soporta).

---

¿Qué viene?

Sabés organizar el trabajo en sesiones y proyectos. En el próximo capítulo hacemos un recorrido exhaustivo por todos los comandos CLI y atajos disponibles.