Claude Code Hooks

Plug-and-play hooks for Claude Code. Two essential hooks that solve two common pain points:

1. context-check.js — Monitors context window usage and warns you before it's too late
2. permission-whistle.js — Plays a sound when Claude needs your permission

What Are Hooks?

Claude Code hooks are shell commands that run automatically at specific lifecycle events (prompt submitted, tool used, permission requested, etc.).

• Exit 0 → continue
• Exit 2 → block the action

That's it. Your script runs, you decide.

Hooks

context-check.js

Tracks context window fill percentage by reading the session transcript.

Event	Threshold	Mode	What happens
PostToolUse	50%	warn	System message warning after each tool use
UserPromptSubmit	80%	block	Blocks your prompt, terminal beeps
TaskCompleted	60%	warn	Reminder when a task finishes

When triggered, you see:

⚠️ CONTEXT: [============........] %60
Kullanilan: ~120K / 200K
/compact ile sikistirmayi dusun.

Features:

• ASCII progress bar with severity indicators (= normal, ~ warning, ! critical)
• /compact bypass — even when blocked at 80%+, /compact is always allowed through so you can compress and continue
• Dedup logic — only re-warns after 5% increase, no spam
• Reads only the last 100KB of transcript for performance
• Never blocks on error (fails open)

Thresholds are customizable:

# Warn at 40%, block at 70%
node context-check.js 40 warn
node context-check.js 70 block

permission-whistle.js

Plays a two-tone rising whistle when Claude requests permission.

• Uses PowerShell [console]::Beep() on Windows
• Falls back to terminal bell (\x07) if PowerShell fails
• 7 lines of code, no dependencies

Mac/Linux users: Replace the PowerShell command with afplay, paplay, or tput bel. See Cross-platform section below.

Setup

Quick Setup

# 1. Clone
git clone https://github.com/eminn2721/claude-code-hooks.git

# 2. Copy hooks
mkdir -p ~/.claude/hooks
cp claude-code-hooks/hooks/* ~/.claude/hooks/

# 3. Merge the hooks config into your ~/.claude/settings.json
# See settings.example.json for the full config

Manual Setup

1. Copy hooks/context-check.js and hooks/permission-whistle.js to ~/.claude/hooks/
2. Open ~/.claude/settings.json
3. Add the hooks configuration from settings.example.json into your existing "hooks" section

Note: If you already have hooks configured, merge the entries — don't replace your entire "hooks" object.

Windows Users

The paths in settings.example.json use ~/ shorthand. On Windows, use the full path:

"command": "node C:/Users/YOUR_USERNAME/.claude/hooks/context-check.js 80 block"

Cross-platform

permission-whistle.js — Mac/Linux Alternative

Replace the PowerShell command in permission-whistle.js:

macOS:

execSync('afplay /System/Library/Sounds/Tink.aiff', { stdio: "ignore", timeout: 3000 });

Linux:

execSync('paplay /usr/share/sounds/freedesktop/stereo/bell.oga', { stdio: "ignore", timeout: 3000 });

Or use a simple terminal bell (works everywhere):

process.stderr.write("\x07");

How Hooks Work

Event fires → Hook receives JSON on stdin → Your script runs → Exit code decides

Input (stdin): JSON with session_id, transcript_path, tool_name, tool_input, etc.

Output:

• Exit 0 = allow (optionally print JSON with systemMessage)
• Exit 2 = block (stderr shown as error)

Full docs: Claude Code Hooks Documentation

License

MIT