Claude Code Hooks: Ο Πλήρης Οδηγός του Developer με Παραδείγματα Έτοιμα για Production

Claude Code Hooks: Ο Πλήρης Οδηγός του Προγραμματιστή με Παραδείγματα Έτοιμα για Παραγωγή

Το Claude Code γράφει εξαιρετικό κώδικα, αλλά παραμένει ένα πιθανοτικό σύστημα. Μπορείς να του ζητήσεις να τρέχει το Prettier μετά από κάθε επεξεργασία αρχείου. Μπορείς να βάλεις αυτή την οδηγία μέσα στο CLAUDE.md σου. Και μερικές φορές, απλά... το ξεχνά. Τα Claude Code hooks λύνουν αυτό το πρόβλημα, δίνοντάς σου ντετερμινιστικό, εγγυημένο έλεγχο πάνω σε ό,τι συμβαίνει πριν, κατά τη διάρκεια και μετά από κάθε ενέργεια που εκτελεί το Claude.

Τους τελευταίους μήνες ρυθμίζω hooks σε δεκάδες projects και έχουν γίνει αθόρυβα το πιο σημαντικό κομμάτι της εγκατάστασης του Claude Code μου. Αυτός ο οδηγός καλύπτει τα πάντα, από τα βασικά μέχρι ένα starter kit έτοιμο για παραγωγή, που μπορείς να ενσωματώσεις σε οποιοδήποτε project σήμερα κιόλας. Αν έχεις χρησιμοποιήσει το Claude Code μαζί με εργαλεία όπως το Cursor ή το Copilot, ξέρεις ήδη την αξία της προσαρμογής — τα hooks την πάνε ένα βήμα παραπέρα.

Τι είναι τα Claude Code Hooks (και γιατί να σε νοιάζουν);

Τα hooks του Claude Code είναι εντολές shell, HTTP endpoints ή LLM prompts που ορίζονται από τον χρήστη και εκτελούνται αυτόματα σε συγκεκριμένα σημεία του κύκλου ζωής του Claude Code. Σύμφωνα με την επίσημη τεκμηρίωση της Anthropic, σε αντίθεση με τις οδηγίες prompt που ο Claude μπορεί να αγνοήσει, τα hooks ενεργοποιούνται ντετερμινιστικά κάθε φορά, προσφέροντάς σου εγγυημένο έλεγχο στη μορφοποίηση, την ασφάλεια, τις ειδοποιήσεις και την αυτοματοποίηση της ροής εργασίας.

Το Πιθανοτικό Πρόβλημα

Το ζήτημα με τις οδηγίες του CLAUDE.md είναι το εξής: είναι προτάσεις, όχι συμβόλαια. Μπορείς να γράψεις «πάντα να τρέχεις npx prettier --write μετά την επεξεργασία αρχείων TypeScript» στο context του project σου, και ο Claude θα το ακολουθεί τις περισσότερες φορές. Όμως το «τις περισσότερες φορές» δεν αρκεί όταν επιβάλλεις τη μορφοποίηση κώδικα σε μια ομάδα, ή όταν μπλοκάρεις pushes στην παραγωγή, ή όταν καταγράφεις κάθε εντολή shell για έλεγχο ασφαλείας.

Αυτή είναι η βασική ένταση σε κάθε εργαλείο κωδικοποίησης με AI. Ο Claude είναι γλωσσικό μοντέλο και λειτουργεί με πιθανότητες. Η μηχανική του context μπορεί να κατευθύνει τη συμπεριφορά, αλλά δεν μπορεί να την εγγυηθεί.

Πώς τα Hooks λύνουν αυτό το πρόβλημα

Τα hooks παρακάμπτουν εντελώς το LLM. Είναι σενάρια shell, κλήσεις HTTP ή αξιολογήσεις AI που ενεργοποιούνται σε συγκεκριμένα γεγονότα του κύκλου ζωής: πριν από την εκτέλεση ενός εργαλείου (PreToolUse), μετά την ολοκλήρωσή του (PostToolUse), όταν εμφανίζεται μια ειδοποίηση, όταν ξεκινά μια συνεδρία ή όταν ο Claude σταματά. Σκεφτείτε τα σαν τα hooks του Git, αλλά για τον AI βοηθό κώδικά σας.

Υπάρχουν τέσσερις τύποι hooks: command (σενάρια shell), HTTP (αιτήματα POST σε webhook), prompt (αξιολογήσεις ναι/όχι του Claude σε έναν μόνο γύρο) και agent (δημιουργεί έναν υποπράκτορα με πρόσβαση σε εργαλεία). Θα αναλύσουμε τον καθένα παρακάτω· τα command hooks καλύπτουν περίπου το 90% όσων θα χρειαστείτε.

Πώς λειτουργούν τα Hooks του Claude Code: Η Ροή του Κύκλου Ζωής

Τα hooks του Claude Code εκτελούνται σε έναν καθορισμένο κύκλο ζωής: ένα συμβάν ενεργοποιείται (π.χ. PreToolUse), ο matcher ελέγχει αν το hook εφαρμόζεται, το σενάριο του hook εκτελείται και λαμβάνει JSON μέσω stdin, και ο κωδικός εξόδου καθορίζει τι θα συμβεί στη συνέχεια. Ο κωδικός εξόδου 0 σημαίνει συνέχεια, ο κωδικός εξόδου 2 σημαίνει αποκλεισμό της ενέργειας. Αυτή η ροή είναι η ίδια ανεξάρτητα από τον τύπο hook που χρησιμοποιείτε.

