HookRunner

A cross-platform pre-commit hook system with DAG-based execution, policy enforcement, remote policy support, and secret detection.

🚀 Single binary, zero dependencies — Works on Windows, macOS, and Linux out of the box.

✨ Key Features

🔀 DAG Execution

Parallel hook execution with proper dependency ordering

🛡️ Policy Engine

Enforce organizational rules and standards

🌐 Remote Policies

Fetch and cache policies from HTTPS endpoints

🔐 Secret Detection

Prevent accidental credential commits

📊 Comparison

Feature	pre-commit	Husky	Lefthook	HookRunner
Single Binary	❌	❌	✅	✅
Policy Engine	❌	❌	❌	✅
Remote Policies	❌	❌	❌	✅
DAG Execution	❌	❌	❌	✅
Multi-language	✅	❌	✅	✅
Cross-platform	❌	❌	✅	✅

📦 Installation

Using Go

go install github.com/ashavijit/hookrunner/cmd/hookrunner@latest

Quick Install

🐧 Linux / macOS

curl -sSL https://raw.githubusercontent.com/ashavijit/hookrunner/master/scripts/install.sh | bash

🪟 Windows

iwr -useb https://raw.githubusercontent.com/ashavijit/hookrunner/master/scripts/install.ps1 | iex

From Source

git clone https://github.com/ashavijit/hookrunner.git
cd hookrunner
go build -o hookrunner ./cmd/hookrunner

🚀 Quick Start

# Initialize with Go preset
hookrunner init --lang go

# Install git hooks
hookrunner install

# Make a commit (hooks run automatically)
git commit -m "feat: add new feature"

💡 Tip: Use hookrunner run pre-commit --all-files --fix to run hooks manually with auto-fix.

⚙️ Configuration

HookRunner supports hooks.yaml, hooks.yml, or hooks.json:

hooks:
  pre-commit:
    - name: format
      tool: go
      args: ["fmt", "./..."]

    - name: lint
      tool: golangci-lint
      after: format  # Runs after format completes

🛡️ Policy System

Available Rules

Rule	Description
`max_files_changed`	Limit commit size
`forbid_files`	Regex-based file bans
`forbid_directories`	Block specific directories
`commit_message`	Regex validation for messages
`max_parallel_hooks`	Control concurrency

Commands

hookrunner policy list        # List active policies
hookrunner policy fetch       # Fetch remote policies
hookrunner policy clear-cache # Clear policy cache

🔀 DAG Execution Engine

[format]  [lint]  [security]
    │        │
    └────────┴────► [test]

⚡ Parallel — Independent hooks run concurrently
🚫 Cycle Detection — Rejects invalid dependency graphs
🎯 Deterministic — Same order across all platforms

🗂️ Language Presets

Language	Tools
Go	gofmt, govet, golangci-lint
Node.js	eslint, prettier, npm test
Python	black, flake8, mypy, pytest
Java	checkstyle, spotless, maven
Ruby	rubocop, rspec
Rust	cargo fmt, clippy, cargo test

🔧 CLI Reference

hookrunner init          # Initialize hooks
hookrunner install       # Install git hooks
hookrunner run <hook>    # Run specific hook
hookrunner doctor        # Diagnose issues

Flags:

--all-files — Run on all files
--fix — Auto-fix issues
--dry-run — Preview without executing
--cached — Only staged files

🔄 CI/CD Integration

GitHub Actions

- uses: actions/checkout@v4
- run: go install github.com/ashavijit/hookrunner/cmd/hookrunner@latest
- run: hookrunner run pre-commit --all-files

🤝 Contributing

git checkout -b feature/my-feature
go test ./...
golangci-lint run
git commit -m "feat: add feature"