Magdagdag ng limitadong project-context hook sa pagsisimula ng Claude Code

Ang Claude Code hook ay command na pinapatakbo ng app sa isang pinangalanang punto ng session. Nagdaragdag ang gabay ng project-scoped na SessionStart hook na bumabasa ng kasalukuyang Git branch at nagbibigay ng maikling konteksto sa pagsimula o pagpapatuloy ng usapan. Sinusunod nito ang kasalukuyang sanggunian ng hooks ng Anthropic, na sinuri noong 19 Oktubre 2026. Direktang sinuri ng BIG CHANGE ang script sa Node at ang settings JSON; hindi kami nagpatakbo ng hook na tinawag ng Claude Code o sumubok ng sagot ng modelo.

Ang malaking pagbabago

• Ano ang nagbago: Ang project hook na ito na SessionStart ay nagbibigay ng maikling linya ng Git branch sa pagsimula o pagpapatuloy ng usapan sa Claude Code.
• Bakit mahalaga: Napapasama sa konteksto ang kasalukuyang branch sa simula o pagpapatuloy nang hindi paulit-ulit na ipinapaste.
• Dapat bantayan: Hindi nagpapatupad ng tuntunin o gumagarantiya ng sagot ang konteksto. Suriin ang aktuwal na paghatid sa simula at pagpapatuloy sa pinagkakatiwalaang proyekto.

Bago i-install

Gumamit ng Git project na maaari mong baguhin. Kailangan ang Claude Code, Node.js at Git sa iisang terminal at pahintulot na i-edit ang .claude/settings.json ng proyekto. Suriin ang node --version, git --version at claude --version. May Claude Code 2.1.301 at Node 24.19.0 ang paghahandang host; mga naobserbahang bersiyon ito, hindi minimum na kailangan.

Suriin ang pangalan ng branch bago ipadala sa modelo. Maaaring may pangalan ng kliyente, ticket o insidente. Hindi inaalis ng pag-filter at pagpapaikli ang kahulugan. I-install lamang kung aprubado ang pangalan para sa model context. Kung hindi, baguhin ang script para maglabas ng aprubadong hindi sensitibong status at repasuhin bago i-install. Ang dokumentasyon ng Anthropic sa datos ay nagpapaliwanag ng paghawak ng serbisyo; sundin din ang pahintulot ng proyekto.

Gamit ang iyong user permissions tumatakbo ang hook commands. Bago paganahin, siyasatin ang umiiral na project at user hooks, patakaran ng organisasyon at buong script. Maaaring maisama sa repository commit ang project settings; .claude/settings.local.json ay lokal lamang. Project settings file ang ginagamit upang doon lang saklaw ang configuration.

I-install ang dalawang file

1. Gumawa ng .claude/hooks/ sa proyekto. I-save ang buong block bilang .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);
}

May 1.5-segundong timeout at 4,096-byte na output buffer ang Git child process. Kapag walang branch, gaya ng detached HEAD, magiging detached HEAD ito. Ang nawawalang project path o Git failure ay nagbibigay ng maikling stderr diagnostic at exit code 1.

2. Buksan ang umiiral na .claude/settings.json. Isama ang entry na hooks.SessionStart sa ibang settings at hook group nang pinapanatili ang dati. Buong settings.example.json mula sa sinuring pakete ang ipinapakita. Kung mayroon nang SessionStart entries, idagdag ang grupong ito sa array sa halip na palitan iyon.

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

Saklaw ng matcher ang bagong session at ipinagpatuloy na session. Idinodokumento rin ng Anthropic ang clear, compact at fork bilang mga pinagmumulan ng SessionStart ; sadyang wala ang mga iyon sa halimbawang ito. Pinipili ng field na args ang exec form: tinatawag ng Claude Code ang node kasama ang resolved project script path bilang iisang argument, nang walang shell quoting o parsing. Sa Windows, dapat tunay na executable ang node.exe ; hindi angkop ang .cmd shim para sa exec form. Hiwalay ang limang-segundong hook timeout sa 1.5-segundong Git timeout ng script.

Suriin muna ang script, saka Claude Code

3. Bago buksan ang Claude Code, patakbuhin ang script sa project terminal at ihambing ang output sa Git. Sa PowerShell:

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

Sa Bash:

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