Συμβάν -> Αντιστοιχιστής -> Hook -> Κωδικός Εξόδου (Η Ροή 4 Βημάτων)

Δείτε πώς λειτουργεί κάθε εκτέλεση hook:

1. EVENT FIRES          e.g., PreToolUse(Write)
       |
2. MATCHER CHECKS       Does "Write" match the hook's matcher pattern?
       |
3. HOOK EXECUTES        Shell script runs, receives JSON via stdin
       |
4. EXIT CODE DECIDES    0 = proceed | 2 = block | other = error

Το JSON που φτάνει στο stdin περιέχει τα πάντα για το συμβάν: το tool_name, το tool_input (διαδρομή αρχείου, περιεχόμενο, εντολή) και τα μεταδεδομένα συνεδρίας. Το script σας διαβάζει αυτό το JSON, εκτελεί όποια λογική χρειάζεται και εξέρχεται με τον κατάλληλο κωδικό.

Για τα PreToolUse hooks, ο κωδικός εξόδου 2 είναι ο ισχυρός, καθώς αποκλείει εντελώς την ενέργεια και στέλνει το μήνυμα του stdout πίσω στον Claude ως ανατροφοδότηση. Ο Claude βλέπει το μήνυμά σας και μπορεί να προσαρμόσει την προσέγγισή του.

Εμβέλεια ρυθμίσεων: Χρήστης, Έργο και Τοπικό

Τα hooks βρίσκονται στο settings.json σε τρία επίπεδα:

Οι ρυθμίσεις έργου είναι οι πιο χρήσιμες για τις ομάδες. Τοποθετήστε τα hooks σας στο .claude/settings.json, κάντε commit, και κάθε προγραμματιστής της ομάδας αποκτά αυτόματα τα ίδια guardrails.

Το πεδίο if: Φιλτράρισμα λεπτής κοκκομετρίας

Από την έκδοση v2.1.85 του Claude Code, τα hooks υποστηρίζουν ένα πεδίο if που σας επιτρέπει να φιλτράρετε βάσει των ορισμάτων του εργαλείου, και όχι μόνο των ονομάτων των εργαλείων. Όπως τεκμηριώνεται στην αναφορά hooks της Anthropic, αυτό σημαίνει ότι μπορείτε να γράψετε ένα hook που ενεργοποιείται μόνο σε εντολές Bash που ταιριάζουν με το git push, αντί να εκτελείται σε κάθε μεμονωμένη κλήση της Bash.

{
  "matcher": "Bash",
  "if": "tool_input.command matches 'git push'",
  "hooks": [{ "type": "command", "command": "./scripts/check-branch.sh" }]
}

Αυτό αποτέλεσε μια σημαντική βελτίωση. Πριν από το if, είτε ταιριάζατε πολύ ευρέως (κάθε εντολή Bash) είτε κάνατε το φιλτράρισμα μέσα στο script σας (ακατάστατο).

Όλα τα Hook Events του Claude Code: Πίνακας Γρήγορης Αναφοράς

Το Claude Code παρέχει περισσότερα από 20 hook events σε όλο τον κύκλο ζωής του, όπως τεκμηριώνεται στο επίσημο hooks reference και στο changelog του Claude Code. Τα πιο συχνά χρησιμοποιούμενα είναι τα PreToolUse, PostToolUse, Notification και Stop, αλλά νεότερα events όπως το ConfigChange και το FileChanged ανοίγουν νέες δυνατότητες για προηγμένα patterns αυτοματισμού.

Ακολουθεί η πλήρης αναφορά:

Συμβουλή Pro: Θα χρησιμοποιείτε τα PreToolUse και PostToolUse για το 80% των hooks σας. Το SessionStart είναι το αμέσως πιο χρήσιμο, καθώς είναι ιδανικό για την έγχυση του project context που χρειάζεται το Claude στην αρχή κάθε συνεδρίας.

Οι 4 Τύποι Hooks του Claude Code Εξηγημένοι

Το Claude Code υποστηρίζει τέσσερις τύπους χειριστών (handlers) για hooks: τα command hooks εκτελούν σενάρια κελύφους (shell scripts), τα HTTP hooks στέλνουν αιτήματα POST σε διευθύνσεις URL, τα prompt hooks θέτουν στον Claude μια ερώτηση ναι/όχι, και τα agent hooks δημιουργούν έναν υπο-πράκτορα (subagent) με πρόσβαση σε εργαλεία. Σύμφωνα με την εμπειρία μας, τα command hooks καλύπτουν το 90% των περιπτώσεων χρήσης. Χρησιμοποιήστε τα HTTP για εξωτερικές ενσωματώσεις, και τα prompt και agent hooks για λεπτομερείς αποφάσεις που απαιτούν την κρίση της τεχνητής νοημοσύνης.

Command Hooks (Το βασικό εργαλείο)

Τα command hooks εκτελούν μια εντολή shell και χρησιμοποιούν τον κωδικό εξόδου για να καθορίσουν το αποτέλεσμα. Λαμβάνουν τα δεδομένα JSON του συμβάντος στο stdin.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.command' | grep -q 'rm -rf /' && exit 2 || exit 0"
      }]
    }]
  }
}

