cc-hooks

Hooks that make Claude Code safer and happier

Install once. Add language or policy templates in seconds. Get reliable automation with clear feedback and logs—without surprises.

Install cc-hooks See quick start
Runs on Claude Code events
PreToolUse PostToolUse Notification UserPromptSubmit Stop SubagentStop PreCompact SessionStart 
npm install -g @c-p-b/cc-hooks
cc-hooks init && cc-hooks install typescript

Works on macOS and Linux. Windows users: use WSL/WSL2.

Install

Global install

npm install -g @c-p-b/cc-hooks
  • Requires Node.js 18, 20, or 22
  • Binary: cc-hooks

Initialize in a project

cc-hooks init
  • Bootstraps all supported events in your Claude settings
  • Backs up existing settings, hints at vanilla hooks

Install a template

cc-hooks install typescript
  • Also available: typescript-format, python-lint, session-context, git-commit-msg
  • Supports local JSON files and Git sources

Quick start

1. Initialize

cc-hooks init

Adds the orchestrator to your Claude settings across all events.

2. Add a few hooks

cc-hooks install typescript
cc-hooks install typescript-format
cc-hooks install python-lint
cc-hooks install session-context
cc-hooks install git-commit-msg

Templates live in the package under templates/ for easy discovery.

3. See what’s configured

cc-hooks show --verbose

Shows events, commands, timeouts, and priorities. Bundles are grouped automatically when present.

Why developers like cc-hooks

Two tiers, simple by default

  • Text hooks map exit codes to flow control (0=success, 2=block, others=warn)
  • Structured hooks return JSON for approvals, blocks, and diagnostics
  • Clear user messages and optional fix instructions

Reliable execution

  • Per-hook timeout with gentle SIGTERM then SIGKILL
  • 1MB output cap with instant kill on overflow
  • Process groups on Unix to avoid zombies
  • Session JSONL logs with rotation and cleanup

Developer ergonomics

  • cc-hooks logs for quick visibility (filter, tail)
  • Priority sorting and matchers per tool/event
  • CC_HOOKS_DEBUG for deep diagnostics
  • Windows gated to WSL with clear guidance

Mini demo you can run

Format & lint (PostToolUse)

printf 'export const x=[1,2,3]\n' > demo.ts
echo '{"session_id":"demo","transcript_path":"/tmp/demo.jsonl","cwd":"'"$(pwd)"'","hook_event_name":"PostToolUse","tool_name":"Write","tool_input":{"file_path":"demo.ts"}}' | cc-hooks run
  • typescript-format blocks on Prettier issues
  • typescript reports non-blocking warnings

Session context (SessionStart)

echo '{"session_id":"demo","transcript_path":"/tmp/demo.jsonl","cwd":"'"$(pwd)"'","hook_event_name":"SessionStart","source":"startup"}' | cc-hooks run

session-context prints git status and recent commits (becomes context)

Commit policy (Stop)

git add -A && git commit -m "bad message"
echo '{"session_id":"demo","transcript_path":"/tmp/demo.jsonl","cwd":"'"$(pwd)"'","hook_event_name":"Stop"}' | cc-hooks run

git-commit-msg blocks non-conventional messages and suggests a fix

Keep cc-hooks logs -f running in another terminal to watch results in real time.

Make your own hook (text)

Create my-hook.json in your project:

{
  "name": "my-guardrail",
  "description": "Block TODOs in user prompts",
  "command": ["sh", "-c", "jq -er '.prompt|test(\"TODO\")|not' > /dev/null || { echo 'Prompt contains TODO – please remove it' 1>&2; exit 2; }"],
  "events": ["UserPromptSubmit"],
  "outputFormat": "text",
  "exitCodeMap": { "0": "success", "2": "blocking-error", "default": "non-blocking-error" },
  "message": "Prompt check failed",
  "timeout": 10
}
cc-hooks install ./my-hook.json
cc-hooks show --verbose

Prefer structured hooks for richer decisions and diagnostics.

How it works

Pipeline

  • Claude sends a JSON event → cc-hooks run reads stdin
  • Config resolved (global → project → local), then filtered by event/matcher
  • Hooks run in parallel with resource limits
  • Result mapped to success / warn / block with clear output

Observability

  • Per-session JSONL logs with duration, exit code, severity
  • Rotation and cleanup keep disk usage bounded
  • cc-hooks logs to view, filter, or tail

Available Template Bundles

  • typescript — ESLint, Prettier, tests, coverage
  • python — Ruff linting
  • git — Conventional commit validation
  • session — Context, init, transcript saving
  • analysis — Code quality & patterns
  • automation — Script runners & processors

Want installers for your team? Add JSON files under templates/ or publish a Git repo with a hook.json.