Edição em Markdown

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

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

> Instale um pequeno hook SessionStart do projeto que adiciona a branch Git atual ao contexto do Claude Code. Confira saída direta, início, retomada e falhas.

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.

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

```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);
}
```

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.

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

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

No Bash:

```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](https://code.claude.com/docs/en/costs) 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](https://bigchange.ai/blog/claude-code-session-context-continue-guide) cobre contexto e continuidade. Não configura este hook inicial.

## Fontes e leituras adicionais

- [Anthropic, Referência de hooks do Claude Code](https://code.claude.com/docs/en/hooks) — 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](https://code.claude.com/docs/en/hooks-guide) — 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](https://code.claude.com/docs/en/setup) — Instalação e requisitos de ambiente. Confira as instruções atuais da plataforma antes do exemplo.
- [Anthropic, Uso de dados do Claude Code](https://code.claude.com/docs/en/data-usage) — 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](https://code.claude.com/docs/en/costs) — Orientações atuais de conta e uso para testes interativos. O script Git local não chama rede nem modelo.

## Sources

- [Referência de hooks do Claude Code](https://code.claude.com/docs/en/hooks) — Manual primário atual da Anthropic conferido com a captura aprovada de 19 de outubro de 2026 e novamente na redação. Estabelece origens startup/resume e padrões de SessionStart, command e args na forma exec, variável raiz, stdout como contexto, observador de configurações, confiança, logs, executável real no Windows e erros SessionStart não bloqueantes. Descreve o produto; a BIG CHANGE não executou hook invocado por Claude. Sem data fixa de revisão informada.
- [Automatize ações com hooks](https://code.claude.com/docs/en/hooks-guide) — Guia oficial da Anthropic para configuração e testes. Apoia configuração e diagnóstico pelo leitor, não a afirmação de execução pela BIG CHANGE dentro de Claude Code. O script Node delimitado e ajustes vieram do pacote de implementação local revisado separadamente.
- [Configuração avançada do Claude Code](https://code.claude.com/docs/en/setup) — Referência oficial de instalação e ambiente. A preparação só observou 2.1.301; a fonte não torna essa versão um requisito mínimo.
- [Uso de dados do Claude Code](https://code.claude.com/docs/en/data-usage) — Termos oficiais conforme a conta. Revise antes de inserir a branch no modelo: filtro e truncamento não impedem expor nomes confidenciais de clientes ou incidentes. Nenhuma garantia geral de privacidade é inferida.
- [Gerencie custos com eficácia](https://code.claude.com/docs/en/costs) — Orientação oficial de conta e modelo para testes interativos de início e retomada. O script local não pede rede nem modelo, mas sessões reais podem consumir franquias do plano, provedor ou API. Não se afirma preço fixo nem teste pago.
- [Como inspecionar contexto e continuar uma sessão Claude Code](https://bigchange.ai/blog/claude-code-session-context-continue-guide) — Artigo anterior BIG CHANGE 414, usado apenas como link contextual e classificação de relação. Trata de conversa existente e sua continuação; não comprova a implementação do hook nem é um antecessor direto de evento datado.