AI-translated from English; not yet reviewed by a fluent editor.

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

> Instala un pequeño hook SessionStart del proyecto para añadir la rama Git al contexto de Claude Code. Comprueba su salida directa, inicio, reanudación y fallos.

By BIG CHANGE Editorial

Published: 2026-10-20T00:22:54.831Z
Updated: 2026-10-20T00:22:54.831Z
Canonical: https://bigchange.ai/blog/claude-code-session-start-branch-context-hook-guide

![Conceptual charcoal illustration of an unbranded desktop monitor with one short orange stroke above two soft charcoal strokes; a keyboard rests in front.](https://bigchange.ai/api/media/file/claude-code-session-start-context-hero-v2.png)
AI-generated conceptual illustration by BIG CHANGE; no actual Claude Code interface, hook execution or model result is depicted.

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](https://code.claude.com/docs/en/hooks), 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](https://code.claude.com/docs/en/data-usage) 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`:

```javascript
'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.

```json
{
  "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:

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

En Bash:

```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](https://code.claude.com/docs/en/costs) 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](https://bigchange.ai/blog/claude-code-session-context-continue-guide) cubre la inspección y continuación. No configura este hook inicial.

## Fuentes y lecturas adicionales

- [Anthropic, Referencia de hooks de Claude Code](https://code.claude.com/docs/en/hooks) — 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](https://code.claude.com/docs/en/hooks-guide) — 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](https://code.claude.com/docs/en/setup) — 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](https://code.claude.com/docs/en/data-usage) — 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](https://code.claude.com/docs/en/costs) — Orientación actual de cuenta y uso para pruebas interactivas. El script Git local no hace solicitudes de red ni al modelo.

## Sources

- [Referencia de hooks de Claude Code](https://code.claude.com/docs/en/hooks) — Manual principal actual de Anthropic contrastado con la captura aprobada del 19 de octubre de 2026 y otra vez al redactar. Establece orígenes startup/resume y patrones de SessionStart, command y args en forma exec, variable raíz, stdout como contexto, observador de ajustes, confianza, registros, ejecutable real en Windows y errores SessionStart no bloqueantes. Describe el producto; BIG CHANGE no ejecutó un hook invocado por Claude. No se indicaba una fecha fija de revisión del manual.
- [Automatiza acciones con hooks](https://code.claude.com/docs/en/hooks-guide) — Guía oficial de configuración y pruebas de Anthropic. Respalda la configuración y diagnóstico del lector, no una afirmación de que BIG CHANGE ejecutó el ejemplo dentro de Claude Code. El script Node acotado y los ajustes provienen del paquete de implementación local revisado por separado.
- [Configuración avanzada de Claude Code](https://code.claude.com/docs/en/setup) — Referencia oficial de instalación y entorno para revisar la configuración local. La preparación solo observó 2.1.301; la fuente no convierte esa versión en requisito mínimo.
- [Uso de datos de Claude Code](https://code.claude.com/docs/en/data-usage) — Condiciones oficiales según la cuenta. El artículo pide revisarlas antes de enviar ramas al modelo; filtrar y truncar no impide revelar clientes o incidentes confidenciales. No se infiere ninguna garantía general de privacidad.
- [Gestiona los costes eficazmente](https://code.claude.com/docs/en/costs) — Orientación oficial de cuenta y uso de modelos para comprobar interactivamente inicio y reanudación. El script local no solicita red ni modelo; las sesiones reales pueden consumir cuotas del plan, proveedor o API. No se afirma precio fijo ni prueba de pago.
- [Cómo inspeccionar contexto y continuar una sesión Claude Code](https://bigchange.ai/blog/claude-code-session-context-continue-guide) — Artículo anterior BIG CHANGE 414, citado solo como enlace contextual y para clasificar la relación. Trata de inspeccionar una conversación existente y continuar su tarea; no prueba la implementación del hook ni es un origen de continuación de un evento fechado.