Αυτό θα χρησιμοποιείτε για μορφοποίηση, προστασία αρχείων, ειδοποιήσεις και για την περισσότερη αυτοματοποίηση. Γρήγορο, απλό και προβλέψιμο.

HTTP Hooks (Εξωτερικές Ενοποιήσεις)

Τα HTTP hooks στέλνουν ένα POST request σε ένα URL με το JSON του συμβάντος ως body. Ο κωδικός κατάστασης της απόκρισης καθορίζει το αποτέλεσμα (200 = συνέχεια, 403 = αποκλεισμός).

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "http",
        "url": "https://your-api.com/claude-webhook"
      }]
    }]
  }
}

Ιδανικά για την αποστολή συμβάντων σε Slack, Discord, PagerDuty ή σε ένα προσαρμοσμένο dashboard. Θα μπορούσατε επίσης να το χρησιμοποιήσετε για να κάνετε ερώτημα σε μια εξωτερική μηχανή πολιτικής πριν επιτρέψετε την εκτέλεση ενός εργαλείου.

Prompt Hooks (Αποφάσεις με τη Βοήθεια AI)

Τα prompt hooks διαβιβάζουν τα δεδομένα του συμβάντος στον ίδιο τον Claude για μια αξιολόγηση ναι/όχι σε έναν μόνο γύρο. Ο Claude επιστρέφει μια απάντηση JSON με "decision": "allow" ή "decision": "block", μαζί με τη συλλογιστική του.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "prompt",
        "prompt": "Is this bash command safe to run in a production environment? Consider: does it modify system files, delete data, or access sensitive credentials?"
      }]
    }]
  }
}

Χρησιμοποιήστε τα με φειδώ. Προσθέτουν καθυστέρηση (μια πλήρης κλήση LLM ανά εκτέλεση hook) και κόστος. Αλλά για πραγματικά υποκειμενικούς ελέγχους ασφαλείας, όπως «αυτή η μετάβαση βάσης δεδομένων φαίνεται καταστροφική;», δύσκολα θα βρείτε κάτι καλύτερο. Αν αναρωτιέστε για την εναλλαγή μοντέλων στο Claude Code, το μοντέλο που χρησιμοποιείται για τα prompt hooks ακολουθεί το τρέχον μοντέλο της συνεδρίας σας.

Agent Hooks (Επαλήθευση με τη βοήθεια εργαλείων)

Τα agent hooks εκκινούν έναν υποπράκτορα με πρόσβαση στα εργαλεία Read, Grep και Glob. Ο υποπράκτορας μπορεί να επιθεωρήσει τα αρχεία πριν λάβει την απόφασή του.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "agent",
        "prompt": "Check if the file being written follows the project's naming conventions and import patterns. Read .claude/CONVENTIONS.md for the rules."
      }]
    }]
  }
}

Αυτός είναι ο πιο ισχυρός τύπος hook, αλλά και ο πιο αργός. Κρατήστε τον για ελέγχους υψηλής σημασίας, όπου χρειάζεστε το πλαίσιο των αρχείων για να πάρετε μια σωστή απόφαση.

7 Παραδείγματα Claude Code Hooks έτοιμα για παραγωγή (Έτοιμα για αντιγραφή-επικόλληση)

Τα πιο χρήσιμα Claude Code hooks περιλαμβάνουν την αυτόματη μορφοποίηση με Prettier ή Black μετά την επεξεργασία αρχείων, τον αποκλεισμό εγγραφών σε προστατευμένα αρχεία, την αποστολή ειδοποιήσεων επιφάνειας εργασίας κατά την ολοκλήρωση εργασιών, την έγχυση του πλαισίου του έργου κατά την έναρξη μιας συνεδρίας, την εκτέλεση τεστ μετά από αλλαγές στον κώδικα, την επιβολή προστασίας κλάδων και τον έλεγχο της χρήσης όλων των εργαλείων. Χρησιμοποιώ παραλλαγές αυτών σε κάθε έργο τους τελευταίους τρεις μήνες.

Κάθε παρακάτω παράδειγμα είναι ένα πλήρες απόσπασμα settings.json που μπορείτε να προσθέσετε στο .claude/settings.json σας. Συλλογές της κοινότητας όπως το awesome-claude-code διαθέτουν ακόμη περισσότερα μοτίβα.

1. Αυτόματη μορφοποίηση κατά την αποθήκευση

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }]
  }
}

Αυτό εκτελείται μετά από κάθε Write ή Edit, εξάγει τη διαδρομή του αρχείου από το JSON του stdin και εκτελεί τον κατάλληλο formatter. Το exit 0 στο τέλος εξασφαλίζει ότι το hook δεν μπλοκάρει ποτέ — οι αποτυχίες μορφοποίησης δεν πρέπει να σταματούν τον Claude.

Συμβουλή: Προσθέστε *.go με gofmt και *.rs με rustfmt αν δουλεύετε σε πολλές γλώσσες.

2. Αποκλεισμός εγγραφών σε προστατευόμενα αρχεία

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\.local|package-lock\\.json|yarn\\.lock|pnpm-lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: This file is protected. Edit it manually.\"}' && exit 2"
      }]
    }]
  }
}

