Markdown edition

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

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

> Mag-install ng maliit na SessionStart hook para idagdag ang kasalukuyang Git branch sa Claude Code context. Suriin ang direktang output, pagsisimula, pagpapatuloy at kabiguan.

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.

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

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

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.

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

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

Sa Bash:

```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](https://code.claude.com/docs/en/costs) 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](https://bigchange.ai/blog/claude-code-session-context-continue-guide) 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](https://code.claude.com/docs/en/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](https://code.claude.com/docs/en/hooks-guide) — 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](https://code.claude.com/docs/en/setup) — Pag-install at kailangan sa environment. Suriin ang kasalukuyang platform instructions bago gamitin ang halimbawa.
- [Anthropic, Paggamit ng datos ng Claude Code](https://code.claude.com/docs/en/data-usage) — Kasalukuyang data-handling terms ng provider bago ipadala ang branch context; hiwalay na desisyon ang pahintulot ng proyekto.
- [Anthropic, Pamahalaan nang mahusay ang gastos](https://code.claude.com/docs/en/costs) — Kasalukuyang gabay sa account at paggamit para sa interaktibong checks. Walang model o network request ang lokal na Git script.

## Sources

- [Sanggunian sa Claude Code hooks](https://code.claude.com/docs/en/hooks) — Kasalukuyang pangunahing Anthropic manual na itinapat sa aprubadong snapshot ng 19 Oktubre 2026 at muling sinuri sa pagsulat. Itinatakda ang SessionStart startup/resume sources at matchers, exec-form command at args, project-root placeholder, plain stdout context, settings watcher, workspace trust, debug-file inspection, tunay na Windows executable at hindi humaharang na SessionStart errors. Inilalarawan ang produkto; hindi nagpatakbo ang BIG CHANGE ng Claude-invoked hook. Walang nakasaad na permanenteng petsa ng manual revision.
- [I-automate ang mga aksiyon gamit ang hooks](https://code.claude.com/docs/en/hooks-guide) — Opisyal na Anthropic setup at testing walkthrough. Sinusuportahan ang configuration at diagnostics ng mambabasa, hindi pahayag na pinatakbo ng BIG CHANGE sa Claude Code. Galing sa hiwalay na sinuring lokal na implementation packet ang eksaktong limitadong Node script at settings.
- [Advanced setup ng Claude Code](https://code.claude.com/docs/en/setup) — Opisyal na installation at environment reference. Bersiyong 2.1.301 lamang ang naobserbahan sa paghahanda; hindi nito ginagawang minimum ang bersiyong iyon.
- [Paggamit ng datos ng Claude Code](https://code.claude.com/docs/en/data-usage) — Opisyal na data terms ayon sa account. Pinapasuri ito bago ipadala ang Git branch sa modelo; hindi naitatago ng filter at pagpapaikli ang sensitibong pangalan ng kliyente o insidente. Walang pangkalahatang privacy guarantee.
- [Pamahalaan nang mahusay ang gastos](https://code.claude.com/docs/en/costs) — Opisyal na account at model-usage guidance para sa interaktibong startup/resume checks. Walang model o network request ang lokal na script, pero maaaring gumamit ng plan, provider o API allowance ang aktuwal na Claude session. Walang fixed price o paid test na inaangkin.
- [Paano suriin ang context at ipagpatuloy ang Claude Code session](https://bigchange.ai/blog/claude-code-session-context-continue-guide) — Naunang BIG CHANGE article 414, para lamang sa contextual link at relationship classification. Tinutukoy nito ang umiiral na usapan at pagpapatuloy ng gawain; hindi ebidensiya ng hook implementation o direktang naunang artikulo ng isang dated event.