Adicione um hook limitado de contexto ao início do Claude Code

Um hook do Claude Code é um comando executado pelo aplicativo em um ponto identificado da sessão. Este guia adiciona um hook de projeto SessionStart que lê a branch Git atual e fornece uma linha breve de contexto ao iniciar ou retomar a conversa. Segue a referência atual de hooks da Anthropic, conferida em 19 de outubro de 2026. A BIG CHANGE verificou diretamente o script com Node e o JSON de configuração; não executamos um hook chamado pelo Claude Code nem testamos resposta do modelo.

A grande mudança

• O que mudou: Este hook do projeto SessionStart fornece uma linha breve de branch Git quando Claude Code inicia ou retoma a conversa.
• Por que importa: A branch atual chega ao contexto no início ou na retomada, sem colagem manual toda vez.
• O que observar: Contexto não impõe regras nem garante resposta. Confira a entrega real no início e na retomada do seu projeto confiável.

Antes de instalar

Use um projeto Git que possa modificar. Você precisa de Claude Code, Node.js e Git no mesmo terminal, além de permissão para editar o arquivo de projeto .claude/settings.json. Confira node --version, git --version e claude --version. O ambiente de preparação tinha Claude Code 2.1.301 e Node 24.19.0; versões observadas não são requisitos mínimos.

Revise o nome da branch antes de enviá-lo a um modelo. Pode conter cliente, chamado ou incidente. Filtrar caracteres e encurtar a string não remove esse significado. Instale somente se o nome estiver aprovado para o contexto do modelo. Caso contrário, adapte o script para emitir um estado aprovado e não sensível e revise a mudança antes da instalação. A documentação de dados da Anthropic explica o tratamento pelo serviço; aplique também as permissões do projeto.

Comandos de hooks rodam com suas permissões de usuário. Inspecione hooks de projeto e usuário, política da organização e script completo antes de ativar. Configurações do projeto podem entrar em commits; .claude/settings.local.json fica local. O exemplo usa o arquivo de configuração do projeto para limitar o escopo.

Instale os dois arquivos

1. Crie .claude/hooks/ no projeto. Salve o bloco inteiro 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);
}

O processo filho Git tem limite de 1,5 segundo e buffer de saída de 4.096 bytes. Branch vazia, como no HEAD destacado, vira detached HEAD. Caminho ausente ou falha Git gera diagnóstico breve em stderr e código de saída 1.

2. Abra seu arquivo existente .claude/settings.json. Combine a entrada hooks.SessionStart abaixo com outras configurações e grupos, preservando os existentes. O bloco mostra o arquivo completo settings.example.json do pacote revisado. Se já houver entradas SessionStart , adicione o grupo ao array em vez de substituí-lo.

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

O padrão cobre sessão nova e retomada. A Anthropic também documenta clear, compact e fork como origens de SessionStart ; este exemplo as omite de propósito. O campo args seleciona a forma exec: Claude Code invoca node com o caminho resolvido do script como um argumento, sem aspas ou interpretação pelo shell. No Windows, node.exe precisa resolver para um executável real; um adaptador .cmd não serve para exec. O limite de cinco segundos do hook é separado do limite Git de 1,5 segundo do script.

Confira o script e depois o Claude Code

3. Antes de abrir Claude Code, execute o script no terminal do projeto e compare a saída com Git. No PowerShell:

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

No Bash:

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

Espere exatamente uma linha em stdout, Current project branch: BRANCH, em que BRANCH é o resultado Git após filtrar caracteres e limitar a 80. HEAD destacado imprime Current project branch: detached HEAD. A verificação direta só comprova o script local nesse terminal. Na preparação, a branch comum coincidiu com Git; caminhos ausentes e inválidos deram stdout vazio, diagnóstico stderr e saída 1. Inspecionamos no código o limite de nomes longos e a alternativa HEAD destacado, mas não executamos esses casos.

4. Inicie um novo processo interativo de Claude Code no projeto confiável com claude --debug-file STARTUP_PRIVATE_LOG, usando caminho privado sob seu controle. Revise hooks de projeto e usuário antes de aceitar a confiança do espaço de trabalho. Procure no log de depuração um evento SessionStart de origem startup, caminho do script selecionado, estado de saída e tratamento da saída. Pergunte qual contexto de branch Claude recebeu sem permitir ferramenta nem releitura de Git. Compare resposta e registro com o resultado direto. stdout do hook entra no contexto; não há promessa de mensagem visível na interface.
5. Saia dessa sessão. Retome em processo separado com claude --debug-file RESUME_PRIVATE_LOG --resume, confira o evento SessionStart resume e repita a pergunta sem ferramenta ou nova leitura Git. Mantenha ambos os logs privados, pois podem expor detalhes do projeto. Uma execução não interativa -p ou via SDK não tem o mesmo aviso de confiança e pode rodar hooks automaticamente; use o fluxo interativo. A Anthropic diz que seu observador de arquivos normalmente capta mudanças nos hooks, mas um processo novo torna mais claro o teste de início e retomada.

Se o trabalho normal mudar a branch depois, repita a verificação direta e uma sessão nova para ver a linha. Não mude de branch apenas para afirmar que este guia foi testado.

Se não executar

Comece pela saída direta e confira combinação JSON, grafia de SessionStart , padrão startup|resume , raiz do projeto, disponibilidade de node e git, confiança e erros de depuração. A ausência de CLAUDE_PROJECT_DIR imprime CLAUDE_PROJECT_DIR is unavailable em stderr. Caminho errado ou falha Git imprime Could not read the project branch; check Git and project path. Ambos saem com 1 e sem linha de contexto. Uma falha de SessionStart é diagnóstica e não bloqueante; não serve de barreira de ação. A Anthropic documenta PreToolUse para controlar ação de ferramenta, outro evento que exige seu próprio projeto revisado.

O script só roda Git local, sem solicitação de rede ou modelo. Início, retomada e perguntas no Claude Code podem consumir franquia da conta, provedor ou modelo; o guia de custos da Anthropic traz os termos atuais. Não há preço fixo nem relato de teste de sessão paga.

Para outra tarefa depois de começar a conversa, nosso guia de inspeção de contexto e continuação de sessão Claude Code cobre contexto e continuidade. Não configura este hook inicial.

Fontes e leituras adicionais

• Anthropic, Referência de hooks do Claude Code — Especificação primária atual verificada em 19 de outubro de 2026. Documenta origens e padrões de SessionStart , forma exec args, variáveis de caminho, stdout como contexto, recarga de configuração, confiança, logs e falhas não bloqueantes. É documentação, não execução de hook pela BIG CHANGE.
• Anthropic, Automatize ações com hooks — Guia oficial de configuração e testes. O script e ajustes exatos acima são exemplo limitado da BIG CHANGE revisado para este guia, não resultado de teste copiado do fornecedor.
• Anthropic, Configuração do Claude Code — Instalação e requisitos de ambiente. Confira as instruções atuais da plataforma antes do exemplo.
• Anthropic, Uso de dados do Claude Code — Termos atuais do provedor antes de enviar dados da branch ao contexto; autorização do projeto é decisão separada.
• Anthropic, Gerencie custos com eficácia — Orientações atuais de conta e uso para testes interativos. O script Git local não chama rede nem modelo.