Ο κωδικός εξόδου 2 αποκλείει την ενέργεια και στέλνει το μήνυμα JSON πίσω στον Claude. Ο Claude βλέπει την ανατροφοδότηση και προσαρμόζεται· συνήθως θα σας πει ότι ήθελε να τροποποιήσει το αρχείο και θα σας ζητήσει να το κάνετε χειροκίνητα. Το πεδίο if εμποδίζει την ενεργοποίηση αυτού σε κάθε μεμονωμένο Write.

3. Ειδοποίηση επιφάνειας εργασίας κατά την ολοκλήρωση

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Claude Code task finished\"' /dev/stdin); if [ \"$(uname)\" = 'Darwin' ]; then osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\"; else notify-send 'Claude Code' \"$MSG\"; fi; exit 0"
      }]
    }]
  }
}

Λειτουργεί σε macOS (osascript) και Linux (notify-send). Ο κενός ανιχνευτής σημαίνει ότι ενεργοποιείται για όλες τις ειδοποιήσεις. Αυτό είναι πραγματικά χρήσιμο όταν ξεκινάς μια χρονοβόρα εργασία και αλλάζεις σε άλλο παράθυρο.

4. Έγχυση πλαισίου κατά την έναρξη της συνεδρίας

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null || echo none)\"' | Last commit: '\"$(git log --oneline -1 2>/dev/null || echo none)\"'\"}'; exit 0"
      }]
    }]
  }
}

Αυτό εγχέει το τρέχον όνομα του έργου, τον κλάδο Git και το τελευταίο commit σε κάθε συνεδρία. Ο Claude λαμβάνει αυτό το πλαίσιο αυτόματα, χωρίς να χρειάζεται να του πείτε σε ποιον κλάδο βρίσκεστε.

5. Αυτόματη Εκτέλεση Δοκιμών Μετά από Αλλαγές Κώδικα

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '\\.(ts|tsx|js|jsx|py)$'",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path' /dev/stdin); TEST_FILE=$(echo \"$FILE\" | sed 's/\\.[^.]*$/.test&/'); if [ -f \"$TEST_FILE\" ]; then npx jest \"$TEST_FILE\" --no-coverage 2>&1 | tail -5; fi; exit 0",
        "timeout": 30000
      }]
    }]
  }
}

Αν υπάρχει αντίστοιχο αρχείο δοκιμών, εκτελείται αυτόματα αφού ο Claude επεξεργαστεί τον πηγαίο κώδικα. Το tail -5 διατηρεί την έξοδο συνοπτική, ενώ το χρονικό όριο αποτρέπει την ανεξέλεγκτη εκτέλεση των δοκιμών. Αυτό συνδυάζεται ιδανικά με μια ροή εργασίας κώδικα αξιολογούμενου από AI.

6. Επιβολή προστασίας κλάδου (Για προχωρημένους)

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "if": "tool_input.command matches 'git push.*(main|master|production)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: Direct push to protected branch. Use a feature branch and open a PR.\"}' && exit 2"
      }]
    }]
  }
}

Αυτό αποκλείει οποιοδήποτε git push στοχεύει στους κλάδους main, master ή production. Ο Claude λαμβάνει την ανατροφοδότηση και θα προτείνει αντ' αυτού τη δημιουργία ενός κλάδου νέας δυνατότητας (feature branch).

7. Καταγραφή Ελέγχου Ασφαλείας (Για προχωρημένους)

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "INPUT=$(cat /dev/stdin); CMD=$(echo \"$INPUT\" | jq -r '.tool_input.command'); echo \"[$(date -u +%Y-%m-%dT%H:%M:%SZ)] BASH: $CMD\" >> .claude/audit.log; exit 0"
      }]
    }]
  }
}

Καταγράφει κάθε εντολή Bash που εκτελεί ο Claude σε ένα αρχείο ελέγχου με χρονική σήμανση UTC. Ιδιαίτερα πολύτιμο για ανασκοπήσεις ασφαλείας και για την κατανόηση του τι έκανε πραγματικά ο Claude κατά τη διάρκεια μιας συνεδρίας. Διατηρήστε το .claude/audit.log στο .gitignore σας.

Hooks vs MCP vs Skills vs CLAUDE.md: Πότε να χρησιμοποιήσετε τι

Χρησιμοποιήστε τα hooks για ντετερμινιστικές αυτοματοποιήσεις που πρέπει να εκτελούνται πάντα (μορφοποίηση, αποκλεισμός, ειδοποιήσεις). Χρησιμοποιήστε το MCP για να δώσετε στον Claude πρόσβαση σε εξωτερικά εργαλεία και δεδομένα. Χρησιμοποιήστε τα Skills για επαναχρησιμοποιήσιμα πακέτα prompts. Χρησιμοποιήστε το CLAUDE.md για καθοδήγηση συμπεριφοράς και πλαίσιο έργου. Τα hooks είναι εγγυημένα· όλα τα υπόλοιπα είναι πιθανοτικά. Αυτή είναι η μοναδική πιο σημαντική διάκριση, και σε αυτήν επανέρχομαι συνεχώς όταν συμβουλεύω ομάδες.

Ο Πίνακας Απόφασης

Για μια σε βάθος ανάλυση του MCP, δείτε τον οδηγό MCP μας. Αν προέρχεστε από το Cursor, το σύστημα κανόνων του Cursor είναι χονδρικά ανάλογο με το CLAUDE.md, αλλά το Cursor δεν διαθέτει κάτι αντίστοιχο με τα hooks.

