Monitor File Validator

Monitors and validates file integrity after every write operation, checking for syntax errors, encoding issues, and file corruption in real-time.

When to Use This Hook

Attach this hook when you need to:

• Automatically validate file syntax after every write operation to catch malformed JSON, YAML, XML, or code files immediately
• Detect file encoding issues and BOM markers that can cause subtle bugs across different operating systems and editors
• Verify that written files match expected checksums or structural patterns to prevent corruption during complex multi-file operations

Consider alternatives when:

• Your language server or IDE provides real-time syntax validation that already covers the same file types
• You are editing binary files or media assets where text-based validation rules do not apply

Quick Start

Configuration

Copy
name: monitor-file-validator
type: hook
trigger: PostToolUse
category: development-tools

Example Trigger

Copy
# Claude writes a new config file:
# Write tool creates config/settings.json
# Hook fires:
# File Validator: Checking config/settings.json...

Example Output

File Validator: Validation Report for config/settings.json
File Type: JSON
Syntax: Valid JSON structure
Encoding: UTF-8 (no BOM)
Size: 2.4KB (within expected range)
Line Endings: LF (consistent with project)
Trailing Newline: Present
Schema Validation: Matches config.schema.json
Permissions: 644 (appropriate for config file)
Status: VALID

Core Concepts

File Validation Overview

Aspect	Details
Trigger Point	PostToolUse on Write, Edit, and MultiEdit operations
Validation Types	Syntax parsing, encoding detection, line ending consistency
Supported Formats	JSON, YAML, TOML, XML, JavaScript, TypeScript, Python, CSS
Schema Validation	Optional JSON Schema or custom validators for config files
Encoding Detection	Identifies UTF-8, UTF-16, ASCII, and detects unexpected BOM markers
Line Ending Check	Verifies consistency with project convention (LF vs CRLF)

Validation Workflow

PostToolUse (Write/Edit/MultiEdit)
    |
    v
[Identify file type from extension]
    |
    v
[Select appropriate validator]
    |
    +--- JSON --> [json.tool parse]
    |
    +--- YAML --> [yaml.safe_load check]
    |
    +--- JS/TS --> [syntax check via node --check]
    |
    +--- Python --> [py_compile check]
    |
    +--- Other --> [encoding + line ending only]
    |
    v
[Check encoding and BOM]
    |
    v
[Verify line endings match project convention]
    |
    v
[Output validation report]
    |
    +--- Valid --> exit 0
    +--- Invalid --> exit 2 (report to stderr)

Configuration

Parameter	Type	Default	Description
matcher	string	Write|Edit|MultiEdit	Tool types that trigger file validation
validate_syntax	boolean	true	Whether to perform syntax validation based on file type
check_encoding	boolean	true	Whether to verify file encoding and detect BOM markers
expected_line_ending	string	LF	Expected line ending style for the project: LF or CRLF
schema_dir	string	.claude/schemas/	Directory containing JSON Schema files for config validation

Best Practices

1. Define schemas for critical configuration files - Create JSON Schema files for your most important configuration files like tsconfig.json, package.json, and custom config formats. Schema validation catches structural errors that simple syntax checking misses.

2. Enforce consistent line endings across the project - Set expected_line_ending to match your .gitattributes configuration. Inconsistent line endings cause unnecessary diff noise and can break shell scripts on Unix systems.

3. Use encoding validation to prevent cross-platform issues - Windows editors sometimes add BOM markers to UTF-8 files, which can cause parsing failures on Unix systems. The validator catches these encoding mismatches before they become hard-to-diagnose bugs.

4. Configure validation severity by file type - Not all validation failures are equally important. A syntax error in a JSON config file is critical, while a missing trailing newline in a documentation file is a minor style issue. Configure severity levels per file type.

5. Add custom validators for domain-specific formats - If your project uses custom file formats like DSL configurations or template files, write custom validation scripts and register them with the validator for those file extensions.

Common Issues

1. Syntax validation fails on files with template expressions - Files containing template syntax like ${variable} or <%= expression %> may fail standard JSON or YAML parsing. Add file path exclusions for template directories or use template-aware parsers.

2. Encoding detection reports false positives on binary files - If a binary file is accidentally matched by the file type filter, the encoding check will report issues. Add binary file extensions to the exclusion list to prevent these false positives.

3. Line ending check flags files from external sources - Files downloaded from the web or generated by cross-platform tools may have different line endings than your project convention. Configure the validator to auto-fix line endings rather than just reporting them.