SkillAgentSearch skills...

Bitcheck

BitCheck - The simple and fast data integrity checker!

GenerateConvertImprove

Install / Use

/learn @AlanBarber/Bitcheck
About this skill

Quality Score

0/100

Category

Operations

Supported Platforms

Universal

README

BitCheck - Data Integrity Monitor

GitHub Release GitHub Actions Workflow Status GitHub Downloads (all assets, all releases) GitHub License

Monitor your data for silent corruption (bitrot) with automated file integrity checking.

BitCheck is a fast, cross-platform CLI tool that detects file corruption by tracking file hashes over time. Perfect for monitoring important documents, photos, backups, and archives for gradual data degradation.

Why BitCheck?

  • 🛡️ Detect corruption early - Find bitrot before it's too late
  • ⚡ Lightning fast - Uses the extremely fast XxHash64 to validate files
  • 🎯 Simple to use - Just a few commands: add, check, update, delete
  • 🧠 Smart checking - Automatically distinguishes intentional edits from corruption
  • 🔒 Safe & reliable - Gracefully handles locked files and permission issues
  • 📁 Per-directory tracking - Each folder maintains its own database
  • 🌍 Cross-platform - Works on Windows, Linux, and macOS

Quick Start

1. Download

Get the latest release for your platform from the Releases page:

| Platform | Download | |----------|----------| | Windows | bitcheck-win-x64.exe | | Linux | bitcheck-linux-x64 | | macOS (Intel) | bitcheck-osx-x64 | | macOS (Apple Silicon) | bitcheck-osx-arm64 |

2. Make Executable (Linux/macOS only)

chmod +x bitcheck-linux-x64  # or bitcheck-osx-x64 or bitcheck-osx-arm64

3. Start Monitoring Your Files

# Add all files in current directory to database
bitcheck --add --recursive

# Check for corruption
bitcheck --check --recursive

That's it! BitCheck will create a .bitcheck.db file in each directory to track file integrity.

How It Works

BitCheck creates a .bitcheck.db file in each directory containing hash fingerprints of your files. When you run a check, it recomputes the hashes and compares them to detect any changes or corruption.

Smart Check Mode (Default)

BitCheck uses smart checking by default to distinguish between intentional file changes and corruption:

  • Intentional changes: If a file's hash changes AND its modification date changed, BitCheck treats it as an intentional edit and automatically updates the hash
  • Corruption detected: If a file's hash changes BUT its modification date is unchanged, BitCheck reports it as possible corruption (bitrot)

This makes BitCheck practical for real-world use where files are frequently edited, while still catching true corruption.

Use --strict mode if you want to report all hash mismatches as corruption, regardless of modification date. In strict mode, files with changed creation dates will also prevent auto-updates.

Use --timestamps mode if you want to verify that both creation and modification dates remain unchanged, in addition to the file hash. This is useful for detecting file system manipulation or when files are copied/moved.

Basic Commands

| Command | Purpose | |---------|----------| | bitcheck --add | Add new files to the database | | bitcheck --check | Check files for corruption | | bitcheck --update | Update hashes for intentionally modified files | | bitcheck --add --check | Add new files AND check existing ones |

Command Options

  • -a, --add - Add new files to the database
  • -c, --check - Check files against stored hashes (smart mode by default)
  • -u, --update - Update hashes for files that have changed
  • -r, --recursive - Process subdirectories
  • -v, --verbose - Show detailed output
  • -s, --strict - Strict mode: report all hash mismatches as corruption, prevents auto-update if creation date changed
  • -t, --timestamps - Timestamp mode: flag file as changed if hash, created date, or modified date do not match
  • --single-db - Single database mode: use one database file in root directory with relative paths
  • -f, --file <path> - Process a single file instead of scanning directories
  • -d, --delete - Delete a file record from the database (only valid with --file)
  • -i, --info - Show database information for a single file (only valid with --file)
  • -l, --list - List all files tracked in the database
  • --help - Show help information

Usage Examples

Monitor Your Files (First Time)

# Add all files in current directory
bitcheck --add

# Add all files recursively
bitcheck --add --recursive

Output (single directory):

BitCheck - Data Integrity Monitor
Mode: Add 
Recursive: False

[ADD] document.pdf
[ADD] photo.jpg
[ADD] data.xlsx

=== Summary ===
Files processed: 3
Files added: 3
Files skipped: 0
Total bytes read: 2.45 MB
Time elapsed: 00:00:00

Output (recursive with multiple directories):

BitCheck - Data Integrity Monitor
Mode: Add 
Recursive: True

Directory: /home/user/documents
[ADD] report.pdf
[ADD] notes.txt

Directory: /home/user/documents/photos
[ADD] vacation.jpg
[ADD] family.png

=== Summary ===
Files processed: 4
Files added: 4
Files skipped: 0
Total bytes read: 3.21 MB
Time elapsed: 00:00:00

Check for Corruption (Regular Use)

# Check all files in current directory
bitcheck --check