Όταν Επικαλύπτονται (και Πώς να Επιλέξετε)

Ορίστε το διάγραμμα ροής που χρησιμοποιώ:

• «Πρέπει αυτό να γίνεται κάθε φορά, χωρίς εξαιρέσεις;», Hook. Μορφοποίηση κώδικα, αποκλεισμός προστατευμένων αρχείων, αποστολή ειδοποιήσεων. Μηδενική ασάφεια.
• «Χρειάζεται ο Claude μια νέα ΔΥΝΑΤΟΤΗΤΑ που δεν έχει;», διακομιστής MCP. Πρόσβαση σε βάση δεδομένων, κλήση API, αναζήτηση σε εξωτερικά έγγραφα.
• «Θέλω επαναχρησιμοποιήσιμες ΟΔΗΓΙΕΣ για μια συγκεκριμένη ροή εργασίας;», Skill (εντολή slash). Πρότυπα ανασκόπησης κώδικα, λίστες ελέγχου ανάπτυξης.
• «Θέλω να διαμορφώσω τη ΣΥΜΠΕΡΙΦΟΡΑ του Claude σε αυτό το έργο;», CLAUDE.md. Πρότυπα κωδικοποίησης, αποφάσεις αρχιτεκτονικής, προτιμώμενες βιβλιοθήκες.

Πραγματικά παραδείγματα που διευκρινίζουν το όριο:

• «Πάντα μορφοποίηση με Prettier» = Hook (πρέπει να γίνεται κάθε φορά)
• «Χρησιμοποίησε το Prettier για μορφοποίηση» στο CLAUDE.md = Καθοδήγηση (ο Claude μπορεί να το ξεχάσει)
• «Αναζήτησε στα έγγραφα της εταιρείας μας» = MCP (νέα δυνατότητα)
• «Ακολούθησε τον οδηγό στυλ μας κατά την ανασκόπηση κώδικα» = Skill ή CLAUDE.md

Όπως περιγράφεται στην ανακοίνωση της Anthropic για τα πρόσθετα, τα hooks είναι ένα κομμάτι ενός ευρύτερου οικοσυστήματος πρόσθετων που περιλαμβάνει επίσης τα MCP και τα Skills. Είναι σχεδιασμένα να συμπληρώνουν το ένα το άλλο, όχι να ανταγωνίζονται.

Το Starter Kit: Έτοιμη Διαμόρφωση Hooks του Claude Code για Οποιοδήποτε Έργο

Μια αρχική διαμόρφωση hooks για το Claude Code θα πρέπει να περιλαμβάνει αυτόματη μορφοποίηση κατά την επεξεργασία αρχείων, ειδοποίηση κατά την ολοκλήρωση εργασιών, προστασία για ευαίσθητα αρχεία, έγχυση πλαισίου συνεδρίας και ένα hook διακοπής για εκκαθάριση. Αυτή είναι η ακριβής διαμόρφωση που προσθέτω σε κάθε νέο έργο, προσαρμοσμένη στο stack, αλλά η δομή παραμένει η ίδια.

Η Διαμόρφωση

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null)\"' | Node: '\"$(node -v 2>/dev/null)\"'\"}'; exit 0"
      }]
    }],
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\..+|.*lock\\.json|.*lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Protected file. Edit manually.\"}' && exit 2"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; *.go) gofmt -w \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }],
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Done\"' /dev/stdin); osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\" 2>/dev/null || notify-send 'Claude Code' \"$MSG\" 2>/dev/null; exit 0"
      }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '[STOP] '\"$(date +%H:%M:%S)\"'' >> .claude/session.log; exit 0"
      }]
    }]
  }
}

Πώς να προσαρμόσετε για το Stack σας

Αντικαταστήστε τις εντολές μορφοποίησης και δοκιμής στην παραπάνω διαμόρφωση ώστε να ταιριάζουν με το stack σας. Η δομή παραμένει ίδια.

Επαλήθευση ότι τα Hooks σας λειτουργούν

Τρεις τρόποι για να επιβεβαιώσετε ότι τα hooks είναι ενεργά:

1. Εντολή /hooks, πληκτρολογήστε /hooks στο Claude Code για να δείτε όλα τα καταχωρημένα hooks, τους matchers και την κατάστασή τους.
2. Έλεγχος του transcript, αφού εκτελεστεί ένα hook, ελέγξτε το transcript της συνεδρίας. Οι εκτελέσεις των hooks εμφανίζονται με το output και τον κωδικό εξόδου τους.
3. Γρήγορη εναλλαγή, προσθέστε "disableAllHooks": true στο settings.json για να απενεργοποιήσετε προσωρινά όλα τα hooks χωρίς να διαγράψετε τη ρύθμιση. Αφαιρέστε το (ή ορίστε το σε false) για να τα ενεργοποιήσετε ξανά.

Ενσωμάτωση CI/CD: Claude Code Hooks σε Headless Λειτουργία

Τα hooks του Claude Code λειτουργούν σε headless λειτουργία (claude -p) με ορισμένες διαφορές: τα hooks ειδοποιήσεων εξακολουθούν να ενεργοποιούνται, αλλά θα πρέπει να τα ανακατευθύνετε σε καταγραφή (logging) αντί για ειδοποιήσεις επιφάνειας εργασίας. Τα hooks τύπου PreToolUse με κωδικό εξόδου 2 μπορούν να θέσουν σε παύση τις headless συνεδρίες για ανθρώπινη αναθεώρηση. Τα GitHub Actions χρησιμοποιούν το anthropics/claude-code-action@v1 παράλληλα με τα hooks για αυτοματοποιημένες ροές εργασίας.

