Automated Build Inspector

Monitors and validates build output after every build command, catching errors, warnings, and performance regressions automatically.

When to Use This Hook

Attach this hook when you need to:

• Automatically analyze build output for errors, warnings, and deprecation notices after each build command execution
• Track build performance metrics over time and alert when build duration exceeds established baselines
• Enforce build quality standards by blocking workflows when critical build issues are detected

Consider alternatives when:

• Your CI/CD pipeline already provides comprehensive build analysis and you do not need local real-time feedback
• You are working on small scripts or prototypes where build overhead monitoring adds unnecessary complexity

Quick Start

Configuration

Copy
name: automated-build-inspector
type: hook
trigger: PostToolUse
category: automation

Example Trigger

Copy
npm run build
# Hook output:
# Build Inspector: Analyzing build output...

Example Output

Build Inspector: Analysis Complete
Duration: 14.3s (baseline: 12.1s, +18%)
Warnings: 3 detected
  - Unused import in src/utils/helpers.ts:14
  - Missing return type in src/api/handler.ts:28
  - Deprecated API usage in src/services/auth.ts:42
Errors: 0
Bundle Size: 245KB (previous: 238KB, +2.9%)
Status: PASS with warnings

Core Concepts

Build Analysis Overview

Aspect	Details
Trigger Point	PostToolUse on Bash commands matching build patterns
Supported Build Tools	npm, yarn, pnpm, webpack, vite, turbopack, cargo, go build, make
Output Parsing	Regex-based extraction of errors, warnings, and timing data
History Tracking	Build metrics stored in .claude/build-history.json for trend analysis
Alert Threshold	Configurable percentage increase over baseline triggers warnings
Exit Behavior	Returns exit code 2 for critical failures, 0 for pass or warnings only

Build Inspection Workflow

Bash Command Executed
    |
    v
[Match build pattern?] --No--> [Skip inspection]
    |
   Yes
    |
    v
[Capture stdout/stderr] --> [Parse output]
    |                            |
    v                            v
[Extract timing] --> [Categorize: errors/warnings/info]
    |                            |
    v                            v
[Compare to baseline] --> [Generate report]
    |                            |
    v                            v
[Update history] ---------> [Output summary]

Configuration

Parameter	Type	Default	Description
build_patterns	string	build|compile|make	Regex pattern to match Bash commands that trigger inspection
warning_threshold	integer	10	Maximum number of warnings before the hook reports a failure status
duration_alert_pct	integer	25	Percentage increase in build duration over baseline that triggers an alert
history_file	string	.claude/build-history.json	Path to store historical build metrics for trend analysis
bundle_size_limit	string	500KB	Maximum acceptable bundle size before triggering a warning

Best Practices

1. Establish baselines early in the project - Run several builds before relying on duration alerts so the inspector has accurate baseline data. Without sufficient history, the threshold comparisons produce noisy false positives that undermine trust in the tool.

2. Categorize warnings by severity - Configure the inspector to distinguish between actionable warnings like unused imports and informational notices like deprecation timelines. This prevents warning fatigue and ensures developers focus on issues that genuinely impact code quality.

3. Integrate with your existing CI checks - Use the build inspector as a local pre-flight check that catches issues before they reach CI. Align the inspector's thresholds with your CI pipeline's rules so developers receive consistent feedback locally and remotely.

4. Review bundle size trends weekly - The inspector tracks bundle sizes over time. Review the history file periodically to identify gradual size creep that individual builds might not flag but that accumulates into performance problems for end users.

5. Exclude test builds from baseline calculations - Test-specific builds often have different characteristics than production builds. Configure the pattern matcher to distinguish between npm run build and npm run build:test to maintain accurate baselines.

Common Issues

1. Hook fires on non-build commands - If the build pattern regex is too broad, commands like npm run build-docs or make clean may trigger the inspector unnecessarily. Narrow the build_patterns parameter to match only your specific build commands using anchored patterns.

2. Build duration alerts during dependency updates - After adding new dependencies, build times naturally increase. Reset the baseline by deleting the history file or updating the duration_alert_pct threshold temporarily while the new baseline stabilizes.

3. Output parsing fails for custom build tools - The inspector uses regex patterns designed for common build tool output formats. If your project uses a custom build system, you may need to adjust the parsing patterns or write a wrapper script that normalizes the output format.