Brzi sažetak: Claude Code hookovi su skripte za automatizaciju koje se izvršavaju u određenim točkama životnog ciklusa tijekom AI sesija kodiranja, omogućujući programerima pokretanje prilagođenih naredbi, validaciju akcija, formatiranje koda, slanje obavijesti i provođenje pravila projekta. Ovi hookovi integriraju se s Claudeovim radnim tijekom kroz događaje kao što su SessionStart, PreToolUse i PostToolUse, podržavajući obrasce izvršavanja temeljene na naredbama, HTTP-u i upitima s konfigurabilnim vremenskim ograničenjima i ponašanjem kod izlaznog koda.
Claude Codeov sustav hookova transformira AI asistenta za kodiranje iz korisnog alata u potpuno automatizirano razvojno okruženje. Većina programera ne shvaća opseg kontrole dostupne putem hookova.
Stvar je u tome što hookovi nisu samo za pokretanje skripti nakon uređivanja datoteka. Oni pružaju točke presretanja kroz cijeli proces donošenja odluka Claudea. Prije nego što izvrši naredbu. Nakon što poziv alata ne uspije. Kada mu je potrebno dopuštenje. Čak i prije obrade korisničkih upita.
Ovaj vodič pokriva sve što pruža službena dokumentacija, plus praktične obrasce koje rasprave zajednice otkrivaju da zapravo rade u produkcijskim okruženjima.
Što Claude Code hookovi zapravo rade
Prema službenoj dokumentaciji Claude Code, hookovi su korisnički definirane shell naredbe, HTTP endpointi ili prompt injekcije koje se izvršavaju u određenim točkama Claude Codeovog životnog ciklusa. Primaju strukturirani JSON unos putem stdin-a i kontroliraju radni tijek kroz izlazne kodove ili HTTP odgovore.
Automatizacija ide dublje nego što većina vodiča sugerira. Hookovi mogu potpuno blokirati izvršavanje alata, ubaciti dodatni kontekst u Claudeovo razmišljanje, pokrenuti vanjske usluge i provoditi pravila validacije kojih se Claude mora pridržavati.
Postoje tri glavne vrste hookova:
- Command hookovi: Shell skripte koje komuniciraju putem stdout, stderr i izlaznih kodova
- HTTP hookovi: Daljinski endpointi koji primaju POST zahtjeve i vraćaju JSON odgovore
- Prompt hookovi: Dinamičke upute ubrizgane u Claudeov kontekst u određenim događajima
Svaki tip služi različitim obrascima automatizacije. Command hookovi obrađuju lokalnu validaciju i formatiranje. HTTP hookovi integriraju se s vanjskim uslugama i bazama podataka. Prompt hookovi mijenjaju Claudeovo ponašanje bez vanjskih procesa.
Životni ciklus hookova i sustav događaja
Službena dokumentacija definira više događaja hookova (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification i drugi) koji se aktiviraju tijekom Claude Codeovog tijeka izvršavanja. Razumijevanje kada se svaki aktivira određuje kakva je automatizacija moguća.
| Događaj | Kada se aktivira | Može blokirati |
|---|---|---|
| SessionStart | Kada se sesija započne ili nastavi | Ne |
| UserPromptSubmit | Kada pošaljete upit, prije nego što ga Claude obradi | Da |
| PreToolUse | Prije nego što se alat izvrši | Da |
| PermissionRequest | Kada se pojavi dijaloška kutija za dopuštenje | Da |
| PostToolUse | Nakon što poziv alata uspije | Ne |
| PostToolUseFailure | Nakon što poziv alata ne uspije | Ne |
| Notification | Kada Claude Code pošalje obavijest | Ne |
| SubmitMessage | Kada Claude pošalje poruku korisniku | Ne |
| ContextCompaction | Kada se približi kapacitet prozora konteksta | Ne |
Sposobnost blokiranja je najvažnija. PreToolUse hookovi mogu spriječiti opasne operacije prije nego što se izvrše. Izlazni kod 1 blokira akciju. Izlazni kod 0 dopušta je. Izlazni kod 2 potiče Claudea na ponovno razmatranje.
Ali čekajte. PostToolUse hookovi ne mogu poništiti akcije jer se alat već izvršio. Ovo ograničenje oblikuje kako se logike validacije strukturiraju. Kritičke provjere pripadaju u PreToolUse. Čišćenje i formatiranje pripadaju u PostToolUse.
Pregledajte AI Tool Perks tijekom postavljanja Claude Code
Ako radite s Claude Code hookovima, možda birate i druge AI alate oko svog radnog tijeka. Get AI Perks prikuplja početne kredite i popuste na softver za AI i cloud alate na jednom mjestu. Platforma uključuje 200+ ponuda, s uvjetima za perk i smjernicama za preuzimanje za svaku od njih.
Tražite Claude ili druge AI Tool Perks?
Provjerite Get AI Perks za:
- pregled ponuda za Claude i druge AI alate
- usporedbu uvjeta za perk prije prijave
- pronalazak početnih popusta na cijeli vaš sklop alata
👉 Posjetite Get AI Perks kako biste istražili trenutne perkove za AI softver.
Konfiguracija i struktura datoteka
Hookovi se definiraju u datoteci .claude/settings.json unutar projekta. Shema konfiguracije podržava globalne hookove i matcher-e specifične za alat koji filtriraju kada se hookovi izvršavaju.
Osnovna struktura command hooka:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Varijabla ${file} proširuje se na stvarni put datoteke iz unosa alata. Prema službenoj dokumentaciji, hookovi podržavaju ova proširenja varijabli u poljima command i args.
Hijerarhija lokacije hookova
Claude Code provjerava više lokacija za definicije hookova, s jasnim redoslijedom prioriteta:
- Na razini projekta: .claude/settings.json u trenutnom radnom prostoru
- Na razini korisnika: ~/.claude/settings.json za sve sesije
- Osigurano putem dodatka: Hookovi koji su ugrađeni u instalirane dodatke
Projektni hookovi zamjenjuju korisničke hookove za isti događaj. Ovo omogućuje specifična pravila formatiranja projekta uz zadržavanje globalnih rukovatelja obavijesti.
Matcher uzorci za selektivno izvršavanje
Sustav matcher-a filtrira hookove na specifične alate ili uvjete. Bez matcher-a, hookovi se aktiviraju za svaku pojavu njihovog događaja.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Polje pathPattern prihvaća glob sintaksu. Polje toolName uspoređuje se s ugrađenim alatima Claudea kao što su edit_file, execute_command, read_file i create_directory.
Rasprave zajednice otkrivaju da kombinacije matcher-a rade s AND logikom. Svi navedeni matcher-i moraju se podudarati da bi se hook izvršio.
Command hookovi: Integracija Shell skripti
Command hookovi izvršavaju shell naredbe ili skripte sa strukturiranim JSON unosom. Oni predstavljaju najčešći tip hookova za lokalnu automatizaciju.
Službena dokumentacija navodi da command hookovi primaju JSON putem stdin-a sa sljedećom strukturom:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Skripte parsiraju ovaj unos kako bi donijele odluke. Python hook za validaciju bi mogao izgledati ovako:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Cannot edit protected files”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Izlazni kod 0 dopušta operaciju. Izlazni kod 1 ga blokira i prikazuje stderr poruku Claudeu. Izlazni kod 2 pokreće posebno ponašanje ovisno o događaju.
Ponašanje izlaznog koda 2
Prema službenoj referentnoj dokumentaciji hookova, izlazni kod 2 ima značenje specifično za događaj (PreToolUse: blokira i potiče na ponovno razmatranje; UserPromptSubmit: pruža kontekst bez blokiranja; PermissionRequest: blokira dopuštenje):
- PreToolUse: Blokira alat i potiče Claudea na ponovno razmatranje sa stderr porukom kao kontekstom
- UserPromptSubmit: Pruža stderr izlaz kao dodatni kontekst bez blokiranja
- PermissionRequest: Blokira odobrenje dopuštenja
Ovo stvara srednji put između tvrdog blokiranja i dopuštanja. Claude dobiva povratne informacije zašto akcija može biti problematična i može prilagoditi svoj pristup.
Asinkroni Command hookovi
Zastava async: true pokreće hookove u pozadini bez blokiranja Claudeovog radnog tijeka. Ovo je važno za spore operacije kao što su obavijesti o implementaciji ili prikupljanje metrika.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Kada se aktivira async hook, Claude Code pokreće proces i nastavlja odmah. Polje timeout postavlja maksimalno vrijeme izvršavanja u sekundama. Ako nije navedeno, async hookovi koriste zadani timeout od 10 minuta.
Iskreno rečeno: async hookovi ne mogu blokirati operacije jer se pokreću nakon što Claude nastavi. Oni rade za logiranje, obavijesti i čišćenje—ne za validaciju.
HTTP hookovi: Integracija vanjskih usluga
HTTP hookovi šalju JSON payload-e na udaljene endpoint-e i parsiraju odgovore za kontrolu odluka. Omogućuju integraciju s uslugama za validaciju, bazama podataka i alatima trećih strana.
Osnovna konfiguracija HTTP hookova:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Struktura payload-a odgovara ulazu command hooka, ali stiže kao HTTP POST tijelo. Odgovor određuje sljedeći korak Claudea.
Obrada HTTP odgovora
Prema službenoj dokumentaciji, HTTP hookovi tumače odgovore na temelju statusnog koda i sadržaja tijela:
| Statusni kod | Učinak | Izvor poruke |
|---|---|---|
| 200 | Dopusti operaciju | Tijelo odgovora (opcionalno) |
| 400 | Blokiraj operaciju | Tijelo odgovora prikazano Claudeu |
| 500 | Pogreška hooka, dopusti operaciju | Logirano, ali nije prikazano Claudeu |
| Drugo | Dopusti operaciju | Kvar hooka ne blokira radni tijek |
Tijelo odgovora može sadržavati polje poruke koje Claude vidi kao kontekst. Ovo omogućuje uslugama za validaciju da objasne zašto je operacija blokirana.
Interopolacija varijabli okruženja
HTTP hookovi podržavaju sintaksu ${VAR} u url, headers i drugim tekstualnim poljima. Varijable se proširuju iz okruženja gdje se Claude Code pokreće.
Prema službenoj MCP dokumentaciji, proširenje varijabli okruženja uključuje sintaksu zadanog fallback-a: ${VAR:-default} proširuje se na VAR ako je postavljen, inače koristi zadanu vrijednost.
Sigurnosno ograničenje: Prema GitHub issue #28044, HTTP hookovi mogu pristupiti samo varijablama okruženja eksplicitno navedenim u polju konfiguracije allowedEnvVars. Ovo sprječava slučajno izlaganje vjerodajnica.
Prompt hookovi: Injekcija konteksta
Prompt hookovi ubacuju dinamičke upute u Claudeov kontekst u određenim događajima. Oni mijenjaju ponašanje bez vanjskih procesa ili API poziva.
| { “event”: “SessionStart”, “prompt”: “Radite na TypeScript projektu. Uvijek koristite stroge null provjere i preferirajte async/await umjesto promises.” } |
Ubačeni tekst postaje dio Claudeovih sistemskih uputa za tu sesiju. Prompt hookovi također mogu koristiti predloške varijabli koje se proširuju na temelju podataka događaja.
Generiranje dinamičkih upita
Prema službenoj dokumentaciji, prompt hookovi podržavaju polja naredbi koje generiraju dinamičke upite:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Naredba prima standardni JSON unos putem stdin-a i izlazni tekst upita na stdout. Ovo omogućuje generiranje uputa svjesnih konteksta na temelju stanja projekta.
Hookovi temeljeni na agentima
Agent hookovi specificiraju podagenta koji obrađuje događaj umjesto izravne prompt injekcije. Podagent prima kontekst o događaju i može izvršiti višestupanjsko razmišljanje.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Poziv alata nije uspio. Analizirajte grešku i predložite popravke.” } |
Nazvani podagent mora biti definiran u konfiguraciji projekta. Agent hookovi omogućuju složenu logiku odluka koju jednostavna prompt injekcija ne može pružiti.
Praktični obrasci hookova
Rasprave zajednice i službeni primjeri otkrivaju specifične obrasce automatizacije koji pouzdano rade u produkciji.
Automatsko formatiranje koda nakon uređivanja
Najčešći obrazac automatski formatira kod nakon što Claude uredi datoteke:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Varijabla ${toolInput.path} proširuje se na put izmijenjene datoteke. PostToolUse osigurava da se formatiranje događa nakon uspješnih uređivanja, ali ne blokira Claudeov radni tijek.
Blokiranje izmjena zaštićenih datoteka
PreToolUse hookovi provode pravila zaštite datoteka:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Skripta provjerava ciljni put u odnosu na zaštićene uzorke i izlazi s kodom 1 kako bi blokirala zabranjena uređivanja.
Primanje obavijesti kada Claude treba unos
Prema službenom vodiču za radni tijek, Notification hookovi mogu pokrenuti desktop upozorenja ili slati poruke vanjskim uslugama:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Ovo se aktivira kad god Claude Code pošalje obavijest, uključujući čekanje korisničkog unosa ili nakon završetka zadatka.
Ponovno ubrizgavanje konteksta nakon sažimanja
ContextCompaction hookovi vraćaju važan kontekst kada se prozor razgovora napuni:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Izlaz naredbe se ubacuje natrag u Claudeov kontekst nakon što sažimanje ukloni starije poruke. Ovo sprječava gubitak kritičnih uputa specifičnih za projekt.
Revizija promjena konfiguracije
Pratite kada Claude mijenja konfiguracijske datoteke:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Asinkrono izvršavanje sprječava blokiranje Claudea dok se git operacije ne završe. Ovo stvara zapisnik revizije promjena konfiguracije bez ručnog staginga.
JSON izlaz i kontrola odluka
Command hookovi mogu izlaziti strukturirani JSON kako bi pružili detaljne povratne informacije izvan jednostavnih izlaznih kodova. Prema službenom referenci, JSON izlaz omogućuje višestruke odgovore koje Claude tumači za donošenje odluka.
| { “allowed”: false, “message”: “Ova datoteka je zaštićena pravilima tima”, “suggestion”: “Stvorite novu datoteku umjesto toga u src/features/” } |
Polje allowed kontrolira hoće li se operacija nastaviti. Poruka se prikazuje Claudeu kao kontekst. Polje suggestion pruža alternativne pristupe.
Da bi hookovi izlazili JSON, oni moraju:
- Napisati validan JSON na stdout
- Izlaziti s kodom 0 (za dopušteno) ili 1 (za blokirano)
- Uključiti barem polje allowed boolean
Claude Code parsira JSON i koristi ga za poboljšanje povratne petlje. Izlazni kodovi još uvijek određuju primarnu odluku, ali JSON pruža bogatiji kontekst.
Referenca polja ulaza hookova
Svi hookovi primaju JSON objekt putem stdin-a s uobičajenim poljima plus podacima specifičnim za događaj. Razumijevanje potpune sheme omogućuje sofisticiraniju logiku hookova.
Uobičajena ulazna polja
Svaki hook prima ova osnovna polja:
- event: Naziv događaja hooka (npr. “PreToolUse”)
- sessionId: Jedinstveni identifikator trenutne Claude sesije
- turnId: Identifikator trenutnog okreta razgovora
- timestamp: ISO 8601 vremenska oznaka kada se događaj aktivirao
Polja događaja alata
PreToolUse, PostToolUse i PostToolUseFailure događaji uključuju:
- toolName: Naziv alata koji se poziva (edit_file, execute_command, itd.)
- toolInput: Objekt koji sadrži ulazne parametre alata
- toolResponse: Izlazni podaci alata (samo PostToolUse)
- error: Pojedinosti o pogrešci uključujući poruku i kod (samo PostToolUseFailure)
Struktura toolInput varira ovisno o alatu. Za edit_file sadrži path i content. Za execute_command sadrži command i args.
Polja događaja dopuštenja
PermissionRequest događaji uključuju:
- permissionType: Vrsta traženog dopuštenja (file_write, command_execute, itd.)
- requestedAction: Specifična akcija koja zahtijeva dopuštenje
- resourcePath: Put datoteke ili identifikator resursa na koji se odnosi
MCP Tool hookovi
Prema službenoj referenci hookova, hookovi se mogu podudarati s alatima protokola za kontekst modela (MCP) pomoću polja mcpTool matcher-a. Ovo omogućuje izvršavanje hookova kada Claude koristi vanjske alate koje pružaju MCP serveri.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Vrijednost mcpTool podudara se s nazivom alata u formatu server-name/tool-name. Ovo omogućuje logiku validacije za SQL upite, API pozive ili druge vanjske operacije.
Zahtjevi za značajke na GitHubu ukazuju na rastući interes za dubljom MCP integracijom, uključujući hookove koji mogu pregledavati obavijesti MCP servera i reagirati na vanjske događaje.
Sigurnosna razmatranja
Hookovi se izvršavaju s istim dopuštenjima kao i sam Claude Code. Ovo stvara sigurnosne implikacije za okruženja s više korisnika i dijeljene konfiguracije.
Sandbox za izvršavanje naredbi
Prema GitHub issue #28044, HTTP hookovi prolaze kroz sandbox proxy koji ograničava mrežni pristup i filtrira varijable okruženja. Command hookovi nemaju takva ograničenja—izvršavaju se s punim shell pristupom.
Dokumentacija preporučuje ove prakse:
- Nikada ne pohranjujte vjerodajnice u naredbe hookova
- Koristite varijable okruženja za osjetljive podatke
- Validirajte sve unose iz ${…} proširenja
- Implementirajte ograničenja vremenskog isteka za vanjske usluge
- Koristite async hookove za nekritične operacije kako biste izbjegli blokiranje u slučaju grešaka
Izolacija izvršavanja hookova
Korisnički hookovi u ~/.claude/settings.json primjenjuju se na sve projekte. Ovo stvara rizike kada se radi preko različitih granica povjerenja. Projektni hookovi zamjenjuju korisničke hookove, ali ih ne mogu u potpunosti onemogućiti.
Izbornik /hooks u Claude Codeu prikazuje sve aktivne hookove za trenutnu sesiju. Pregledavanje ovog popisa prije rada na osjetljivim projektima pomaže identificirati potencijalne sigurnosne probleme.
Otklanjanje grešaka i rješavanje problema
Kvarovi hookova ne uvijek se jasno prikazuju u Claudeovom razgovoru. Službena dokumentacija pruža nekoliko pristupa za otklanjanje grešaka.
Logovi izvršavanja hookova
Claude Code logira izvršavanje hookova u izlaz za debugiranje sesije. Prema vodiču za rješavanje problema, omogućavanje debug logiranja otkriva:
- Koji su se hookovi podudarali za svaki događaj
- JSON unos poslan svakom hooku
- Stdout i stderr izlaz iz hook procesa
- Izlazne kodove i vrijeme izvršavanja
- HTTP kodove odgovora i tijela za HTTP hookove
Omogućite debug logiranje postavljanjem CLAUDE_DEBUG=1 u okruženju prije pokretanja Claude Code.
Neovisno testiranje hookova
Command hookovi mogu se testirati izvan Claude Code ručnom izradom JSON unosa:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Ovo provjerava logiku hookova bez pokretanja stvarnih Claude operacija. Izlazni kod i stdout/stderr izlaz bi trebali odgovarati očekivanom ponašanju.
Uobičajeni kvarovi hookova
Rasprave zajednice identificiraju ove česte probleme:
- Greške vremenskog isteka: Zadano 10-minutno vrijeme isteklo prekratko za spore operacije—povećajte s poljem timeout
- Greške proširenja puta: Varijable poput ${file} nedefinirane za događaje koji ne uključuju kontekst datoteke
- Greške dopuštenja: Hook skripte nemaju prava izvršavanja—pokrenite chmod +x script.sh
- Greške parsiranja JSON-a: Nepravilni JSON izlaz iz hookova—validirajte s jq prije vraćanja
- Nedostupnost varijabli okruženja: Varijable nisu propagirane na hook proces—provjerite Claude Code okruženje
Implikacije performansi hookova
Sinkroni hookovi blokiraju Claudeov radni tijek do završetka. Zadano 10-minutno vremensko ograničenje sprječava beskonačno vješanje, ali čak i kratka kašnjenja se nakupljaju kroz više operacija.
Praktičari izvješćuju da jednostavni hookovi za validaciju imaju zanemariv utjecaj na performanse. Hookovi za formatiranje datoteka uzrokuju primjetan, ali prihvatljiv utjecaj na performanse. Pozivi vanjskih API-ja mogu stvoriti trenje u radnom tijeku. Operacije teških izračuna imaju koristi od asinkronog izvršavanja.
Grupisanje hookova
Više hookova može se podudarati s istim događajem. Prema referentnoj dokumentaciji, hookovi se izvršavaju sekvencijalno redoslijedom definicije. Ako bilo koji hook blokira operaciju, preostali hookovi se ne izvršavaju.
Ovo je važno za performanse. Pet sinkronih hookova od 200ms svaki dodaje jednu sekundu po događaju. Kombiniranje povezanih validacija u jedan hook smanjuje režiju.
Napredni obrasci
Osim osnovne automatizacije, hookovi omogućuju sofisticiranu prilagodbu radnog tijeka.
Stanje lanca hookova
Hookovi mogu održavati stanje između izvršavanja koristeći datoteke ili baze podataka. PostToolUse hook može zabilježiti uspješne operacije koje PreToolUse hook kasnije provjerava:
| #!/bin/bash # Zabilježite uspješna uređivanja echo “${toolInput.path}” >> .claude/edit-history.txt |
Prateći PreToolUse hook može provjeriti ovu povijest kako bi spriječio suvišne operacije ili proveo ograničenja redoslijeda.
Aktivacija hookova pod uvjetom
Varijable okruženja kontroliraju ponašanje hookova u vrijeme izvršavanja. Postavljanje CLAUDE_SKIP_HOOKS=1 onemogućuje hookove za hitne situacije.
Sami hookovi mogu provjeriti zastavice okruženja:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Primijeni strogu validaciju exit 1 fi exit 0 |
Ovo omogućuje ponašanje u razvojnom načinu rada nasuprot produkcijskom načinu rada bez promjena konfiguracije.
Višestupanjska validacija
PreToolUse hookovi mogu implementirati višeslojnu validaciju gdje izlazni kod 2 omogućuje Claudeu da nastavi s upozorenjima:
- Tvrdi kvarovi (izlaz 1): Blokiraj opasne operacije
- Meka upozorenja (izlaz 2): Upozori Claudea na ponovno razmatranje
- Prođi s kontekstom (izlaz 0 + JSON): Pruži dodatne informacije
Ovo stvara spektar validacije koji je suptilniji od binarnog dopušteno/odbijeno.
Integracija s CI/CD
Prema službenoj dokumentaciji za integraciju platforme, Claude Code se pokreće u CI/CD okruženjima za automatiziranu reviziju koda i triage problema. Hookovi proširuju ovu automatizaciju.
GitHub Actions radni tijekovi mogu definirati hookove koji provode timska pravila tijekom automatiziranih sesija:
| -- name: Pokreni Claude Code sa strogim hookovima env: STRICT_MODE: 1 run: | claude “Pregledaj ovaj PR i predloži poboljšanja” |
Zastava STRICT_MODE aktivira uvjetnu logiku validacije u hook skriptama. Ovo osigurava da automatizirane sesije slijede rigoroznija pravila od interaktivnog razvoja.
Generiranje zapisa revizije
PostToolUse hookovi u CI okruženjima stvaraju detaljne zapise revizije svih Claude operacija:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Logiranje u pozadini ne utječe na performanse, ali pruža potpunu povijest operacija za usklađenost i otklanjanje grešaka.
Izbornik /hooks
Claude Code pruža /hooks naredbu koja prikazuje sve aktivne hookove za trenutnu sesiju. Prema službenoj dokumentaciji, ovaj izbornik prikazuje:
- Vrsta događaja hooka
- Matcher uzorci
- Naredba ili URL endpoint
- Je li hook asinkron
- Izvor konfiguracije (projekt, korisnik ili dodatak)
Odabir hooka prikazuje njegovu potpunu konfiguraciju i omogućuje privremeno onemogućavanje za trenutnu sesiju.
Onemogućavanje ili uklanjanje hookova
Hookovi se mogu onemogućiti bez uklanjanja konfiguracije dodavanjem “enabled”: false definiciji hooka. Ovo čuva konfiguraciju, ali sprječava izvršavanje.
Da biste trajno uklonili hook, izbrišite njegov unos iz odgovarajuće datoteke settings.json. Promjene stupaju na snagu prilikom ponovnog pokretanja sljedeće sesije ili prilikom pokretanja /reload.
Hookovi u vještinama i agentima
Prema službenoj dokumentaciji, hookovi definirani unutar konfiguracija vještina ili podagenata primjenjuju se samo kada se ta vještina ili agent izvrši. Ovo omogućuje specijaliziranu automatizaciju za specifične radne tijekove.
Agent za otklanjanje grešaka može uključivati hookove koji logiraju sve pozive alata:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Ovi hookovi se aktiviraju samo tijekom debugger agent sesija, ne tijekom normalnog rada Claude Code.
Pozivanje skripti po putanji
Naredbe hookova podržavaju i relativne i apsolutne putanje. Relativne putanje rješavaju se iz korijena projekta gdje se Claude Code pokreće.
Najbolje prakse iz rasprava zajednice:
- Spremite hook skripte u direktorij .claude/hooks/
- Koristite opisne nazive: validate-typescript.sh a ne hook1.sh
- Učinite skripte izvršnima: chmod +x .claude/hooks/*.sh
- Uključite shebang redak: #!/usr/bin/env bash ili #!/usr/bin/env python3
- Dodajte rukovanje greškama s set -e u bash skriptama
Buduće mogućnosti hookova
Zahtjevi za značajke na GitHubu otkrivaju planirana i tražena poboljšanja hookova:
- Inline skript hookovi: Definirajte logiku hookova izravno u settings.json bez vanjskih datoteka
- MCP alatna integracija: Pozovite MCP server alate iz hookova umjesto shell naredbi
- Suradnja više agenata: Hookovi koji koordiniraju između Claude instanci na različitim strojevima
- Poboljšano tipiziranje: TypeScript definicije tipova za sheme ulaza/izlaza hookova
Prema GitHub issue #4274, zahtjev za integriranim tipovima hookova (MCP alat, inline skripta, API poziv) ima za cilj pojednostaviti konfiguraciju i poboljšati korisničko iskustvo programera.
Često postavljana pitanja
Mogu li hookovi spriječiti Claudea da izvršava opasne naredbe?
Da. PreToolUse hookovi mogu blokirati izvršavanje bilo kojeg alata izlazom s kodom 1. Ovo uključuje uređivanje datoteka, izvršavanje naredbi i pozive MCP alata. Hook prima potpuni unos alata i može provjeriti prema bilo kojem kriteriju prije nego dopusti operaciju.
Kako da otklonim grešku hooka koji ne radi?
Omogućite debug logiranje s CLAUDE_DEBUG=1 prije pokretanja Claude Code. Provjerite logove sesije za pojedinosti izvršavanja hookova uključujući koje su se hookovi podudarali, JSON unos poslan, stdout/stderr izlaz i izlazne kodove. Testirajte hookove neovisno slanjem uzorka JSON-a hook skripti.
Rade li hookovi sa svim Claude Code platformama?
Hookovi rade u CLI, desktop aplikaciji i VS Code ekstenziji. Prema službenoj dokumentaciji, hookovi se izvršavaju gdje god se Claude Code pokreće s pristupom datotečnom sustavu. Preglednik-bazirani Claude i mobilne aplikacije ne podržavaju hookove zbog ograničenja sandboxinga.
Mogu li hookovi mijenjati Claudeove odgovore ili ponašanje?
Prompt hookovi ubacuju upute koje utječu na Claudeovo ponašanje. Agent hookovi delegiraju rukovanje događajima specijaliziranim podagentima. Međutim, hookovi ne mogu izravno mijenjati generirani tekst ili proces razmišljanja Claudea—rade pružanjem konteksta i blokiranjem operacija.
Koja je razlika između async i sync hookova?
Sinkroni hookovi blokiraju Claudeov radni tijek do završetka ili vremenskog isteka. Asinkroni hookovi rade u pozadini bez blokiranja. Sync hookovi mogu spriječiti operacije putem izlaznih kodova. Async hookovi ne mogu blokirati jer Claude nastavlja prije nego što hook završi. Koristite async za logiranje i obavijesti, sync za validaciju.
Kako da dijelim hookove s timom?
Dodajte datoteku .claude/settings.json u kontrolu verzija. Projektni hookovi primjenjuju se na sve članove tima koji kloniraju spremište. Za politike cijele organizacije, timovi mogu održavati zajedničku datoteku korisničkih postavki koju članovi kopiraju u ~/.claude/settings.json.
Mogu li HTTP hookovi pozivati interne API-je iza vatrozida?
Da, ako Claude Code radi u okruženju s mrežnim pristupom tim API-jima. HTTP hookovi šalju standardne POST zahtjeve sa stroja koji pokreće Claude Code. Korporativni vatrozidi i VPN-ovi primjenjuju se normalno. Sandbox proxy spomenut u dokumentaciji kontrolira izlaganje varijabli okruženja, a ne mrežnog usmjeravanja.
Povećavaju li hookovi korištenje tokena Claude Code?
Prompt hookovi ubacuju tekst u Claudeov kontekst, što troši tokene. Command i HTTP hookovi ne utječu izravno na korištenje tokena, ali njihov izlaz (poruke o greškama, prijedlozi) postaje dio konteksta razgovora. Izlazni kod 2 s objašnjavajućim porukama dodaje više konteksta nego izlazni kod 1 s jednostavnim blokiranjem.
Zaključak
Claude Code hookovi transformiraju AI asistenta iz moćnog alata u potpuno automatiziranu razvojnu platformu. Sustav događaja pruža točke presretanja kroz Claudeov radni tijek—od inicijalizacije sesije do sažimanja konteksta.
Command hookovi obrađuju lokalnu validaciju i formatiranje. HTTP hookovi integriraju vanjske usluge i baze podataka. Prompt hookovi mijenjaju ponašanje ubrizgavanjem konteksta. Zajedno, oni omogućuju obrasce automatizacije koji provode timska pravila, održavaju kvalitetu koda i integriraju se s postojećom razvojnom infrastrukturom.
Sustav matcher-a filtrira hookove na specifične alate i uzorke datoteka. Izlazni kodovi i JSON izlaz kontroliraju protok odluka. Asinkrono izvršavanje sprječava blokiranje sporih operacija. Potpuna shema konfiguracije podržava sve, od jednostavnog automatskog formatiranja do složene višestupanjske validacije.
Započnite s osnovnim PostToolUse hookovima za formatiranje koda. Dodajte PreToolUse validaciju kako se pravila pojavljuju. Eksperimentirajte s prompt hookovima za modifikaciju ponašanja. Izgradite HTTP integracije za provedbu na cijelom timu.
Provjerite službenu dokumentaciju Claude Code za potpunu referencu hookova i ažuriranu shemu konfiguracije kako novi kapaciteti budu objavljeni.
