hk

A fast, language-agnostic git hook manager and project linter.

hk runs linters concurrently while coordinating access to files with read/write locks. This lets formatters and other tools safely work on overlapping files without racing or silently overwriting one another's changes.

• Runs independent checks and fixes in parallel
• Safely handles partially staged files by stashing and restoring unstaged changes
• Includes built-in configurations for common linters and formatters
• Uses typed Pkl configuration
• Integrates with mise for tool and task management
• Provides fast native checks for common issues such as trailing whitespace and merge conflicts

Quick start

From the project you want to configure, install hk with mise:

cd my-project
mise use hk
hk --version

With Git 2.54 or newer, install hk's hooks once for every repository on your machine:

hk install --global

Then enable hk in a project:

hk init

hk init detects relevant linters and creates an hk.pkl configuration. Review the detected linters, or use hk init --interactive to select them yourself. You can then commit as usual; hk runs the configured pre-commit hook automatically. Repositories without an hk.pkl are left untouched by the global hooks.

On older Git versions, run hk install in each project instead. See the getting started guide for Homebrew, Cargo, and Aqua installation options and detailed hook setup.

Example configuration

The generated hk.pkl uses hk's built-in linter definitions, which you can extend when a project needs different behavior:

amends "package://github.com/jdx/hk/releases/download/v1.58.1/hk@1.58.1#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v1.58.1/hk@1.58.1#/Builtins.pkl"

local linters = new Mapping<String, Step> {
  ["eslint"] = Builtins.eslint
  ["prettier"] = (Builtins.prettier) {
    glob = List("*.js", "*.ts", "*.json", "*.md")
  }
}

hooks {
  ["pre-commit"] {
    fix = true
    stash = "git"
    steps = linters
  }
  ["check"] {
    steps = linters
  }
  ["fix"] {
    fix = true
    steps = linters
  }
}

Run the same checks directly at any time:

hk check        # check modified files
hk fix          # fix modified files
hk check --all  # check the entire repository, useful in CI

Agent skills

hk includes two skills for coding agents:

• hk-configure: add linters and custom checks, preserve the project's Pkl schema version, and verify which files each step selects.
• hk-debug: diagnose hook failures, skipped steps, configuration overrides, and partially staged files.

Both skills ship in the skills/ directory of each release archive. hk's packslip manifest points to those directories, so compatible installers can use the bundled instructions without a separate repository download. Making them available to an agent is opt-in; see mise's skills documentation.

Documentation

• Getting started
• Configuration reference
• Configuration examples
• Built-in linters
• CLI reference
• Why hk?
• Contributing

Sponsors

Sponsored by

   

View all sponsors

Demo

CI

Thanks to Namespace for providing CI for hk.