Tambahkan hook konteks proyek yang dibatasi saat sesi Claude Code dimulai

Hook Claude Code adalah perintah yang dijalankan aplikasi pada titik tertentu dalam sesi. Panduan ini menambahkan satu SessionStart hook khusus proyek yang membaca cabang Git saat ini dan memberikan satu baris konteks singkat saat Anda memulai atau melanjutkan percakapan. Panduan mengikuti referensi hook Anthropic terkini, yang diperiksa pada 19 Oktober 2026. BIG CHANGE memeriksa skrip langsung dengan Node dan memeriksa JSON pengaturan; kami tidak menjalankan hook Claude Code atau menguji jawaban model.

Perubahan utama

• Apa yang berubah: Hook SessionStart proyek ini memberikan satu baris singkat tentang cabang Git ketika Claude Code memulai atau melanjutkan percakapan.
• Mengapa penting: Cabang saat ini masuk ke konteks sesi saat mulai atau dilanjutkan tanpa perlu ditempel secara manual setiap kali.
• Yang perlu diperhatikan: Konteks tidak menegakkan aturan atau menjamin jawaban model. Periksa pengiriman konteks saat mulai dan melanjutkan sesi di proyek tepercaya Anda sendiri.

Sebelum memasang

Gunakan proyek Git yang boleh Anda ubah. Claude Code, Node.js, dan Git harus tersedia di terminal yang sama, dan Anda perlu izin mengedit berkas proyek .claude/settings.json. Periksa node --version, git --version dan claude --version. Komputer persiapan memiliki Claude Code 2.1.301 dan Node 24.19.0; versi yang teramati ini bukan persyaratan minimum.

Periksa nama cabang sebelum mengirimkannya ke model. Nama cabang dapat memuat nama klien, tiket, atau insiden. Penyaringan karakter dan pemendekan teks tidak menghilangkan maknanya. Pasang contoh ini hanya jika nama cabang disetujui untuk konteks model. Jika tidak, ubah skrip agar menghasilkan status yang disetujui tanpa informasi sensitif, lalu tinjau perubahan sebelum pemasangan. Dokumentasi penggunaan data Anthropic menjelaskan penanganan data oleh layanan; terapkan juga izin proyek Anda.

Perintah hook berjalan dengan izin pengguna Anda. Periksa hook proyek dan pengguna yang sudah ada, kebijakan organisasi, dan seluruh skrip sebelum mengaktifkannya. Pengaturan proyek dapat dimasukkan ke repositori; .claude/settings.local.json tetap lokal. Contoh ini menggunakan berkas pengaturan proyek agar konfigurasi hanya berlaku untuk proyek tersebut.

Pasang kedua berkas

1. Buat .claude/hooks/ di dalam proyek. Simpan seluruh blok ini sebagai .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);
}

Proses anak Git memiliki batas waktu 1,5 detik dan penyangga keluaran 4.096 byte. Hasil cabang kosong, seperti pada detached HEAD, menjadi detached HEAD. Jalur proyek yang tidak ada atau kegagalan Git menghasilkan diagnostik stderr singkat dan kode keluar 1.

2. Buka berkas yang sudah ada .claude/settings.json. Gabungkan entri hooks.SessionStart di bawah dengan pengaturan dan kelompok hook lainnya; pertahankan entri yang sudah ada. Blok menampilkan keseluruhan settings.example.json dari paket yang ditinjau. Jika berkas sudah memiliki entri SessionStart , tambahkan kelompok ini ke lariknya, bukan mengganti larik tersebut.

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

Matcher mencakup sesi baru dan sesi yang dilanjutkan. Anthropic juga mendokumentasikan clear, compact dan fork sebagai sumber SessionStart ; contoh ini sengaja tidak menyertakannya. Kolom args memilih bentuk exec: Claude Code memanggil node dengan jalur skrip proyek yang sudah diuraikan sebagai satu argumen, tanpa pengutipan atau penguraian shell. Di Windows, node.exe harus ditemukan sebagai berkas yang dapat dieksekusi; shim .cmd tidak cocok untuk bentuk exec. Batas waktu hook lima detik terpisah dari batas waktu Git 1,5 detik di skrip.

Periksa skrip, lalu Claude Code

3. Sebelum membuka Claude Code, jalankan skrip di terminal proyek dan bandingkan keluarannya dengan Git. Dalam PowerShell:

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

Dalam Bash:

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

Harapkan tepat satu baris stdout dari skrip, Current project branch: BRANCH, dengan BRANCH sebagai hasil Git setelah penyaringan karakter dan batas 80 karakter. Detached HEAD mencetak Current project branch: detached HEAD. Pemeriksaan langsung hanya membuktikan skrip lokal bekerja di terminal ini. Pada pemeriksaan persiapan kami, hasil cabang biasa cocok dengan Git; jalur proyek yang hilang dan tidak valid menghasilkan stdout kosong, diagnostik stderr, dan keluar 1. Kami meninjau batas nama panjang dan nilai cadangan detached HEAD dalam kode sumber, tetapi tidak menjalankan kasus tersebut.

