Añade un hook de contexto acotado al inicio de sesión de Claude Code

Un hook de Claude Code es un comando que la aplicación ejecuta en un punto identificado de una sesión. Esta guía añade un hook SessionStart del proyecto que lee la rama Git actual y aporta una línea breve de contexto al iniciar o reanudar una conversación. Sigue la referencia actual de hooks de Anthropic, revisada el 19 de octubre de 2026. BIG CHANGE comprobó directamente el script con Node y el JSON de configuración; no ejecutamos un hook de Claude Code ni probamos una respuesta del modelo.

El gran cambio

• Qué cambia: Este hook del proyecto SessionStart proporciona una línea breve con la rama Git al iniciar o reanudar una conversación en Claude Code.
• Por qué importa: La rama actual llega al contexto al iniciar o reanudar, sin pegarla manualmente cada vez.
• Qué vigilar: El contexto no impone reglas ni garantiza respuestas. Comprueba la entrega real al inicio y al reanudar en tu propio proyecto de confianza.

Antes de instalarlo

Usa un proyecto Git que puedas modificar. Necesitas Claude Code, Node.js y Git disponibles en el mismo terminal y permiso para editar el archivo del proyecto .claude/settings.json. Comprueba node --version, git --version y claude --version. El equipo de preparación tenía Claude Code 2.1.301 y Node 24.19.0; las versiones observadas no son requisitos mínimos.

Revisa el nombre de rama antes de enviarlo a un modelo. Puede contener un cliente, incidencia o ticket. Filtrar caracteres y acortar el texto no elimina ese significado. Instala este ejemplo solo si el nombre está autorizado como contexto. De lo contrario, cambia el script para emitir un estado aprobado y no sensible y revisa esa modificación antes de instalarlo. La documentación de uso de datos de Anthropic explica el tratamiento del servicio; aplica también los permisos de tu proyecto.

Los comandos de hooks se ejecutan con tus permisos de usuario. Antes de activarlos, revisa los hooks de proyecto y usuario, la política de la organización y el script completo. La configuración del proyecto puede versionarse; .claude/settings.local.json permanece local. El ejemplo usa la configuración del proyecto para limitarla a ese ámbito.

Instala los dos archivos

1. Crea .claude/hooks/ dentro del proyecto. Guarda este bloque completo como .claude/hooks/session-context.cjs:

'use strict';

const { execFileSync } = require('node:child_process');

const project = process.env.CLAUDE_PROJECT_DIR;
if (!project) {
  process.stderr.write('CLAUDE_PROJECT_DIR is unavailable\n');
  process.exit(1);
}

try {
  const raw = execFileSync('git', ['-C', project, 'branch', '--show-current'], {
    encoding: 'utf8',
    timeout: 1500,
    maxBuffer: 4096,
    stdio: ['ignore', 'pipe', 'pipe'],
  }).trim();
  const branch = raw ? raw.replace(/[^A-Za-z0-9._/-]/g, '_').slice(0, 80) : 'detached HEAD';
  process.stdout.write(`Current project branch: ${branch}\n`);
} catch {
  process.stderr.write('Could not read the project branch; check Git and project path\n');
  process.exit(1);
}

El proceso hijo Git tiene un límite de 1,5 segundos y un búfer de salida de 4096 bytes. Una rama vacía, como con HEAD separado, se convierte en detached HEAD. Si falta la ruta del proyecto o falla Git, se produce un diagnóstico breve en stderr y código de salida 1.

2. Abre tu archivo existente .claude/settings.json. Combina la entrada hooks.SessionStart siguiente con el resto de configuración y grupos de hooks; conserva las entradas actuales. El bloque muestra el archivo completo settings.example.json del paquete revisado. Si ya contiene entradas SessionStart , añade este grupo a su matriz sin sustituirla.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-context.cjs"],
            "timeout": 5
          }
        ]
      }
    ]
  }
}

El patrón cubre una sesión nueva y otra reanudada. Anthropic también documenta clear, compact y fork como orígenes de SessionStart ; este ejemplo los omite expresamente. El campo args selecciona la forma exec: Claude Code invoca node con la ruta resuelta del script como único argumento, sin interpretación ni comillas del intérprete de comandos. En Windows, node.exe debe resolverse como ejecutable real; un adaptador .cmd no sirve para exec. Los cinco segundos del hook son independientes del límite Git de 1,5 segundos del script.

Comprueba el script y después Claude Code

3. Antes de abrir Claude Code, ejecuta el script en el terminal del proyecto y compara su salida con Git. En PowerShell:

