Inicio y cierre de sesiónretoma cualquier proyecto en un mensaje y deja de pagar por el chat de ayer

01 el punto de partida

Qué es y por qué existe

Claude Code ya tiene memoria propia (CLAUDE.md y su carpeta de memoria), pero está pensada para reglas estables: cómo te gusta el código, qué stack usas. No está pensada para el estado cambiante de un proyecto: qué hiciste el martes, qué decidiste el miércoles, qué falta para el viernes. Eso es lo que resuelve STATE.md.

02 antes de instalar nada

Lo que Claude Code ya trae y por qué no alcanza

Claude Code guarda cada conversación en disco y te da varias formas de volver a ella. Conviene conocerlas porque el sistema de esta guía no las sustituye: las usa donde sirven y las evita donde cobran de más.

El detalle que importa: si reabres una conversación grande después de más o menos una hora, Claude Code te ofrece retomarla desde un resumen o completa. Ninguna de las dos es gratis: la caché ya expiró y la primera petición reprocesa todo el historial. Por eso el estado vive en un archivo de unas cuantas líneas y no en el transcript de 600 mil tokens.

03 el dato que lo justifica

Lo que cuesta no cerrar

Antes de escribir el sistema medí dos semanas de uso real. El resultado fue lo que decidió el diseño del comando de cierre:

• 14 conversaciones que se estiraron más de 48 horas se llevaron el 83% del consumo semanal, con solo 2 a 7 horas de trabajo real cada una.
• Retomar una conversación tras una pausa larga obliga a regrabar el contexto completo en caché: más de mil regrabaciones en el periodo, un 25% del ciclo.
• Una conversación de 620 mil tokens retomada al día siguiente cuesta alrededor de 1.5 millones de unidades antes de leer la primera palabra nueva.

La conclusión fue incómoda pero simple: guardar el estado no sirve de nada si después sigues escribiendo en el mismo chat. Por eso /cerrar-sesion no solo guarda: termina su respuesta con un bloque que te dice, literal, que cierres la conversación.

04 el archivo

El formato de STATE.md

El formato es fijo a propósito. Si cada sesión se escribe igual, el comando de inicio siempre sabe dónde buscar 'lo hecho', 'pendientes' y 'próximo paso'. Este es el bloque que se prepende en cada cierre:

## Última sesión — 2026-08-27 — Buscador del Lab con filtros

**Lab en producción con buscador, filtros por tipo y nivel y la primera guía publicada.**

### Lo hecho hoy
- Motor de búsqueda client-side sobre título, resumen, tags y herramientas
- Plantilla de guía con índice lateral, bloques de comando y FAQ
- Primera guía publicada: inicio y cierre de sesión

### Decisiones tomadas
- Guías como archivos TypeScript tipados, no markdown: la plantilla es fija y así el editor valida cada bloque

### Bugs conocidos
- El contador de resultados no se anuncia a lectores de pantalla (pendiente aria-live)

### Pendientes — orden de prioridad

#### 🔴 P0 — Bloqueante
- Publicar sitemap con las guías nuevas

#### 🟡 P1 — Esta semana
- Segunda y tercera guía

#### 🟢 P2 — Post-launch
- Negociación de contenido markdown para agentes

### Próximo paso para retomar
Escribir la guía del MCP de GHL con la plantilla ya validada.

---

Tres reglas que hacen que funcione: la sesión nueva siempre va arriba (lo primero que se lee es lo más reciente); los pendientes llevan prioridad explícita (P0 bloqueante, P1 esta semana, P2 después); y el 'próximo paso' es una sola frase accionable, no una lista.

05 para no confundirlas

Tres memorias que se parecen y no son la misma

Cuando la gente instala este sistema, la duda que más se repite es si STATE.md choca con la memoria que Claude Code ya lleva solo. No choca, pero hay que tener claro quién escribe cada una, dónde vive y si viaja con el repo:

• De la memoria automática solo se cargan las primeras 200 líneas (o 25 KB) del índice; el resto lo lee Claude bajo demanda. No es un lugar para pendientes ordenados.
• La memoria automática es por repositorio y se comparte entre todos los worktrees del mismo repo, pero no entre computadoras. STATE.md sí llega a la otra máquina porque va en el push.
• Los subagentes no ven la memoria automática de la conversación principal ni la conversación. Si un subagente necesita saber en qué va el proyecto, pásale la ruta de STATE.md en el prompt.
• Un CLAUDE.md largo reduce la obediencia a sus propias reglas. Si un dato cambia cada semana, no es de CLAUDE.md: es de STATE.md.

