Introduction

Welcome to the Checkle documentation! Checkle is a fast and versatile file integrity checker designed for modern systems.

What is Checkle?

Checkle is a command-line tool that helps you verify file integrity through various hash algorithms. It's built with performance in mind, utilizing parallel processing and SIMD acceleration where available.

Key Features

  • Multiple Hash Algorithms: Support for MD5, SHA-256, SHA-512, BLAKE3, and more
  • High Performance: Parallel processing and SIMD acceleration
  • Archive Support: Check files within archives without extraction
  • Flexible Output: JSON, CSV, or human-readable formats
  • Cross-Platform: Works on Linux, macOS, and Windows

Quick Example

# Generate checksums for all files in a directory
checkle -a sha256 /path/to/directory

# Verify checksums from a file
checkle verify checksums.txt

# Check specific files with multiple algorithms
checkle -a md5,sha256,blake3 file1.txt file2.bin

Getting Started

Head over to the Installation guide to get started with Checkle.

Installation

checkle offers multiple installation methods to suit different preferences and use cases.

The quickest way to get started is using our installation script:

# Standard build
curl -fsSL https://raw.githubusercontent.com/nrminor/checkle/main/INSTALL.sh | sh

# SIMD-optimized build (faster, requires modern CPU)
curl -fsSL https://raw.githubusercontent.com/nrminor/checkle/main/INSTALL.sh | sh -s -- --simd

Manual Binary Download

Download precompiled binaries from releases:

# SIMD-optimized (recommended for modern CPUs)
wget https://github.com/nrminor/checkle/releases/latest/download/checkle-x86_64-unknown-linux-gnu-simd.tar.gz
tar -xzf checkle-x86_64-unknown-linux-gnu-simd.tar.gz
sudo mv checkle /usr/local/bin/

# Standard compatibility version
wget https://github.com/nrminor/checkle/releases/latest/download/checkle-x86_64-unknown-linux-gnu.tar.gz

Cargo Install

If you have Rust installed, you can build and install checkle using Cargo:

# From crates.io (when published)
cargo install checkle

# With cargo-binstall (if available)
cargo binstall checkle

# From source
cargo install --git https://github.com/nrminor/checkle

Verification

After installation, verify that checkle is working correctly:

checkle --version

You should see output showing the installed version of checkle.

SIMD vs Standard Builds

checkle offers two build variants:

  • SIMD-optimized: Faster performance using advanced CPU instructions. Requires modern CPUs (x86_64 with SSE4.2+ or ARM64 with NEON).
  • Standard: Maximum compatibility across different hardware platforms.

For best performance on modern systems, use the SIMD-optimized build. If you encounter issues or are using older hardware, use the standard build.

Quick Start

Command Line Usage

Configuration

Hash Algorithms

Performance

Archive Support

CLI Reference

Configuration Reference

Development Setup

Building from Source

Working with AI Agents

As AI coding agents continue to improve, generated code is increasingly a part of the software development process, and indeed projects that plan to use AI-generated code should be structured to provide maximum context--including goals, style and API design guidelines, and non-negotiable development rules--to make agents effective. The checkle codebase is designed to do just that. Starting with AGENTS.md and including additional context in the context/ directory, the codebase comes with many specific requirements and guidelines that all AI agents must follow to ensure code quality and maintainability.

Strict Rule Compliance

AI agents working on checkle must follow all development rules without exception. At minimum, this includes:

  • Quality Checks: Run cargo fmt, cargo check, and cargo clippy --all-targets --all-features -- -D warnings before declaring any work complete
  • No Lint Suppressions: Never add #[allow()] lint suppressions without explicit permission from the project maintainer. clippy lints operate under an opt-out default principle, which means project lints are exceptionally strict and demanding unless exceptions have been explicitly approved. This keeps coding agents "on the rails" quite effectively while also providing specific, achievable feedback on how to verify that a feature is actually finished.
  • Three-Test Rule: Every change must include at least 3 new, improved tests, or replaced tests

Frequent Context Loading

Before making any changes, AI agents must read and understand these documents:

  1. AGENTS.md - Complete development guidelines and project rules
  2. README.md - Project overview and goals
  3. TIGER_STYLE.md - World-class software robustness principles
  4. GRUG BRAIN DEVELOPER - Pragmatic simplicity principles

It is also recommended that agents review these documents after implementing a feature to ensure that the submitted code is standards-compliant and leaves the codebase better than it was found.

Essential Guidelines for AI Agents

Performance Focus

checkle is designed for bioinformatics workflows with terabyte-scale files. Always consider:

  • Multicore utilization and parallel processing
  • Memory efficiency for large file handling
  • Merkle tree optimization opportunities
  • Buffer reuse and minimal allocations

Code Quality Standards

The project enforces extremely strict quality standards:

  • Zero clippy warnings allowed
  • Comprehensive test coverage required
  • No unwrap() calls in production code
  • Proper error handling with context

Balance Principles

Follow both development philosophies:

  • Tiger Style: Robustness, assertions, resource limits
  • Grug Brain: Simplicity, avoiding premature complexity

When these conflict, prefer solutions that are both robust AND simple.

Bioinformatics Context

Remember that checkle serves genomics researchers who:

  • Work with files that can be 500GB+ each
  • Need reliable integrity verification for critical data
  • Require fast batch processing of many large files
  • Value performance and correctness over feature richness

Critical Requirements

Documentation Reading

Working without reading the required documents (AGENTS.md, README.md, TIGER_STYLE.md, GRUG BRAIN DEVELOPER) is unacceptable and will result in code rejection.

Error Prevention

Common mistakes AI agents must avoid:

  • Adding dependencies without approval
  • Skipping quality checks
  • Writing tests that only verify assertions
  • Adding complexity without clear benefit
  • Ignoring performance implications

Success Criteria

Code is considered complete only when:

  1. All quality checks pass without warnings
  2. At least 3 meaningful tests are included
  3. Performance implications have been considered
  4. Tiger Style and Grug Brain principles are balanced
  5. The change serves the bioinformatics use case

Getting Started

  1. Read all required documentation
  2. Understand the specific task requirements
  3. Consider performance and simplicity implications
  4. Implement with comprehensive error handling
  5. Add thorough tests
  6. Run all quality checks
  7. Document any architectural decisions

By following these guidelines, AI agents can contribute effectively to checkle while maintaining the high standards that make it reliable for critical bioinformatics workflows.