Audit Hooks Command

Audit Claude Code hooks for quality, compliance, and maintainability.

Initialization

Before auditing, initialize the environment:

Get the current UTC date, capture the project root path, ensure the temp directory exists, and clean up any stale audit files if the user confirms. The hook-management skill provides authoritative validation guidance (auto-loaded when this command runs).

What Gets Audited

• hooks.json configuration structure and validity
• Hook script existence and structure
• Matcher configuration appropriateness
• Environment variable naming conventions
• Decision control usage
• Test existence and coverage

Command Arguments

Argument	Description
(none)	Smart mode: audit only modified, never-audited, or stale (>90 days) hooks
--force	Audit ALL hooks regardless of status
--plugin-only	Only audit local plugin hooks
--project-only	Only audit project hooks (.claude/hooks/)
--global-only	Only audit globally installed plugin hooks
hook-name	Audit specific hook(s) by name
plugin:name	Explicitly target plugin hook

Step 1: Discover Hook Sources

Detect all hook sources in local repo and globally installed plugins.

For local discovery, check marketplace repos, single plugin repos, and .claude/hooks/. Track plugin names for deduplication.

For global discovery, check ~/.claude/plugins/ (Unix) or %USERPROFILE%\.claude\plugins\ (Windows). Skip globals that have local dev versions.

Step 2: Parse Arguments

Parse flags and hook names. Read audit logs for each source.

Step 3: Present Audit Plan

Display mode, sources discovered, deduplication status, and audit queue.

Step 4: Execute Audits

For each hook, spawn the hook-auditor subagent with source, path, and last audit date. Run in parallel batches of 3-5.

Subagents write findings to .claude/temp/. The main conversation thread collects results and updates audit logs using its Write/Edit tools.

Step 5: Final Summary

Report total audited by source, results, and details table. Note that global hook fixes must be applied manually.

Important Notes

Deduplication

Local dev repo plugins take precedence over globally installed versions. Global hooks are read-only - report findings but recommend manual fixes.

Cross-Platform Paths

Platform	Global Plugins
Unix	~/.claude/plugins/
Windows	%USERPROFILE%\.claude\plugins\

Audit Log Location

All audit results are written to .claude/audit/hooks.md.

Use /audit-log hooks to view current audit status.

Example Usage

Example 1: Audit All Hooks

User: /audit-hooks

Claude: Discovering hook sources...

## Audit Plan
**Mode**: SMART
- Plugin: claude-ecosystem (4 hooks)
- Local: .claude/hooks/ (2 hooks)
- Deduplicated: claude-ecosystem (global skipped)

**Will audit**: 3 hooks

[Spawns hook-auditor subagents]

## Audit Complete
| Source | Hook | Result | Score |
| --- | --- | --- | --- |
| plugin | prevent-backup-files | PASS | 100/100 |

Example 2: Audit Specific Hook

User: /audit-hooks plugin:prevent-backup-files
Claude: PASS (Score: 100/100)