pbakaus_impeccable/site/content/reference/hooks.md

title, tagline, description, section, order

title	tagline	description	section	order
Design hooks	Automatic detector feedback inside Claude Code, GitHub Copilot, Codex, and Cursor.	Install, enable, disable, debug, and tune Impeccable's provider-native design hook for automatic detector feedback on UI file edits.	automation	2

The design hook runs Impeccable's detector automatically when an AI coding tool edits UI files. It catches regressions while the agent still has the edit in context.

Fast path

Check hook state inside your AI tool:

/impeccable hooks status

Turn the hook on or off for this project:

/impeccable hooks on
/impeccable hooks off

Installer and updater commands can skip hook setup for one run:

npx impeccable install --no-hooks
npx impeccable update --no-hooks

What it does

The hook scans direct edits to UI code and styles. When it finds a new issue, it sends the agent a short reminder with the finding and a fix direction.

Claude Code, GitHub Copilot, and Codex run after the edit. Cursor checks proposed writes before they land and blocks only when the detector finds an issue in the proposed UI code.

Plain .ts and .js files are scanned, but the hook stays quiet unless it finds something design-relevant.

Handling intentional findings

Persist an exception only after you confirm the finding is intentional. Prefer the narrowest exception:

/impeccable hooks ignore-value overused-font Inter --shared --reason "Brand font"
/impeccable hooks ignore-file "src/legacy/Card.tsx"
/impeccable hooks ignore-rule side-tab

For value-specific rules such as overused-font, use ignore-value for a specific font. Use ignore-rule overused-font --all-values only when you want to suppress the entire rule.

The terminal equivalent is npx impeccable ignores ..., which writes the same detector config. See Config and ignores.

Details when the default path is not enough

Supported harnesses and approval steps

npx impeccable install and npx impeccable update install provider-native hook manifests for Claude Code, GitHub Copilot, Codex, and Cursor.

• Claude Code: .claude/settings.local.json by default.
• GitHub Copilot: .github/hooks/impeccable.json, a committed file shared by the Copilot CLI and the cloud agent.
• Codex: .codex/hooks.json.
• Cursor: .cursor/hooks.json.

GitHub Copilot reads the committed .github/hooks/impeccable.json. In the Copilot CLI the hook activates once that file is on the repository's default branch and you trust the folder; the cloud agent reads it straight from the repo.

Codex requires one extra approval step. After install or update, open /hooks in Codex and approve the project hook. Codex tracks trust by hook definition, so updates can require approval again.

Cursor users should also confirm hooks are enabled in Cursor Settings -> Hooks.

Scanned file types

The hook scans common UI and style files:

.tsx, .jsx, .html, .vue, .svelte, .astro, .css, .scss, .sass, .less, .ts, and .js.

Config and environment overrides

Hook lifecycle settings live under hook in .impeccable/config.json:

{
  "hook": {
    "enabled": true,
    "quiet": false,
    "auditLog": ".impeccable/hook.ndjson"
  }
}

Per-developer choices, including install consent, live in .impeccable/config.local.json.

Detector filters live under detector, not hook, because they are shared by the hook and the CLI detector.

Environment variables still override config for one shell: IMPECCABLE_HOOK_DISABLED, IMPECCABLE_HOOK_QUIET, and IMPECCABLE_HOOK_LOG.

Debugging hook behavior

Start with status:

/impeccable hooks status

It shows the shared and local config paths, current ignores, hook state, and relevant environment overrides.

For invocation logs, set hook.auditLog or use IMPECCABLE_HOOK_LOG. The hook writes one NDJSON line per invocation. Leave audit logging off for normal work.

If a manifest is malformed, install/update aborts by default. Re-run with --force only when you want Impeccable to back up the malformed file as .bak and replace it.