Hk Updates & Release Notes

hk 2.5.0 makes stashing safe when hk is killed and when several hk processes run at once, loads configs much faster, and reports diagnostics from many more builtins. It also fixes a long list of cases where a check passed without checking anything, along with several Windows problems.

Highlights

• Stashing holds up under interruption and concurrency. SIGTERM, SIGHUP and crashes no longer leave your unstaged changes stuck in git stash. Hooks running in linked worktrees now take turns stashing. Several edge cases that dropped or mixed up changes are fixed.
• Configs load faster. A cold config load drops from about 1.4 s to about 0.07 s, and hk validate is about 14x faster. Several per-step and stashing costs are lower in large repos.
• Fewer checks pass when they should fail. hk validate now catches more config mistakes. Several builtins and hk util checks no longer skip binary files, case conflicts in directory names, or executable bits recorded in git.

Added …

In hk fix, many more builtins now apply their check_diff patch instead of running the tool a second time as the fixer. hk now applies those patches itself instead of calling git apply, and read-only check_diff commands can run in parallel with other steps that read the same files.

Added

• hk util format-diff (#1514, @jdx). Builds an applicable patch from any formatter that reads stdin and writes the formatted file to stdout. It runs the formatter once per file, in parallel, and replaces {} with the file's path. It exits 1 with a patch when a file would change, and 0 when nothing would. If the formatter fails for any file or prints nothing for a non-empty file, it prints no patch, so hk runs fix and that reports the error. Use --no-stdin for formatters that read the file from its path.

  check_diff = "hk util format-diff {{files}} -- stylua --stdin-filepath {} -"
  

• hk util sarif-diff (#1515, @jdx). Runs a tool that reports fixes in a SARIF log and turns them into a patch. It prints a patch only when every result has a usable fix. If any result has no fix, or the tool fails, it prints no patch and hk runs fix. The findings exit code defaults to 1 and can be changed with --findings-exit-code.

  check_diff = "hk util sarif-diff -- pinact run --check --format sarif {{files}}"
  ``` …
  

hk now starts faster, spends less of its own time per file, and spreads --jobs more evenly across batched steps. This release also fixes several cases where stashing could lose files, fail before any step ran, or leave untracked files visible to steps.

Added

• apply_check_diff step setting (#1495, @jdx). Defaults to true. If you set it to false, hk fix runs the step's fix command instead of applying the check_diff output, and hk check still shows the diff. In staging hooks such as pre-commit, hk still runs check_diff first and passes fix only the files the diff names. The trailing_whitespace and newlines builtins now use it. Together with a parallel file scan in hk util trailing-whitespace and hk util end-of-file-fixer, this roughly halves the time of those two steps on a whole-repo fix.

  ["my-fixer"] {
    check_diff = "my-fixer --diff {{files}}"
    fix = "my-fixer --write {{files}}"
    apply_check_diff = false
  }
  

Changed …

Staging hooks such as pre-commit now stage each fixer's files as soon as that fixer finishes, and hk fix --all makes better use of --jobs. This release also adds a batch_min_files step setting and fixes the jq/yq builtins, stashing before the first commit, and an intermittent git crash during concurrent staging.

Added

• batch_min_files for batched steps (#1475, @jdx). Steps with batch = true can set the minimum number of files hk passes to one process. The default is still 4. Raising it means fewer processes, which helps tools with slow startup, such as prettier and eslint, on whole-tree runs. In hk's benchmark, batch_min_files = 200 on prettier and eslint cut hk check --all from 1.56 s to 1.33 s. It made a small pre-commit a little slower, so the builtins' defaults are unchanged. OS command-length limits can still split a batch below this number.

  steps {
    ["prettier"] = (Builtins.prettier) {
      batch_min_files = 200
    }
  }
  

Changed …

Fix steps now run their fixer directly instead of checking first, and batch steps start fewer processes on small commits. Together these make hk run pre-commit about a third faster on a typical fixture. This release also adds JUnit XML output, hook arguments in conditions, and a hk migrate pre-commit that produces a working config right away. It fixes a staging race between concurrent fixers and a stale config cache when Pkl reads environment variables.

Added

• --junit-xml <PATH> for hk check, hk fix and hk run <hook> (#1432, @sanga). Writes one JUnit <testcase> per step, with its status, duration and captured output, so CI systems such as Jenkins can show hk results. It works alongside --sarif, whatever output format you choose. If a run fails before any step is planned, the report still contains a failing test case, so it doesn't look like a passing build.

• Git hook arguments in condition and step_condition (#1445, @jdx). Conditions can now use the hook variables that command templates already had: prev_head, new_head and is_branch_checkout (post-checkout), commit_msg_file (commit-msg, prepare-commit-msg), source and sha (prepare-commit-msg), hook_stdin (pre-push, post-rewrite), and hook_args (all hooks). Conditions are expr-lang expressions, so write is_branch_checkout, not {{ is_branch_checkout }}.

  hooks { …
  

Fix steps now run their fixer directly instead of checking first, and batch steps start fewer processes on small commits. Together these make hk run pre-commit about a third faster on a typical fixture. This release also adds JUnit XML output, hook arguments in conditions, and a hk migrate pre-commit that produces a working config right away. It fixes a staging race between concurrent fixers and a stale config cache when Pkl reads environment variables.

Added

• --junit-xml <PATH> for hk check, hk fix and hk run <hook> (#1432, @sanga). Writes one JUnit <testcase> per step, with its status, duration and captured output, so CI systems such as Jenkins can show hk results. It works alongside --sarif, whatever output format you choose. If a run fails before any step is planned, the report still contains a failing test case, so it doesn't look like a passing build.

• Git hook arguments in condition and step_condition (#1445, @jdx). Conditions can now use the hook variables that command templates already had: prev_head, new_head and is_branch_checkout (post-checkout), commit_msg_file (commit-msg, prepare-commit-msg), source and sha (prepare-commit-msg), hook_stdin (pre-push, post-rewrite), and hook_args (all hooks). Conditions are expr-lang expressions, so write is_branch_checkout, not {{ is_branch_checkout }}.

  hooks { …
  

hk.pkl can now assemble steps from a glob of Pkl files with the expression form of import*, and hk's config cache finally notices when glob-matched or transitively imported modules change. Three new builtin capabilities land for Kubernetes manifests, .NET projects, and EditorConfig fixes, plus fixes for typos under custom shells and pre-push crashing on unexpected stdin.

Added

• Glob imports in hk configuration (#1423, @jdx). The expression form import*("generated/*.pkl") now evaluates; hk previously rejected it at parse time with unexpected token in expression: KwImportStar, which kept projects that generate step definitions on hk 1.x. The declaration form import* "generated/*.pkl" as generated continues to work. Support comes from upgrading hk's bundled Pkl evaluator to pklr 3.0.

  local generated = import*("generated/*.pkl")
  
  hooks {
    ["check"] {
      steps = new Mapping<String, Step> {
        for (_, mod in generated) {
          ...mod.STEPS
        }
      }
    }
  }
  

  Each matched file exports its own STEPS: Mapping<String, Config.Step>. See the new "Import many files at once" section in the Pkl introduction docs. …

The Terragrunt builtins now catch errors in shared HCL files, kubeconform can be retargeted without breaking its bundled tests, and hk test explains itself when a step's filters exclude every file a test writes. Note that the Terragrunt builtins now require terragrunt 1.0.8 or newer.

Fixed

• terragrunt_hcl_validate catches errors in shared HCL includes (#1371, @sassdavid). Previously the step ran --working-dir once per selected directory, so editing a shared file outside every unit directory (one reached only via include or read_terragrunt_config) validated nothing and passed. Both terragrunt_hcl_validate and terragrunt_hcl_fmt now run a single terragrunt process scoped with --filter; validate adds a directory filter and a reading= filter per selected file so unit configs and shared includes are both covered. On a 39-unit repository this cut fmt from 1650ms to 91ms and validate from 5680ms to 1475ms. Requires terragrunt 1.0.8+, the first release where --filter works on hcl fmt and hcl validate. …

hk 2.0 simplifies configuration around a single shared steps map, stages fixed files only in pre-commit by default, turns builtin variants into typed options, and removes the deprecated v1 configuration files and entry points. Upgrading requires reviewing your hk.pkl; see Breaking Changes below and the v2 migration guide.

Highlights

• Less repetition in hk.pkl: a top-level steps block now defines the check, fix, and pre-commit hooks at once, and builtin variants such as gitleaks_staged or pinact_v3 are replaced by options on the primary builtin (#1255, #1253).
• Predictable staging: only pre-commit stages fixes automatically; hk fix and custom hooks leave the index alone unless you ask (#1256).
• Pkl only: hk.toml/yaml/json, .hkrc.pkl, UserConfig.pkl, hk generate, and the external pkl CLI fallback are gone; hk reports a targeted replacement for each removed input (#1257).
• Nine new builtins for Terraform, Terragrunt, Kubernetes, Markdown, and repository hygiene, plus fixes to rubocop, tf_lint, and zizmor.

Breaking Changes

Shared top-level steps and hook defaults (#1255, @jdx) …

[!IMPORTANT] The original v1.58.0 publishing workflow failed after the tag was created. This backfilled release contains no binary assets and was not published to crates.io. The changes below first became available to installers in v1.58.1; use that version or newer.

This release adds the droast Dockerfile linter and fixes several places where hk's effective behavior diverged from its configuration: project and global Pkl scalar settings now reach the runtime, standalone subdirectory configs stay scoped to their own project, and HK_CHECK plus the corresponding git settings correctly select check or fix commands. Release binaries also regain their embedded Pkl package instead of silently falling back to the network.

Added

• droast Dockerfile linter (@illesnagy1) #1302. The new droast builtin checks Dockerfile, Dockerfile.*, and Containerfile* files and can apply droast's safe, deterministic fixes with hk fix.

Fixed

• Pkl scalar settings now take effect (@jdx) #1307. terminal_progress, walk_ignore, and stash_backup_count are now loaded from project Pkl and user-global configuration, merged with the existing project-first precedence, and shown correctly by hk config dump. …

This release seeds hk with an embedded Pkl package so matching-version configs validate offline on a cold cache, adds templated dir support for workspace-aware steps, and lands a new check_after_diff mechanism that lets partial fixers (like ShellCheck) apply what they can while still reporting what they cannot. It also brings several new Go and lint builtins plus a batch of correctness fixes for Go linters, gitleaks, workspace paths, Windows shims, and stashing.

Added

• Embedded matching-version Pkl package (@sahidvelji) #1218. hk now ships the Pkl package built for its own version and seeds HK_PKL_CACHE_DIR with it before evaluating hk.pkl, so a config pinned to that version validates with no network round trip on a cold cache — a fresh clone, CI runner, new container, or upgrade. Cached content always wins over the embedded copy, and other versions are fetched as before. Set HK_PKL_EMBEDDED=0 to disable seeding. Addresses discussion #1216. …

This release adds a persistent Pkl package cache with offline evaluation, pinact v4 support, a configurable failed-command output file, and a handful of fixes for binary files, builtin argument handling, worktrees, annotated tags, and step conditions.

Added

• Persistent Pkl package cache and offline mode (@jdx) #1199. Pkl packages are now persisted (by default under the platform cache directory as pklr), so a package downloaded during any prior evaluation stays available even after hk's resolved-config cache is invalidated by a config edit, upgrade, or cache cleanup. This prevents local commits from being blocked when a registry is unreachable. Two new environment variables control the behavior: HK_PKL_CACHE_DIR overrides the cache location, and HK_PKL_OFFLINE=1 disables all network access, failing fast with the missing package URL and cache path instead of hitting the network. Both are read from the environment before hk.pkl is evaluated. Addresses discussion #1198.

• pinact v3 and v4 builtins (@risu729) #1195. The pinact and pinact_update builtins now track the latest major version (currently v4.1.1) and use the v4-native --verify-comment flag. New pinact_v3 and pinact_update_v3 alternatives are available for projects still on pinact v3, without requiring changes to step names.

  // pinact v4 (default) …
  

This release turns hk into a first-class tool for coding agents, adding an MCP server, an interactive dashboard, structured and machine-readable output, command effect safety, normalized diagnostics with SARIF export, and one-command integration snippets for popular agents and editors. It also adds a Kingfisher secret-scanner builtin and fixes a couple of file-selection and command-composition bugs.

Highlights

• A complete agent-native workflow: drive hk from anywhere with --cd/--files0-from, get machine-readable results via --format json|jsonl, gate risky steps with --safe, export findings as SARIF, and expose everything to agents over MCP with a live dashboard.
• New hk agent command tree prints ready-to-paste instruction, hook, and MCP setup snippets for Codex, Claude Code, Claude Desktop, and VS Code.

Added

• MCP server for coding agents (@jdx) #1169. hk mcp [--root <path>] starts a STDIO-only Model Context Protocol server built on the official Rust MCP SDK. Agents can inspect projects, read effect-aware execution plans, run all-or-nothing safe checks and fixes, poll run lifecycle, cancel runs, and page through logs and captured diffs. Tools are constrained to canonical startup roots plus client-provided roots, with one active run per root and bounded output/run retention. There is no HTTP listener, hosted service, auth system, or unrestricted shell tool.

  hk mcp --root /path/to/project
  ``` …
  

A small patch release focused on bug fixes across stashing, builtins, config error handling, and conventional-commit validation.

Fixed

• Fixer output preserved with stage=false / fail_on_fix=true (@jdx) #1145. When smart stashing was combined with disabled auto-staging, stash restoration used the post-hook index as the fixer side of its three-way merge. Since the fixer only touched the isolated worktree in that mode, restoration saw no change and silently discarded the formatter output. hk now uses worktree content as the fixer input, merges it with the user's saved unstaged edits, and leaves the original index untouched. Fixes discussion #1144.

• Ruff builtins detect extensionless Python scripts (@jdx) #1147. The ruff and ruff_format builtins previously matched files only with **/*.py and **/*.pyi globs. They now select files using hk's Python type detection, so extensionless scripts with a Python shebang are linted and formatted alongside .py and .pyi files. Fixes discussion #1146. …

17% smaller, up to 31% faster

Compared with v1.53.0, the published x86_64-unknown-linux-gnu release is substantially leaner and faster:

Measurement	v1.53.0	v1.54.0	Improvement
Compressed archive	8.19 MB	7.06 MB	13.8% smaller
Extracted binary	22.01 MB	18.27 MB	17.0% smaller
Startup (--version)	2.21 ms	1.52 ms	31.2% faster
Builtins loading	2.31 ms	1.62 ms	29.8% faster
Config validation	3.69 ms	2.94 ms	20.3% faster
Representative check --all	14.62 ms	13.47 ms	7.8% faster

Measurements use the published release binaries with hermetic state, warm caches, shell overhead excluded, and execution pinned to one CPU. Real hook runs dominated by external linters will see a smaller overall percentage.

---

This release adds an opt-in way to focus detailed check diagnostics on only the files that actually failed, teaches hk's usage spec to declare each command's effect on the world, and speeds up the mixed-line-ending and check-merge-conflict builtins along with a new PGO/BOLT-optimized Linux release binary. It also fixes noise and false errors in a couple of builtins.

Added …

This release adds a cargo-deny builtin, meaningfully speeds up config resolution and hook runs in large repos, and fixes two correctness bugs around dependency graphs and stashing. It also hardens hk's Git invocations against argument injection.

Added

• cargo_deny builtin (@risu729) #1081. Runs cargo-deny for Rust dependency policy checks (advisories, bans, licenses, sources). It triggers on Cargo.toml, Cargo.lock, and deny.toml/.deny.toml (including .cargo/ and exceptions variants), groups executions by Cargo workspace and runs from the workspace directory, and uses --locked so checks never create or update Cargo.lock.

  ["cargo_deny"] = Builtins.cargo_deny
  

Fixed

• Dependents no longer hang after a failed dependency (@jdx) #1099. With fail_fast = false, a failed step returned without marking its dependency watch channel as done, so any step with depends on it waited forever and the run hung. The failed step now signals its dependents so they can proceed. fail_fast = true behavior is unchanged. Fixes discussion #1098. …

This release brings hk to monorepos with nested subprojects configs and per-directory mise environments, adds a --unstaged flag for linting only working-tree changes, and ships a batch of correctness fixes for branch guards, empty remotes, and conventional commit scopes.

Added

• subprojects for monorepos (@jdx) #1094. The root hk.pkl can list literal directories or globs, and each subproject's own hk.pkl is merged into the root run scoped to its directory. Step working directories and glob matching are relative to the subdirectory, flat step names are prefixed with <dir>: (e.g. packages/web:eslint) for --step/skip_steps, and a subproject's env applies only to its own steps. Paired with this, HK_MISE=1 now resolves mise env --json per step dir, so subproject-local tools land on PATH — including for structured argv commands.

  // hk.pkl (repo root)
  subprojects = List("frontend", "packages/*")
  
  // frontend/hk.pkl
  hooks {
    ["check"] {
      steps { ["eslint"] = (Builtins.eslint) { batch = true } }
    }
  }
  ``` …
  

Two configuration expansions land in this release: shell-free argv commands with per-file argument expansion, and match_any selectors that combine globs and types with OR semantics. Alongside them, correctness fixes for --quiet/--silent, config-based hook argument forwarding, transient index locks, and Linux argument-size limits.

Added

• Structured argv commands (@jdx) #1067. A step's check/fix/check_list_files/check_diff can now be a Command with an explicit argv list that runs a binary via PATH without a shell. Standalone {{files}} and {{workspace_files}} entries expand to one argument per file (raw paths), so names with spaces or shell metacharacters are passed literally. Auto-batching, hk test, progress output, and fix suggestions all go through shared Command rendering, and many builtins (prettier, ruff, biome, ...) have moved to structured commands. Existing string and platform Script commands are unchanged; structured commands can't be combined with shell or prefix.

  check = new Command {
    argv = List("wc", "-c", "{{files}}")
  }
  ``` …
  

A cluster of pre-commit correctness fixes so hk run pre-commit (and installed hooks) really only see staged files, plus a textlint builtin, a content-addressed config cache, and a docs accuracy pass.

Added

• textlint builtin (@smasato) #1036. Adds textlint as a batched natural-language linter for Markdown and plain text. check runs textlint {{ files }}, fix runs textlint --fix {{ files }}, and it auto-suggests when .textlintrc* or a "textlint" entry in package.json is present.

  ["textlint"] = Builtins.textlint
  

Fixed

• Pre-commit is staged-only, even without stashing (@jdx) #1023. The default file selection for pre-commit steps now stays scoped to staged paths when stash = false, matching the "only what you're committing" expectation instead of also picking up unstaged and untracked matches.

• Installed global pre-commit hooks pass --staged (@jdx) #1043. hk install --global now generates pre-commit hook commands as hk run pre-commit --from-hook --staged, so an env override like HK_STASH=git can't defeat a repo-level stash = "none" policy. Local config hooks and legacy .git/hooks/ shims are unchanged. Fixes discussion #1030. …