Συμπεριφορά Λειτουργίας Headless

Η μεγάλη έκπληξη στη λειτουργία headless: τα hooks PreToolUse που εξέρχονται με κωδικό 2 δεν αποτυγχάνουν απλώς σιωπηλά. Παύουν τη συνεδρία και σας επιτρέπουν να την επαναλάβετε με το --resume, κάτι που σας δίνει ένα μοτίβο human-in-the-loop για pipelines CI.

Ενσωμάτωση GitHub Actions

Ακολουθεί μια ελάχιστη ροή εργασίας GitHub Actions που χρησιμοποιεί το Claude Code με hooks. Όπως τεκμηριώνεται στον επίσημο οδηγό GitHub Actions:

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR and suggest improvements"
    allowed_tools: "Read,Grep,Glob"
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Τα hooks του αρχείου .claude/settings.json συνοδεύουν το αποθετήριο, επομένως θα ενεργοποιούνται στο CI ακριβώς όπως και τοπικά. Απλώς φροντίστε ώστε τυχόν hooks που βασίζονται σε εργαλεία ειδικά για επιτραπέζιους υπολογιστές (όπως το osascript) να διαθέτουν εναλλακτικές λύσεις ή συνθήκες.

Διαχείριση Hooks Ομάδας

Ένα μοτίβο που λειτουργεί καλά για τις ομάδες:

• .claude/settings.json (committed), Κοινόχρηστα hooks ομάδας: προστασία αρχείων, formatters, προστασία κλάδων (branches). Αυτά τα λαμβάνουν όλοι.
• .claude/settings.local.json (gitignored), Προσωπικά hooks: προτιμήσεις ειδοποιήσεων, προσαρμοσμένη καταγραφή (logging), πειραματικά hooks.
• ~/.claude/settings.json (user-global), Οι προεπιλογές σας για όλα τα έργα: στυλ ειδοποιήσεων, προσωπικές προτιμήσεις μορφοποίησης.

Αυτό αντικατοπτρίζει τον τρόπο που λειτουργούν το .editorconfig (committed) και οι τοπικές ρυθμίσεις του IDE (προσωπικές). Όπως επισημαίνει ο Οδηγός CI/CD του Angelo Lima, οι ομάδες που τυποποιούν τη χρήση κοινόχρηστων hooks αντιμετωπίζουν λιγότερα προβλήματα τύπου «σε εμένα δουλεύει» με το Claude Code.

Αντιμετώπιση προβλημάτων με τα Hooks του Claude Code και συχνά λάθη

Τα συχνά προβλήματα με τα hooks του Claude Code περιλαμβάνουν hooks που δεν ενεργοποιούνται (ελέγξτε την ορθογραφία του matcher και τη θέση του settings.json), hooks που εκτελούνται αλλά δεν μπλοκάρουν (λάθος exit code, χρησιμοποιήστε 2 και όχι 1), άπειρους βρόχους (το Stop hook να ενεργοποιεί τον εαυτό του) και αργή εκκίνηση (πάρα πολλά σύγχρονα hooks). Το πιο συχνό λάθος που βλέπω είναι η σύγχυση με τους κωδικούς εξόδου· οι προγραμματιστές χρησιμοποιούν το exit 1 όταν εννοούν το exit 2.

Το Hook δεν ενεργοποιείται

Συμπτώματα: Προσθέσατε ένα hook, αλλά δεν συμβαίνει τίποτα όταν πραγματοποιείται το συμβάν.

Διορθώσεις:

• Τυπογραφικό λάθος στον Matcher, οι Matchers κάνουν διάκριση πεζών-κεφαλαίων. Το \"write\" δεν θα ταιριάξει με το εργαλείο Write. Ελέγξτε τα ακριβή ονόματα των εργαλείων με το /hooks.
• Λάθος αρχείο ρυθμίσεων, τα hooks στο ~/.claude/settings.json δεν θα εμφανίζονται στην έξοδο του /hooks για το πεδίο εφαρμογής του έργου. Δοκιμάστε το .claude/settings.json στη ρίζα του έργου.
• Σφάλμα σύνταξης JSON, ένα περιττό κόμμα ή μια παρένθεση που λείπει απενεργοποιεί σιωπηλά ολόκληρη τη διαμόρφωση των hooks. Τρέξτε το settings.json σας μέσω του jq . για επικύρωση.
• disableAllHooks: true, ελέγξτε αν κάποιος (ή μια προηγούμενη συνεδρία αποσφαλμάτωσης) άφησε αυτήν τη σημαία ενεργοποιημένη.

Το Hook εκτελείται αλλά δεν μπλοκάρει

Συμπτώματα: Το PreToolUse hook σας εκτελείται, αλλά η ενέργεια συνεχίζεται κανονικά.

Διορθώσεις:

• Λάθος κωδικός εξόδου, Ο κωδικός εξόδου 1 σημαίνει «σφάλμα» (το hook απέτυχε), όχι «μπλοκάρισμα». Χρησιμοποιήστε το exit 2 για να μπλοκάρετε μια ενέργεια. Αυτό μπερδεύει σχεδόν τους πάντες, όπως αναφέρεται στα επίσημα έγγραφα.
• Λείπει το JSON του stdout, Για τα hooks που μπλοκάρουν, εξάγετε ένα μήνυμα JSON ώστε ο Claude να γνωρίζει γιατί μπλοκαρίστηκε η ενέργεια: echo '{"message": "Blocked: reason"}'

Άπειροι Βρόχοι

Συμπτώματα: Ο Claude συνεχίζει να δοκιμάζει ξανά την ίδια ενέργεια, ή το μηχάνημά σας θερμαίνεται ύποπτα.

Λύσεις:

• Το hook διακοπής (Stop hook) προκαλεί ενέργειες, Αν το Stop hook σας γράφει ένα αρχείο ή εκτελεί μια εντολή που κάνει τον Claude να απαντήσει, έχετε δημιουργήσει έναν βρόχο. Τα Stop hooks θα πρέπει να κάνουν μόνο παθητικά πράγματα: καταγραφή, ειδοποίηση, εκκαθάριση.
• Το PostToolUse hook προκαλεί επεξεργασίες, Ένα PostToolUse hook που τροποποιεί ένα αρχείο ενεργοποιεί ένα άλλο συμβάν PostToolUse. Προστατευτείτε από αυτό με συγκεκριμένους ανιχνευτές (matchers) ή με το πεδίο if.

Προβλήματα Απόδοσης

Συμπτώματα: Το Claude καθυστερεί αισθητά να ξεκινήσει ή να εκτελέσει εργαλεία.

Διορθώσεις:

• Πάρα πολλά hooks SessionStart, Το καθένα εκτελείται σύγχρονα κατά την εκκίνηση. Κρατήστε τα ελαφριά (κάτω από 1 δευτερόλεπτο το καθένα).
• Βαριά σενάρια σε κρίσιμα μονοπάτια, Τα hooks σε PreToolUse και PostToolUse ενεργοποιούνται συχνά. Αν το σενάριό σας κάνει αιτήματα δικτύου ή βαρείς υπολογισμούς, προσθέστε ένα πεδίο timeout (χιλιοστά δευτερολέπτου) και εξετάστε αν θα έπρεπε να είναι αντ' αυτού ένα HTTP hook.
• Χωρίς προσωρινή αποθήκευση, Αν ελέγχετε επανειλημμένα το ίδιο πράγμα (όπως «είναι αυτό προστατευμένος κλάδος;»), αποθηκεύστε προσωρινά το αποτέλεσμα σε ένα προσωρινό αρχείο αντί να εκτελείτε εντολές Git σε κάθε κλήση hook.

Συχνές Ερωτήσεις

Τι είναι τα hooks του Claude Code και πώς λειτουργούν;

Τα hooks του Claude Code είναι αυτοματοποιημένα σενάρια (scripts) που ορίζονται από τον χρήστη και εκτελούνται σε συγκεκριμένα γεγονότα του κύκλου ζωής κατά τη διάρκεια μιας συνεδρίας του Claude Code. Τα διαμορφώνετε στο settings.json με ένα μοτίβο αντιστοίχισης (matcher pattern) και έναν χειριστή (handler) — ο οποίος μπορεί να είναι εντολή shell, endpoint HTTP, prompt ή agent. Όταν ενεργοποιείται το αντίστοιχο γεγονός, το hook εκτελείται αυτόματα και χρησιμοποιεί κωδικούς εξόδου (exit codes) για να ελέγξει το αποτέλεσμα.

Πώς ρυθμίζω τα hooks στο settings.json του Claude Code;

Προσθέστε ένα αντικείμενο "hooks" σε οποιαδήποτε από τις τρεις τοποθεσίες ρυθμίσεων: ~/.claude/settings.json (καθολικό χρήστη), .claude/settings.json (κοινόχρηστο έργου) ή .claude/settings.local.json (προσωπικό έργου). Κάθε τύπος γεγονότος αντιστοιχίζεται σε έναν πίνακα ορισμών hook με matcher, προαιρετικό πεδίο if και έναν πίνακα hooks που περιέχει αντικείμενα χειριστών με type και command ή url.

Ποια είναι η διαφορά μεταξύ των hooks PreToolUse και PostToolUse;

Το PreToolUse ενεργοποιείται πριν από την εκτέλεση ενός εργαλείου, δίνοντάς σας τη δυνατότητα να το αποκλείσετε με κωδικό εξόδου 2. Το PostToolUse ενεργοποιείται μετά την ολοκλήρωση της εκτέλεσης και είναι χρήσιμο για μορφοποίηση, δοκιμές ή καταγραφή. Το PreToolUse προορίζεται για πρόληψη και έλεγχο πρόσβασης. Το PostToolUse προορίζεται για επικύρωση και καθαρισμό. Και τα δύο λαμβάνουν το όνομα του εργαλείου και την είσοδο ως JSON στο stdin.

Μπορούν τα hooks του Claude Code να μπλοκάρουν επικίνδυνες εντολές;