4. Mulai proses interaktif Claude Code baru di proyek tepercaya dengan claude --debug-file STARTUP_PRIVATE_LOG, menggunakan jalur privat yang Anda kendalikan. Tinjau hook proyek dan pengguna sebelum menerima kepercayaan ruang kerja. Periksa log debug untuk peristiwa SessionStart dengan sumber startup, jalur skrip yang dipilih, status keluar, dan penanganan keluaran. Tanyakan kepada Claude konteks cabang yang diterimanya tanpa mengizinkannya memakai alat atau membaca Git sendiri. Bandingkan jawaban dan catatan debug dengan hasil langsung. Stdout hook masuk ke konteks Claude; tidak dijanjikan sebagai pesan pada antarmuka yang terlihat.
5. Keluar dari sesi tersebut. Lanjutkan dalam proses terpisah dengan claude --debug-file RESUME_PRIVATE_LOG --resume, lalu periksa peristiwa SessionStart resume dan ulangi pemeriksaan pertanyaan tanpa alat atau pembacaan ulang Git. Jaga kedua log debug tetap privat karena dapat mengungkap detail proyek. Proses noninteraktif -p atau SDK tidak memberikan permintaan kepercayaan ruang kerja yang sama dan dapat menjalankan hook repositori secara otomatis, jadi gunakan alur interaktif untuk pemeriksaan ini. Anthropic menyatakan pengamat berkas biasanya mendeteksi perubahan pengaturan hook, tetapi proses baru memberi pengujian mulai dan lanjut yang lebih jelas.

Jika pekerjaan proyek biasa kemudian mengubah cabang, ulangi pemeriksaan langsung dan sesi baru untuk melihat apakah barisnya berubah. Jangan mengubah cabang hanya untuk mengklaim panduan ini sudah diuji.

Jika tidak berjalan

Mulai dari hasil skrip langsung, lalu periksa penggabungan JSON, ejaan SessionStart , matcher startup|resume , jalur akar proyek, ketersediaan node dan git, kepercayaan ruang kerja, serta galat debug. Jika tidak ada CLAUDE_PROJECT_DIR , skrip mencetak CLAUDE_PROJECT_DIR is unavailable ke stderr. Jalur proyek salah atau kegagalan Git mencetak Could not read the project branch; check Git and project path. Keduanya keluar 1 tanpa mencetak baris konteks. Kegagalan SessionStart bersifat diagnostik dan tidak memblokir; ini tidak dapat menjadi gerbang tindakan. Anthropic mendokumentasikan PreToolUse untuk mengendalikan tindakan alat, yaitu peristiwa berbeda yang memerlukan rancangan tersendiri yang ditinjau.

Skrip hanya menjalankan Git lokal tanpa permintaan jaringan atau panggilan model. Memulai Claude Code, melanjutkan, dan pemeriksaan pertanyaan dapat memakai kuota akun, penyedia, atau model Anda; panduan biaya Anthropic memuat ketentuan terkini. Panduan ini tidak menetapkan harga tetap atau melaporkan pengujian sesi berbayar.

Untuk tugas terpisah setelah percakapan dimulai, panduan kami untuk memeriksa konteks dan melanjutkan sesi Claude Code membahas pemeriksaan konteks dan kelanjutan. Panduan itu tidak mengonfigurasi hook awal ini.

Sumber dan bacaan lanjutan

• Anthropic, referensi hook Claude Code — Spesifikasi primer terkini diperiksa pada 19 Oktober 2026. Mendokumentasikan SessionStart sumber dan matcher, bentuk exec args, placeholder jalur, konteks stdout, pemuatan ulang pengaturan, kepercayaan, log debug, dan kegagalan yang tidak memblokir. Ini dokumentasi, bukan eksekusi hook oleh BIG CHANGE.
• Anthropic, otomatiskan tindakan dengan hook — Panduan resmi pengaturan dan pengujian hook. Skrip dan pengaturan tepat di atas adalah contoh BIG CHANGE yang dibatasi dan ditinjau untuk panduan ini, bukan hasil uji penyedia yang disalin.
• Anthropic, pengaturan Claude Code — Persyaratan instalasi dan lingkungan. Periksa instruksi platform terkini sebelum memakai contoh.
• Anthropic, penggunaan data Claude Code — Ketentuan penanganan data penyedia terkini untuk ditinjau sebelum mengirim informasi cabang ke konteks model; otorisasi proyek tetap keputusan terpisah.
• Anthropic, kelola biaya secara efektif — Panduan akun dan penggunaan terkini untuk pemeriksaan interaktif. Skrip Git lokal sendiri tidak meminta model atau jaringan.