06 comando 1

/iniciar-sesion, paso a paso

Los slash-commands propios de Claude Code son archivos markdown en ~/.claude/commands/ (globales) o en .claude/commands/ del proyecto. El nombre del archivo es el nombre del comando. Crea el archivo y pega el contenido:

mkdir -p ~/.claude/commands && curl -fsSL https://raw.githubusercontent.com/davidiriza-lab/sesiones-claude-code/main/commands/iniciar-sesion.md -o ~/.claude/commands/iniciar-sesion.md && curl -fsSL https://raw.githubusercontent.com/davidiriza-lab/sesiones-claude-code/main/commands/cerrar-sesion.md -o ~/.claude/commands/cerrar-sesion.md

mkdir -p ~/.claude/commands && touch ~/.claude/commands/iniciar-sesion.md

---
description: Carga el contexto de un proyecto (lee STATE.md) para retomar donde se dejó. Acepta el nombre del proyecto como argumento o lista los disponibles.
---

# /iniciar-sesion [proyecto]

## Paso 0 — Exigir conversación limpia
Este comando reconstruye el contexto DESDE STATE.md. Si esta conversación ya trae
trabajo previo (otro tema, otro proyecto, una sesión ya cerrada), NO cargues nada.
Responde solo esto y espera:

  ⛔ Esta conversación ya viene cargada.
  Escribe /clear y vuelve a lanzar /iniciar-sesion [proyecto].

Si el usuario responde que quiere continuar aquí, hazlo sin insistir.

## Paso 1 — Resolver el proyecto
- Con argumento: busca la carpeta en ~/proyectos/[argumento]; acepta coincidencia parcial;
  si hay ambigüedad muestra opciones.
- Sin argumento: si el directorio actual está dentro de ~/proyectos/, úsalo.
  Si no, lista las carpetas de ~/proyectos/ numeradas y pregunta cuál.

## Paso 2 — Cargar contexto
1. Lee STATE.md y extrae la sección "Última sesión" (la primera del archivo).
2. Complementa con git: últimos 3 commits y archivos con cambios sin commitear.
3. Revisa trabajo externo: `git fetch origin --quiet` y lee `git status -sb`.
   - behind N con copia local limpia → `git pull --ff-only` y resume qué llegó (por tema).
   - behind N con cambios propios → NO hagas pull; repórtalo en "Antes de empezar".
   - ahead N → hay commits sin subir; repórtalo.
4. Health check (reporta SOLO si algo falla):
   - package.json sin node_modules → "instalar deps con npm install"
   - .env.example sin .env.local → "faltan variables de entorno locales"
   - .next/ más viejo que el último commit → "build cache viejo"
   - requirements.txt sin venv → "instalar deps de Python"
5. Presenta el resumen con ESTE formato:

**Proyecto:** [nombre]
**Última sesión:** [fecha del STATE.md, o "primera sesión"]
**Cambios externos traídos:** [solo si hubo pull]
**Lo hecho:** [2-3 bullets de la última sesión]
**Pendientes:** 🔴 P0 / 🟡 P1 / 🟢 P2
**Próximo paso:** [frase exacta del campo "Próximo paso para retomar"]
**⚠️ Antes de empezar:** [solo si el health check detectó algo]
**¿Por dónde empezamos?**

6. Si no existe STATE.md, créalo con el encabezado y una "Sesión 1" vacía,
   y pregunta qué estamos construyendo.

Sobre el formato del archivo: Claude Code fusionó los comandos con las skills. Un archivo en ~/.claude/commands/nombre.md y una carpeta en ~/.claude/skills/nombre/SKILL.md producen el mismo /nombre y aceptan el mismo frontmatter. Los archivos de commands siguen funcionando; si algún día quieres adjuntar scripts o plantillas al comando, muévelo a skills. Dos campos de frontmatter que valen la pena aquí: argument-hint: [proyecto] para que el autocompletado te recuerde el argumento, y disable-model-invocation: true en el comando de cierre, para que solo lo dispares tú y Claude no decida cerrar por su cuenta.

07 comando 2

/cerrar-sesion, paso a paso