Ναι. Τα hooks του PreToolUse με κωδικό εξόδου 2 μπλοκάρουν οποιαδήποτε εκτέλεση εργαλείου. Μπορείτε να προστατεύσετε ευαίσθητα αρχεία από εγγραφή, να μπλοκάρετε εντολές κελύφους που ταιριάζουν με επικίνδυνα μοτίβα όπως το rm -rf ή το git push main, και να αποτρέψετε την πρόσβαση σε βάσεις δεδομένων παραγωγής. Το μήνυμα αποκλεισμού αποστέλλεται πίσω στον Claude ως ανατροφοδότηση, ώστε να μπορεί να προσαρμόσει την προσέγγισή του.

Ποια hook events είναι διαθέσιμα στο Claude Code;

Το Claude Code παρέχει πάνω από 15 events: τα PreToolUse και PostToolUse για την εκτέλεση εργαλείων, το Notification για ειδοποιήσεις, το Stop για το τέλος της συνεδρίας, το SessionStart για την αρχικοποίηση, το UserPromptSubmit για το φιλτράρισμα της εισόδου, τα PreCompact και PostCompact για τη διαχείριση του context, καθώς και νεότερα events όπως τα ConfigChange, FileChanged, TaskCreated και PermissionDenied. Δείτε τον πλήρη πίνακα αναφοράς στην παραπάνω ενότητα για τα hook events.

Πώς διαφέρουν τα hooks από τα εργαλεία MCP και τα Skills;

Τα hooks είναι ντετερμινιστικά — ενεργοποιούνται πάντα σε αντίστοιχα γεγονότα, ανεξάρτητα από το τι θα αποφασίσει ο Claude. Τα εργαλεία MCP επεκτείνουν τις δυνατότητες του Claude (πρόσβαση σε βάσεις δεδομένων, κλήσεις API), αλλά ο Claude επιλέγει πότε θα τα χρησιμοποιήσει. Τα Skills είναι επαναχρησιμοποιήσιμα πακέτα οδηγιών που καλούνται μέσω εντολών slash. Το CLAUDE.md παρέχει καθοδήγηση συμπεριφοράς. Χρησιμοποιήστε hooks όταν κάτι πρέπει να συμβαίνει κάθε φορά και MCP όταν ο Claude χρειάζεται νέες δυνατότητες.

Λειτουργούν τα hooks του Claude Code σε headless λειτουργία;

Ναι, με ορισμένες επισημάνσεις. Τα hooks ενεργοποιούνται κανονικά σε headless λειτουργία (claude -p), αλλά τα hooks που αφορούν την επιφάνεια εργασίας, όπως οι ειδοποιήσεις macOS, χρειάζονται εναλλακτικές λύσεις. Σημαντικά, τα PreToolUse hooks που τερματίζουν με κωδικό εξόδου 2 μπορούν να θέσουν σε παύση τις headless συνεδρίες για ανθρώπινη έγκριση μέσω του --resume. Αυτό επιτρέπει pipelines CI/CD με ανθρώπινη συμμετοχή, όπου ορισμένες ενέργειες απαιτούν χειροκίνητη έγκριση.

Πόσα hooks είναι πάρα πολλά; Τα hooks επιβραδύνουν το Claude Code;

Δεν υπάρχει αυστηρό όριο, αλλά κάθε σύγχρονο hook προσθέτει καθυστέρηση. Τα hooks του SessionStart εκτελούνται κατά την εκκίνηση, γι' αυτό κρατήστε τα γρήγορα (κάτω από 1 δευτερόλεπτο το καθένα). Τα hooks PreToolUse και PostToolUse ενεργοποιούνται σε κάθε αντίστοιχη κλήση εργαλείου — βαριά scripts εκεί συσσωρεύονται γρήγορα. Συνιστώ να κρατάτε τα συνολικά hooks κάτω από 10-15, να χρησιμοποιείτε το πεδίο if για να περιορίζετε το πεδίο εφαρμογής, και να προσθέτετε τιμές timeout για να αποτρέπετε ανεξέλεγκτα scripts.

Μπορώ να χρησιμοποιήσω hooks για να μορφοποιώ αυτόματα κώδικα με το Prettier ή το Black;

Ναι, είναι η πιο δημοφιλής περίπτωση χρήσης των hooks. Δημιουργήστε ένα hook τύπου PostToolUse που να ταιριάζει με το Write|Edit, εξάγετε τη διαδρομή του αρχείου από το JSON του stdin και εκτελέστε τον κατάλληλο μορφοποιητή με βάση την επέκταση του αρχείου. Δείτε το πρώτο παράδειγμα στην ενότητα με τα παραδείγματα παραγωγής για μια πλήρη, έτοιμη προς αντιγραφή διαμόρφωση που χειρίζεται αρχεία TypeScript, JavaScript και Python.

Είναι ασφαλή τα hooks του Claude Code; Ποιοι είναι οι κίνδυνοι ασφαλείας;

Τα hooks εκτελούνται με τα πλήρη δικαιώματα του χρήστη σας, δεν υπάρχει sandbox. Ένα κακόβουλο hook θα μπορούσε να διαβάσει τα SSH κλειδιά σας, να διαγράψει αρχεία ή να εξάγει δεδομένα. Χρησιμοποιείτε μόνο hooks από αξιόπιστες πηγές, ελέγχετε κάθε κοινόχρηστο .claude/settings.json πριν το αποδεχτείτε στο έργο σας και χρησιμοποιείτε το .claude/settings.local.json για προσωπικά hooks που δεν πρέπει να κοινοποιούνται. Για ευρύτερα μοτίβα ασφαλείας AI, δείτε τον οδηγό μας για τα guardrails των LLM.