$env:CLAUDE_PROJECT_DIR = (Get-Location).Path
node .claude/hooks/session-context.cjs
git branch --show-current

En Bash:

CLAUDE_PROJECT_DIR="$PWD" node .claude/hooks/session-context.cjs
git branch --show-current

Debe haber exactamente una línea en stdout, Current project branch: BRANCH, donde BRANCH es el resultado Git tras filtrar caracteres y limitarlo a 80. Con HEAD separado aparece Current project branch: detached HEAD. La prueba directa solo establece que el script funciona en ese terminal. En nuestra preparación, la rama ordinaria coincidió con Git; rutas ausentes e inválidas dieron stdout vacío, diagnóstico en stderr y salida 1. Inspeccionamos en el código el límite de nombres largos y la alternativa HEAD separado, pero no ejecutamos esos casos.

4. Inicia un nuevo proceso interactivo de Claude Code en el proyecto de confianza con claude --debug-file STARTUP_PRIVATE_LOG, usando una ruta privada bajo tu control. Revisa los hooks del proyecto y usuario antes de aceptar la confianza del espacio de trabajo. Busca en el registro de depuración un evento SessionStart con origen startup, la ruta del script seleccionado, el estado de salida y su tratamiento. Pregunta a Claude qué contexto de rama recibió sin permitir herramientas ni leer Git de nuevo. Compara la respuesta y el registro con el resultado directo. stdout del hook entra en el contexto; no se promete como mensaje visible de la interfaz.
5. Sal de esa sesión. Reanúdala en otro proceso con claude --debug-file RESUME_PRIVATE_LOG --resume, comprueba el evento SessionStart resume y repite la pregunta sin herramientas ni releer Git. Mantén ambos registros privados: pueden exponer detalles del proyecto. Una ejecución no interactiva -p o mediante SDK no muestra la misma solicitud de confianza y puede ejecutar hooks del repositorio automáticamente; usa la vía interactiva para esta comprobación. Anthropic dice que su observador de archivos suele detectar cambios de configuración, pero un proceso nuevo aclara la prueba de inicio y reanudación.

Si el trabajo normal cambia después la rama, repite la prueba directa y una sesión nueva para comprobar la línea. No cambies de rama solo para afirmar que esta guía se probó.

Si no se ejecuta

Empieza por el resultado directo y revisa la combinación JSON, la escritura de SessionStart , el patrón startup|resume , la ruta raíz, la disponibilidad de node y git, la confianza del espacio de trabajo y los errores de depuración. La ausencia de CLAUDE_PROJECT_DIR escribe CLAUDE_PROJECT_DIR is unavailable en stderr. Una ruta errónea o un fallo Git escribe Could not read the project branch; check Git and project path. Ambos terminan con 1 y sin línea de contexto. Un fallo de SessionStart es diagnóstico y no bloqueante; no puede actuar como barrera de ejecución. Anthropic documenta PreToolUse para controlar acciones de herramientas, un evento diferente que necesita su propio diseño revisado.

El script solo ejecuta Git local y no hace solicitudes de red ni al modelo. Las comprobaciones de inicio, reanudación y respuesta pueden consumir tu cuota de cuenta, proveedor o modelo; la guía de costes de Anthropic contiene las condiciones actuales. No se fija un precio ni se informa de una sesión de pago probada.

Para otra tarea una vez iniciada la conversación, nuestra guía para inspeccionar contexto y continuar una sesión Claude Code cubre la inspección y continuación. No configura este hook inicial.

Fuentes y lecturas adicionales

• Anthropic, Referencia de hooks de Claude Code — Especificación principal actual revisada el 19 de octubre de 2026. Documenta orígenes y patrones de SessionStart , la forma exec args, variables de ruta, stdout como contexto, recarga de configuración, confianza, registros y fallos no bloqueantes. Es documentación, no ejecución de un hook por BIG CHANGE.
• Anthropic, Automatiza acciones con hooks — Guía oficial de configuración y pruebas. El script y la configuración concretos son un ejemplo acotado de BIG CHANGE revisado para esta guía, no un resultado de prueba copiado del proveedor.
• Anthropic, Configuración de Claude Code — Instalación y requisitos del entorno. Comprueba las instrucciones actuales de tu plataforma antes de usar el ejemplo.
• Anthropic, Uso de datos de Claude Code — Condiciones actuales de datos del proveedor que debes revisar antes de enviar información de la rama al modelo; la autorización del proyecto es otra decisión.
• Anthropic, Gestiona los costes eficazmente — Orientación actual de cuenta y uso para pruebas interactivas. El script Git local no hace solicitudes de red ni al modelo.