touch ~/.claude/commands/cerrar-sesion.md

---
description: Cierra la sesión guardando el resumen en STATE.md del proyecto activo, hace commit y push, y termina la conversación.
---

# /cerrar-sesion

1. Detecta el proyecto activo: el git root del directorio actual (o el directorio si no hay git).

2. Genera el resumen de la sesión y PREPÉNDELO en STATE.md (después del encabezado,
   antes de las sesiones anteriores) con esta estructura exacta:

   ## Última sesión — YYYY-MM-DD — [título corto del foco]
   **[Una frase en negrita con el logro principal o el estado al cerrar.]**
   ### Lo hecho hoy            (bullets concretos: qué archivo, qué endpoint, qué componente)
   ### Decisiones tomadas      (con su razón; omitir si no hubo)
   ### Bugs conocidos          (con workaround si existe; omitir si no hay)
   ### Pendientes — orden de prioridad
   #### 🔴 P0 — Bloqueante
   #### 🟡 P1 — Esta semana
   #### 🟢 P2 — Post-launch
   ### Próximo paso para retomar
   [Una frase que diga exactamente por dónde arrancar la próxima vez.]
   ---

3. Si STATE.md no existe, créalo con este encabezado antes del resumen:
   # STATE.md — [nombre del proyecto]
   > Bookmark técnico de continuidad. Léelo al inicio de cada sesión y actualízalo al cierre.
   ---

4. Commit: `git add STATE.md && git commit -m "chore: cerrar sesión YYYY-MM-DD"`

5. Push con conciliación:
   - `git fetch origin --quiet` y lee `git status -sb`.
   - Sin "behind" → `git push`.
   - Con "behind" → `git pull --rebase`; si no hay conflictos, push y menciona en una línea
     qué llegó de fuera. Si hay conflictos, `git rebase --abort`, NO fuerces nada,
     reporta los archivos y deja la conciliación para la próxima sesión.
   - Sin remote o push fallido → avisa en una línea y continúa. Nunca abortes el cierre por esto.

6. Confirma: fecha, foco de la sesión y el próximo paso guardado.

7. CIERRE REAL — no es opcional. Termina SIEMPRE tu respuesta con este bloque, literal
   y como último elemento:

   ───────────────────────────────
   ⛔ CIERRA ESTA CONVERSACIÓN AHORA
   El STATE.md ya está guardado y commiteado. Todo lo de hoy está a salvo.
   →  Escribe /clear (o abre un chat nuevo)
   Mañana: /iniciar-sesion [proyecto] reconstruye todo desde STATE.md.
   Seguir escribiendo aquí arrastra el contexto de hoy y lo cobra otra vez.
   ───────────────────────────────

8. Si el usuario sigue escribiendo en esta conversación después del cierre, recuérdaselo
   en UNA línea antes de responder. Una vez por mensaje, sin bloquear. Si pide continuar
   aquí explícitamente, deja de avisar.

Fíjate en el paso 5: el cierre nunca se aborta por un problema de git. Si el push falla, se avisa en una línea y se sigue. El estado ya está en el archivo; subirlo es deseable, no bloqueante.

08 el día a día

Cómo se ve un día con el sistema

1. Abres Claude Code en un chat limpio y escribes /iniciar-sesion nombre-del-proyecto.
2. Lees el resumen: lo hecho, pendientes por prioridad, próximo paso y, si aplica, qué llegó de fuera o qué hay que instalar.
3. Trabajas normal. Todo lo que decidas o descubras, el comando de cierre lo va a capturar de la conversación.
4. Al terminar escribes /cerrar-sesion. Revisas que el resumen sea fiel (dos segundos) y ves el bloque de cierre.
5. Escribes /clear. Mañana repites desde el paso 1 con cero contexto arrastrado.

El único hábito nuevo es el paso 5. Todo lo demás lo hacen los comandos.

09 cuando no trabajas solo

Dos máquinas, dos personas o dos asistentes

El sistema asume que el repo puede cambiar fuera de tu sesión: desde otra computadora tuya, desde un colaborador, o desde otro asistente de IA que trabaje el mismo proyecto. Tres reglas lo mantienen sano:

