| name | hookmaster-conflict-reviewer |
| description | Activate when HookMaster hook conflicts are detected. Triggers when: the conflict-watchdog hook outputs a conflict warning (⚠️ HOOKMASTER CONFLICT DETECTED appears in context); the user installs or enables hooks that are known to conflict (auto-format, auto-lint, import-sorter in any combination of 2+); or the user explicitly runs /hook-analysis. Do NOT activate on every settings.json change — only when a conflict warning is present or the user asks.
|
| author | seanrobertwright |
| version | 1.0.0 |
HookMaster Conflict Reviewer
You help the user understand and resolve HookMaster hook conflicts with minimal friction. The goal is one clear recommendation + one yes/no question, then act.
When You Activate
You activate in two situations:
-
Automatic — The conflict-watchdog hook has output a warning block starting with ⚠️ HOOKMASTER CONFLICT DETECTED into the session context. This means settings.json just changed and conflicts were found.
-
Manual — The user has run /hook-analysis or has asked about hook conflicts.
SITUATION 1: Conflict Warning in Context
When you see ⚠️ HOOKMASTER CONFLICT DETECTED in the session context:
Step 1: Acknowledge briefly
Surface the issue in 2-3 lines. Do not repeat all the details from the watchdog output — just summarize:
⚠️ Hook conflict detected: [hook names] will race on file writes.
Step 2: State the single best fix
Pick the most specific combo that covers all the conflicting hooks. The priority is:
- If all three file-writers are installed: recommend
combo-quality-suite
- If only two are installed: recommend
combo-format-and-lint
State it plainly:
Fix: replace [conflicting hooks] with [combo-id] ([description]).
This runs them sequentially, eliminating the race condition.
Step 3: Ask one question
Swap to [combo-id] now? (y/n)
Wait for the user's response. Do not ask follow-up questions.
Step 4a: If yes — apply the fix
Read the appropriate settings.json file(s) to find where the conflicting hooks are installed.
For each conflicting hook to remove:
- Find its entry in
settings.json under hooks.<event>.<matcher-group>.hooks[]
- Remove the handler entry
- If the matcher group is now empty, remove the group
- If the event is now empty, remove the event key
Then add the combo hook. The combo hook's settings.json entry follows this pattern:
- For global scope: command path is
~/.claude/hooks/hookmaster/[combo-id]/script.sh
- For local scope: command path is
[project-root]/.claude/hooks/hookmaster/[combo-id]/script.sh
- Event:
PostToolUse
- Matcher:
Write|Edit|MultiEdit
- Type:
command
- Timeout: 30
Also copy the combo hook's script file:
- Source: wherever HookMaster is installed (from the command path of an existing hookmaster hook — strip the hook ID from the path to find the hookmaster root)
- Destination: same directory structure as the removed hooks
Confirm: "Done. [combo-id] is now installed. The race condition is resolved."
Step 4b: If no — acknowledge and close
"OK, keeping individual hooks. The race condition remains — if you see file corruption after edits, that's likely the cause. You can run /hook-analysis at any time to revisit."
SITUATION 2: /hook-analysis (Interactive Mode)
When the user runs /hook-analysis, perform a full interactive analysis. See the /hook-analysis slash command for the detailed flow — it guides you step by step.
Background: Why Conflicts Happen
Claude Code runs all hooks registered for the same event in parallel. There is no guaranteed execution order.
Race condition hooks — all fire on PostToolUse (Write|Edit|MultiEdit) and write to $FILE_PATH:
auto-format — Prettier/Black/rustfmt/gofmtauto-lint — ESLint --fix / ruff --fiximport-sorter — isort / eslint import/order
Installing any two simultaneously causes both to open and write to the same file at the same moment.
Combo hooks — sequential alternatives:
combo-format-and-lint: format → lintcombo-quality-suite: format → sort imports → lint
Paired hooks — should always coexist:
time-tracker (SessionStart) + time-tracker-end (SessionEnd)
Settings.json Path Reference
| Scope | Path |
|---|
| Global | ~/.claude/settings.json |
| Local | [cwd]/.claude/settings.json |
| Local override | [cwd]/.claude/settings.local.json |
Hook scripts are installed at:
- Global:
~/.claude/hooks/hookmaster/<hook-id>/script.sh
- Local:
[cwd]/.claude/hooks/hookmaster/<hook-id>/script.sh
