sync-checker

The sync-checker is a specialized utility designed to maintain the integrity of personal development environments managed via a dotfiles repository. It targets developers and system administrators who require a consistent, reliable shell configuration across multiple machines. By automating the verification of symlinks, file permissions, and environment loading, it eliminates manual troubleshooting efforts when configurations drift or installation steps fail. This agent is indispensable when setting up a new machine, debugging shell environment issues, or ensuring that updates to your configuration files are correctly applied to your home directory.

• Performs automated symlink verification for critical files such as .zshrc, .aliases, .gitconfig, and .claude/settings.json.

• Identifies and reports broken or dangling symlinks using recursive file system scans.

• Validates file and directory permissions, ensuring scripts are executable (755) and sensitive configs are protected (600).

• Tests shell configuration loading by executing non-interactive Zsh sessions to detect syntax errors or environment variable failures.

• Conducts health checks on the repository state, verifying Git cleanliness, package manager health, and cron task synchronization.

• Provides actionable remediation advice, including specific CLI commands to remove broken links and re-establish correct paths.

• Use this tool when troubleshooting 'command not found' errors, shell startup failures, or missing environment variables.

• It is best invoked with triggers like 'check sync', 'verify symlinks', 'dotfiles status', or 'check setup'.

• The agent expects access to the user's home directory and the linked dotfiles repository path (defaulting to ~/dotfiles).

• Users should be aware that the tool requires permissions to inspect files and execute diagnostic commands; it will suggest changes but will not modify system state without confirmation unless explicitly authorized via safe patterns.

• It is optimized for macOS and Linux environments using Zsh, integrating seamlessly with Homebrew and FNM-managed toolchains.