• Al arrancar, siempre fetch. Si hay commits nuevos y tu copia está limpia, se traen solos y el resumen te dice qué llegó. Si tu copia tiene cambios propios, no se hace pull automático: se te avisa y decides.
• Al cerrar, siempre rebase antes de push. Si hay conflicto, se aborta el rebase y se reporta. Nunca un push forzado.
• Cada asistente escribe solo en su bitácora. Si además de Claude usas otro asistente, dale su propio archivo de estado (por ejemplo OTRO_STATE.md) y pon en ambos comandos la regla de leerlo como contexto secundario y nunca escribirlo.

10 la trampa nueva

Worktrees y la app de escritorio

Hay un caso donde el sistema falla en silencio si no lo sabes: los worktrees. Claude Code puede abrir cada sesión en una copia aparte del repo (claude --worktree nombre, o pidiéndoselo en el chat), y la app de escritorio lo hace sola: cada sesión nueva del sidebar es su propio worktree. Esa copia vive en .claude/worktrees/<nombre>/ y trabaja sobre una rama nueva llamada worktree-<nombre>.

• Si corres /cerrar-sesion dentro de un worktree, el commit de STATE.md cae en la rama worktree-<nombre>, no en main. Mañana, desde la copia principal, /iniciar-sesion va a leer un STATE.md viejo.
• Dos sesiones en paralelo son dos copias del mismo STATE.md. La segunda que cierre no ve lo que escribió la primera hasta que alguien fusione las ramas.
• El worktree arranca sin los archivos ignorados por git. Tu .env.local no está ahí, y el health check lo va a marcar. Para que se copie solo, crea un archivo .worktreeinclude en la raíz con la lista de esos archivos.
• Al salir, Claude Code borra el worktree si está limpio; si tiene cambios te pregunta. Si eliges borrar, se va también la rama con el cierre.

.env
.env.local

Mi regla: cierro sesión desde la copia principal, o mergeo la rama del worktree antes de cerrar. Y en el comando de cierre conviene una línea que detecte si el directorio está dentro de .claude/worktrees/ y lo avise en el mensaje final. Agrega .claude/worktrees/ al .gitignore para que no te aparezca como carpeta sin rastrear.

11 dentro del día

Gastar menos ventana mientras trabajas

Cerrar bien resuelve el costo entre días. El costo dentro del día lo resuelven cuatro hábitos que no requieren instalar nada, y una herramienta que sí:

La herramienta es context-mode, un plugin para Claude Code que corre los comandos pesados en un sandbox e indexa los resultados para que Claude busque en ellos en vez de cargarlos completos. Lo instalé y probé su diagnóstico: registra hooks de SessionStart, PreCompact y Stop, más una decena de herramientas MCP. Su autor promete reducciones muy altas de contexto; yo no medí ese número, así que tómalo como promesa del proyecto y no como dato mío. Licencia Elastic 2.0, no MIT: gratis para uso normal, con restricciones si quieres revenderlo como servicio.

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

12 para exprimirlo

Ajustes que valen la pena

Hook SessionStart: que el estado llegue solo

Los hooks son scripts que Claude Code ejecuta en momentos fijos, y a diferencia de una instrucción en CLAUDE.md no dependen de que Claude decida obedecer. El de SessionStart tiene una propiedad que aquí es oro: lo que el script imprime se agrega al contexto de Claude. Con esto, el encabezado de STATE.md y el estado de git entran a la conversación antes de tu primer mensaje, sin gastar un turno en leerlos:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear",
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$CLAUDE_PROJECT_DIR\" && [ -f STATE.md ] && { echo '## STATE.md (última sesión)'; sed -n '1,40p' STATE.md; echo; echo '## git'; git status -sb 2>/dev/null | head -5; }"
          }
        ]
      }
    ]
  }
}

• El matcher startup|clear lo dispara al abrir Claude Code y después de cada /clear, que es exactamente cuando arrancas limpio. No lo pongas en resume ni en compact: ahí ya hay contexto.
• No reemplaza a /iniciar-sesion. El hook mete el texto crudo; el comando hace el fetch, el health check y te presenta el resumen con formato. Con el hook, el comando arranca con la mitad del trabajo hecho.
• Si el hook vive en .claude/settings.json del repo, quien clone el proyecto lo hereda. Si prefieres que sea solo tuyo, va en ~/.claude/settings.json.
• Dentro de un worktree, $CLAUDE_PROJECT_DIR sigue apuntando a la copia principal. Si quieres el STATE.md del worktree, lee el campo cwd del JSON que el hook recibe por stdin.