Hooks
The hooks cckit installs, what fires each one, and what it does.
A hook is a script Claude Code runs automatically when something happens — a session starts, a
command is about to run, a session ends. cckit scaffolds a few during cckit init, so the right
check runs at the right moment without you remembering to run it.
Always set up
Section titled “Always set up”These four are scaffolded for every project.
| Event | Hook | What it does |
|---|---|---|
SessionStart | repo-hygiene.sh | A read-only report at the start of each session: stale branches, leftover worktrees, and stashes — the same things cckit gc cleans up. |
SessionStart | kit_version_check.sh | A quiet notice if this project is behind the installed cckit — the prompt to run cckit update. |
PreToolUse (Bash) | guard-base-branch-commit.sh | Blocks a commit made straight to the base branch, so work always goes through a branch and a PR. |
PreToolUse (Bash) | guard-raw-git-ops.sh | Blocks a raw gh issue create, gh pr create, gh pr merge, gh issue close, or a branch cut from the base branch, and prints the cckit verb to run instead. The verb adds the item to the board; the raw command does not. KIT_ALLOW_RAW=1 lets one command through and records it in <git-common-dir>/cckit/raw-bypass.log. |
Set up when you enable a feature
Section titled “Set up when you enable a feature”cckit init adds these when you turn the matching option on.
| Event | Hook | Enabled by | What it does |
|---|---|---|---|
PreToolUse (Bash) | prepush_gate.sh | pre-push gate | Runs your project’s check (tests, lint) before a git push, so a red branch never reaches the remote. |
SessionStart | kit-local-status.sh | local model layer | Announces the local model (mlx_lm.server) when it’s enabled and alive. |
SessionStart | mempal_session_start.sh | memory (MemPalace) | Loads this project’s saved context (wake-up --wing) at the start of a session. The body is wing-scoped; for a wing-scoped identity header, drop in .claude/mempal-identity.<wing>.txt. |
Stop | mempal_save.sh | memory (MemPalace) | Files the finished session into MemPalace. |
PreCompact | mempal_precompact.sh | memory (MemPalace) | A safety-net sweep to memory before the conversation is compressed. |
SessionEnd | mempal_followup.sh | memory (MemPalace) | Captures any unsynced work if a session closes abruptly. |
Where they live
Section titled “Where they live”Hooks are plain scripts under .claude/hooks/ in your project, registered in
.claude/settings.local.json. The raw-git guard is the exception: it is registered in the checked-in
.claude/settings.json, so it also runs in every worktree. They are yours to read and edit — every one is a safe no-op when its
tool isn’t installed, so nothing breaks if a dependency is missing.
cckit init --upgrade refreshes a hook you never edited: one whose content matches an earlier
version of its template, or the hash recorded in .claude/kit.manifest.json. A hook you customized
is kept and listed as Drifted in the upgrade summary, for you to compare with the template.
| Do this | Command |
|---|---|
| Scaffold the hooks | cckit init |
| Check setup is healthy | cckit doctor |
| Check the repo health a hook reports | cckit gc |
| Act on the update notice | cckit update |
Independent, educational project — not affiliated with or endorsed by Anthropic. Claude and Claude Code are trademarks of Anthropic PBC.Disclaimer & trademarks ·
From Mexico withloveby josegtz