Asahan ang eksaktong isang stdout line, Current project branch: BRANCH, kung saan ang BRANCH ay resulta ng Git matapos ang character filter at 80-character na hangganan. Sa detached HEAD, ipinapakita ang Current project branch: detached HEAD. Lokal na pagtakbo lang sa terminal na iyon ang napapatunayan ng direktang check. Sa paghahanda namin, tumugma sa Git ang karaniwang branch; ang nawawala at maling path ay nagbigay ng walang stdout, stderr diagnostic at exit 1. Siniyasat namin sa source ang limitasyon ng mahabang pangalan at detached-HEAD fallback ngunit hindi pinatakbo ang mga kasong iyon.

4. Magsimula ng bagong interaktibong Claude Code process sa pinagkakatiwalaang proyekto gamit ang claude --debug-file STARTUP_PRIVATE_LOG, sa pribadong path na kontrolado mo. Repasuhin ang project at user hooks bago tanggapin ang workspace trust. Hanapin sa debug log ang event na SessionStart na may source na startup, piniling script path, exit status at output handling. Itanong kay Claude kung anong branch context ang natanggap nito nang hindi pinapayagang gumamit ng tool o magbasa ng Git muli. Ihambing ang sagot at log sa direktang resulta. Pumapasok sa context ang hook stdout; hindi garantisadong mensahe ito sa nakikitang interface.
5. Lumabas sa session. Ipagpatuloy sa hiwalay na process gamit ang claude --debug-file RESUME_PRIVATE_LOG --resume, saka suriin ang event na SessionStart resume at ulitin ang tanong nang walang tool o bagong Git read. Panatilihing pribado ang dalawang debug log dahil maaaring may detalye ng proyekto. Ang hindi interaktibong -p o SDK run ay walang parehong workspace-trust prompt at maaaring awtomatikong magpatakbo ng repository hooks, kaya gamitin ang interaktibong paraan. Sabi ng Anthropic, karaniwang nakukuha ng file watcher ang binagong settings; mas malinaw pa rin ang startup/resume test sa bagong process.

Kung mabago ang branch sa normal na trabaho, ulitin ang direktang check at bagong session upang tingnan ang linya. Huwag magpalit ng branch para lang sabihing nasubukan ang gabay.

Kung hindi tumakbo

Simulan sa direktang resulta, saka tingnan ang pagsasama ng JSON, baybay ng SessionStart , matcher na startup|resume , project-root path, pagkakaroon ng node at git, workspace trust at debug errors. Kapag wala ang CLAUDE_PROJECT_DIR , ilalabas ang CLAUDE_PROJECT_DIR is unavailable sa stderr. Kapag mali ang path o pumalya ang Git, ilalabas ang Could not read the project branch; check Git and project path. Parehong exit 1 at walang context line. Ang kabiguan ng SessionStart ay diagnostic at hindi humaharang; hindi ito action gate. Idinodokumento ng Anthropic ang PreToolUse para kontrolin ang tool action, ibang event na nangangailangan ng sariling sinuring disenyo.

Lokal na Git lang ang pinapatakbo ng script at wala itong network request o model call. Maaaring makabawas sa account, provider o model allowance ang Claude Code startup, resume at tanong; nasa gabay ng Anthropic sa gastos ang kasalukuyang tuntunin. Walang itinakdang presyo o iniulat na bayad na session test dito.

Para sa hiwalay na gawain kapag nagsimula na ang usapan, ang aming gabay sa pagsusuri ng context at pagpapatuloy ng Claude Code session ay tumatalakay sa context at pagpapatuloy. Hindi nito kino-configure ang startup hook na ito.

Mga sanggunian at karagdagang babasahin

• Anthropic, Sanggunian sa Claude Code hooks — Kasalukuyang pangunahing espesipikasyon na sinuri noong 19 Oktubre 2026. Idinodokumento ang sources at matchers ng SessionStart , exec-form args, path placeholders, stdout context, settings reload, trust, debug logs at hindi humaharang na failures. Dokumentasyon ito, hindi hook execution ng BIG CHANGE.
• Anthropic, I-automate ang mga aksiyon gamit ang hooks — Opisyal na gabay sa setup at testing. Ang eksaktong script at settings sa itaas ay limitadong BIG CHANGE example na sinuri para rito, hindi kinopyang vendor test result.
• Anthropic, Claude Code setup — Pag-install at kailangan sa environment. Suriin ang kasalukuyang platform instructions bago gamitin ang halimbawa.
• Anthropic, Paggamit ng datos ng Claude Code — Kasalukuyang data-handling terms ng provider bago ipadala ang branch context; hiwalay na desisyon ang pahintulot ng proyekto.
• Anthropic, Pamahalaan nang mahusay ang gastos — Kasalukuyang gabay sa account at paggamit para sa interaktibong checks. Walang model o network request ang lokal na Git script.