# Check all files recursively
bitcheck --check --recursive

Output (all OK):

BitCheck - Data Integrity Monitor
Mode: Check 
Recursive: False

=== Summary ===
Files processed: 3
Files checked: 3
Mismatches: 0
Files skipped: 0
Total bytes read: 2.45 MB
Time elapsed: 00:00:00

Output (intentional file change - smart mode):

BitCheck - Data Integrity Monitor
Mode: Check 
Recursive: False

[UPDATED] document.pdf - File was modified (2025-11-07 04:36:26 UTC)

=== Summary ===
Files processed: 3
Files checked: 3
Mismatches: 0
Files skipped: 0
Total bytes read: 2.45 MB
Time elapsed: 00:00:00

Output (recursive mode with changes in subdirectories):

BitCheck - Data Integrity Monitor
Mode: Check 
Recursive: True

Directory: /home/user/documents/reports
[UPDATED] quarterly.pdf - File was modified (2025-11-07 04:36:26 UTC)

Directory: /home/user/documents/archives
[UPDATED] backup.zip - File was modified (2025-11-07 04:38:15 UTC)

=== Summary ===
Files processed: 15
Files checked: 15
Mismatches: 0
Files skipped: 0
Total bytes read: 12.34 MB
Time elapsed: 00:00:00

Output (corruption detected - modification date unchanged):

BitCheck - Data Integrity Monitor
Mode: Check 
Recursive: False

[MISMATCH] data.xlsx
  Expected: A1B2C3D4E5F6G7H8
  Got:      X9Y8Z7W6V5U4T3S2
  File modification date unchanged: 2025-11-05 12:00:00 UTC
  Possible corruption detected!

=== Summary ===
Files processed: 3
Files checked: 3
Mismatches: 1
Files skipped: 0
Total bytes read: 2.45 MB
Time elapsed: 00:00:00

WARNING: 1 file(s) failed integrity check!

Strict Mode (Report All Changes as Corruption)

# Use strict mode to report all hash mismatches, even if file was modified
bitcheck --check --strict

# Useful for read-only media or when you want maximum sensitivity

Output:

BitCheck - Data Integrity Monitor
Mode: Check 
Recursive: False

[MISMATCH] document.pdf
  Expected: A1B2C3D4E5F6G7H8
  Got:      F1E2D3C4B5A69788
  Last successful check: 2025-11-07 04:36:31 UTC

=== Summary ===
Files processed: 3
Files checked: 3
Mismatches: 1
Files skipped: 0
Total bytes read: 2.45 MB
Time elapsed: 00:00:00

WARNING: 1 file(s) failed integrity check!

Timestamp Mode (Verify Creation and Modification Dates)

# Check that hash AND timestamps haven't changed
bitcheck --check --timestamps

# Useful for detecting file system manipulation or copied files

Output (timestamp mismatch detected):

BitCheck - Data Integrity Monitor
Mode: Check 
Recursive: False

[MISMATCH] document.pdf
  Expected hash: A1B2C3D4E5F6G7H8
  Got hash:      A1B2C3D4E5F6G7H8
  Expected modified: 2025-11-05 12:00:00 UTC
  Got modified:      2025-11-07 14:30:00 UTC
  Expected created:  2025-11-01 10:00:00 UTC
  Got created:       2025-11-07 14:30:00 UTC
  Last successful check: 2025-11-07 04:36:31 UTC

=== Summary ===
Files processed: 3
Files checked: 3
Mismatches: 1
Files skipped: 0
Total bytes read: 2.45 MB
Time elapsed: 00:00:00

WARNING: 1 file(s) failed integrity check!

Note: Creation dates are always tracked in the database, but only verified when --timestamps flag is used.

Single File Mode (Process Individual Files)

Instead of scanning entire directories, you can process a single file using the --file option:

# Add a single file to the database
bitcheck --file document.pdf --add

# Check a single file
bitcheck --file document.pdf --check

# Update a single file's hash
bitcheck --file document.pdf --update

# Delete a file record from the database
bitcheck --file document.pdf --delete

Output (add single file):

BitCheck - Data Integrity Monitor
Mode: Add
Single File: document.pdf

[ADD] document.pdf

=== Summary ===
Files processed: 1
Files added: 1
Files skipped: 0
Total bytes read: 1.23 MB
Time elapsed: 00:00:00

Output (delete from database):

BitCheck - Data Integrity Monitor
Mode: Delete
Single File: document.pdf

[DELETED] document.pdf - Removed from database

=== Summary ===
Files processed: 0
Files removed from database: 1
Files skipped: 0
Total bytes read: 0 B
Time elapsed: 00:00:00

Benefits of Single File Mode:

  • ✅ Targeted operations - Process specific files without scanning directories
  • ✅ Faster execution - No dir

AlanBarber

View profile

View on GitHub
GitHub Stars17
CategoryOperations
Updated25d ago
Forks0
AlanBarber/bitcheck

Languages

C#

Security Score

95/100

Audited on Feb 24, 2026

No findings