Getting started

Set up hk in an existing Git repository, then use the same linters when you commit, work locally, and run CI.

Installation

Choose one installation method:

mise

mise use hk

Homebrew

brew install hk

Cargo

cargo install hk --locked

Verify the installation:

hk --version

Prebuilt binaries are also available from GitHub releases. hk uses the built-in pklr evaluator by default, so you do not need to install the Pkl CLI.

Project setup

From the root of your repository, generate a configuration:

hk init

hk detects tools from project files and creates hk.pkl. Review its steps before running them. To select tools and hooks yourself, use hk init --interactive.

Make the linters available

Builtins configure commands; they do not install the tools they invoke. Install the selected linters with your project’s package manager or mise, and make sure hk can find them on PATH.

Install hooks

Choose the scope that fits your setup:

Scope	Command	Behavior
All repositories, Git 2.54+	hk install --global	Install once in your user Git config; projects without an hk configuration are skipped
Current repository	hk install	Install the hooks defined in this project; supports older Git versions

On Git 2.54+, hk uses Git’s configuration-based hooks. On older Git, a per-repository install writes script shims. Use hk install --legacy to request shims explicitly.

If hk is already installed globally, hk install skips the local installation and cleans up stale local hk hooks. --force-local overrides that behavior, but combining local and global hooks can cause duplicate runs.

Using mise tools in Git hooks

On Git 2.54+, use the recommended hk install --global --mise to launch hooks through mise x. The installer records mise’s path, so mise must be on PATH during installation but Git does not need it on its runtime PATH. For a repository-scoped installation on any supported Git version, use hk install --mise; this local launcher requires mise on Git’s runtime PATH.

Commit hk.pkl so your team can share the configuration. Hook installation is local to each developer’s machine or clone.

To remove an installation, use hk uninstall or hk uninstall --global. See the install reference for all options.

Your first configuration

This complete example runs Prettier, ESLint, and Ruff. Install and configure those tools first, or replace them with builtins that match your project.

amends "package://github.com/jdx/hk/releases/download/v2.0.1/hk@2.0.1#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v2.0.1/hk@2.0.1#/Builtins.pkl"

steps {
  ["prettier"] = Builtins.prettier
  ["eslint"] = Builtins.eslint
  ["ruff"] = Builtins.ruff
}

The amends line loads hk’s configuration schema. Builtins supplies reusable step definitions. Top-level steps is the recommended starting point: hk creates check, fix, and pre-commit hooks that share these steps.

In this configuration, pre-commit fixes staged files while unstaged work is stashed. check checks your working tree, and fix applies fixes to it. Steps whose file patterns do not match any selected files are skipped.

Top-level steps is optional. You can instead define steps only inside explicit hooks, or use explicit hooks to customize the shared setup. See hook defaults.

Validate the configuration without running its linters:

hk validate

Checking and fixing code

hk check             # Check modified files
hk fix               # Apply available fixes
hk check --all       # Check all files, useful for CI
hk check src/main.ts # Check a specific file
hk check --step eslint

With the configuration above, modified files include staged, unstaged, and untracked files. --all selects tracked files plus eligible untracked files; ignore rules and exclusions still apply. Hook settings and flags can change file selection.

Check commands should be read-only. Fix commands may edit files, and some findings need a manual fix. hk fix leaves fixes unstaged by default; use hk fix --stage to stage them. The default pre-commit hook stages its fixes. Review git diff and git diff --cached.

Preview a run

Use the plan to see which steps and files hk selects:

hk check --plan
hk check --why eslint
hk check --all --plan --json

These commands do not execute the hook’s steps. See troubleshooting if a step is missing or behaves unexpectedly.

Running hooks

After installation, Git invokes configured hooks automatically. You can also invoke them directly:

hk run pre-commit

A manual hook run uses the hook’s configured behavior, including fixes, staging, and stashing. To inspect it first, use hk run pre-commit --plan.

Next steps

• Git hooks and stashing: control automatic fixes and partial commits.
• Continuous integration: check a full repository or a branch.
• Configuration examples: start from a JavaScript, Python, or monorepo setup.
• Configuration: customize steps, profiles, and local overrides.