메뉴
Use when configuring automated lifecycle commands (hooks) in Claude Code settings.json — event types, matcher syntax, exit codes, JSON output, path placeholders.
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/ucsandman/claude-code-capability-primer --skill claude-code-hooks명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SOC 직업 분류 기준
SKILL.md 표시 중
| name | claude-code-hooks |
| description | Use when configuring automated lifecycle commands (hooks) in Claude Code settings.json — event types, matcher syntax, exit codes, JSON output, path placeholders. |
| user-invocable | true |
Hooks are shell commands, HTTP endpoints, or MCP tools that execute automatically at lifecycle points: before/after tool calls, on session start/end, when config changes, and on other events. The harness controls execution; Claude cannot suppress them.
Hooks fire at specific cadences:
Once per session:
SessionStart — beginning, resume, or after compactionSessionEnd — on session closeOnce per turn:
UserPromptSubmit — before Claude reads prompt (can block)UserPromptExpansion — before user command expands to prompt (can block)Stop — after Claude respondsStopFailure — if response failedPer tool call:
PreToolUse — before tool executes (can block)PermissionRequest — when permission dialog appearsPermissionDenied — when tool denied; can return {retry: true}PostToolUse — after tool succeedsPostToolUseFailure — if tool failedPostToolBatch — after parallel batch resolvesAsync/file watching:
FileChanged — watched file modified on disk (matcher specifies files)CwdChanged — working directory changedConfigChange — settings/skills file modifiedInstructionsLoaded — CLAUDE.md or rules/*.md loadedNotification — when Claude Code sends notification (matcher: notification type)MessageDisplay — while assistant message displaysSubagentStart — subagent spawned (matcher: agent type)SubagentStop — subagent finishedTaskCreated, TaskCompleted — task lifecycleSetup — on --init-only or CI setup modePreCompact, PostCompact — context compaction boundaryElicitation, ElicitationResult — MCP server user inputWorktreeCreate, WorktreeRemove — git worktree lifecycleTeammateIdle — agent team teammate idle~/.claude/settings.json — user-wide (all projects).claude/settings.json — project-wide (shareable, commitable).claude/settings.local.json — project-specific (gitignored)hooks/hooks.json — loaded at plugin install{
"hooks": {
"EventName": [
{
"matcher": "ToolName|OtherTool",
"hooks": [
{
"type": "command|http|mcp_tool|prompt|agent",
"command": "script.sh",
"timeout": 30,
"statusMessage": "Running validation...",
"async": false,
"if": "Bash(git *)"
}
]
}
]
}
}
"*" — matches all_/| — exact match or literal alternatives: Bash, Edit|Write, mcp__github__create_issue^Notebook, .envrc|.env, mcp__.*__write.*startup|resume|clear|compactpermission_prompt, idle_prompt, auth_success, elicitation_dialog, elicitation_complete, elicitation_responseExec form (preferred; safe for paths with special chars):
{
"type": "command",
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/script.js", "--fix"]
}
Spawns directly without shell; ${} placeholders safe.
Shell form (full features like pipes, globs):
{
"type": "command",
"command": "grep 'error' log.txt | wc -l"
}
Runs in shell; supports &&, pipes, * globs. Avoid untrusted paths.
Common fields:
timeout — seconds before kill (default: varies by event)statusMessage — user-visible spinner textasync — run in background without blockingasyncRewake — background task, wake Claude on exit 2if — permission rule: Bash(rm **), Edit(*.ts), Bash(git *)once — run once per session, then remove (skills only)shell — bash (default) or powershell${CLAUDE_PROJECT_DIR} — project root${CLAUDE_PLUGIN_ROOT} — plugin installation directory${CLAUDE_PLUGIN_DATA} — plugin persistent data dirAlways use exec form with args when using placeholders.
Claude Code on Windows auto-prepends bash to .sh commands. Override by using extensionless filenames with a wrapper:
{
"command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start"
}
Wrapper (run-hook.cmd): batch block for cmd.exe, shell code for bash:
: << 'CMDBLOCK'
@echo off
if exist "C:\Program Files\Git\bin\bash.exe" (
"C:\Program Files\Git\bin\bash.exe" "%~dp0%~1" %2 %3
exit /b %ERRORLEVEL%
)
where bash >nul 2>nul && bash "%~dp0%~1" %2 %3 && exit /b %ERRORLEVEL%
exit /b 0
CMDBLOCK
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
exec bash "${SCRIPT_DIR}/$1" "${@:2}"
The : << 'CMDBLOCK' trick: cmd.exe runs batch; bash sees : (no-op) and runs Unix shell code.
| Code | Meaning |
|---|---|
| 0 | Success. Harness parses stdout for JSON output. |
| 2 | Blocking error. Stderr shown to user. Hook can deny action or block turn. |
| Other | Non-blocking error. First line of stderr shown, execution continues. |
All hooks receive:
session_id — unique identifiercwd — current working directorypermission_mode — default, plan, acceptEdits, auto, dontAsk, bypassPermissionshook_event_name — event nameeffort.level — low, medium, high, xhigh, maxtranscript_path — path to session transcript (JSONL)agent_id, agent_type — when inside subagenttool_name, tool_input for PreToolUse)Exit 0 with valid JSON stdout to control harness. Output format depends on your platform:
Claude Code (CLAUDE_PLUGIN_ROOT set):
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"additionalContext": "Context for Claude",
"permissionDecision": "deny",
"permissionDecisionReason": "Blocked by policy"
}
}
Cursor (CURSOR_PLUGIN_ROOT set):
{
"additional_context": "Context for Claude"
}
Copilot CLI (SDK standard):
{
"additionalContext": "Context for Claude"
}
Universal fields:
continue: false — stop entire turnstopReason — message when stoppingsuppressOutput: true — hide from transcriptsystemMessage — warning shown to userterminalSequence — OSC codes (desktop notification, window title){
"type": "http",
"url": "http://localhost:8080/hook",
"headers": {"Authorization": "Bearer ${TOKEN}"},
"allowedEnvVars": ["TOKEN"]
}
POST with stdin JSON. Whitelist env vars to pass. Return 2xx with JSON body for decisions.
{
"type": "mcp_tool",
"server": "my_mcp_server",
"tool": "tool_name",
"input": {"file_path": "${tool_input.file_path}"}
}
Call tool on connected MCP server. Fields can interpolate from stdin.
{
"type": "prompt",
"prompt": "Should this be allowed? $ARGUMENTS",
"model": "fast-model"
}
Sends yes/no question to Claude. Rarely needed; prefer command hooks for determinism.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"if": "Bash(rm -rf *)",
"hooks": [{
"type": "command",
"command": "node",
"args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.js"]
}]
}
]
}
}
Exit code 2 to deny; stderr message shown.
{
"disableAllHooks": true
}
Top-level key to skip all hooks (useful for debugging).
Don't use hooks for:
/hooks command: browse configured hooks, view matchers/handlersjq before deployingchmod +x script.shtimeout to kill runaway scriptssuppressOutput: true)Hooks execute with your user permissions. Always:
.claude/ or plugin dirs (not world-writable)