mise integration

mise manages tools, environments, and tasks. hk selects files and coordinates checks and fixes. Together they let a team share tool versions and run hooks from terminals, editors, and CI.

mise is optional: hk can run any executable available on PATH.

Install tools

From your project directory:

mise use hk
mise use oxfmt

Commit the resulting mise.toml. Other developers can run mise install to install the declared versions.

For tools already managed by a language package manager, keep them there. For example, expose a Node project’s installed executables through mise:

[env]
_.path = ["node_modules/.bin"]

Run the project’s package installation command before invoking hk. See mise tool management for supported backends.

Make tools available to Git

On Git 2.54+, install hk’s hooks once per developer machine with mise integration:

hk install --global --mise

The global launcher is the recommended setup. It uses mise x to prepare each project environment before running hk, and repositories without an hk configuration are skipped. mise must be on PATH during installation; the global launcher records mise’s executable path so Git does not need to find it at hook runtime.

For a repository-scoped setup on any supported Git version, install hooks separately in each repository:

hk install --mise

The local launcher also uses mise x, but it requires Git to find mise on its runtime PATH. Developers do not need an activated shell for either launcher.

Use one installation scope at a time. When moving a repository from a local installation to the recommended global installation, remove the local hooks first:

hk uninstall
hk install --global --mise

Setting HK_MISE=1 makes --mise the default for later hk init and hk install commands. It does not rewrite an already-installed launcher until installation runs again.

Generate a starter setup

hk init --mise creates hk.pkl and, when absent, a mise.toml with hk configured and a pre-commit task.

Run hk init --mise, then install the recommended global launcher on Git 2.54+:

hk init --mise
hk install --global --mise

On older Git, or for a repository-scoped installation, use hk install --mise instead.

Review the generated tools and tasks. Existing mise.toml files are preserved.

Call a mise task from a step

Use a task when a check is also useful outside Git hooks:

amends "package://github.com/jdx/hk/releases/download/v2.7.1/hk@2.7.1#/Config.pkl"

hooks {
  ["check"] {
    steps {
      ["test"] {
        check = "mise run test"
      }
    }
  }
}

A step without a glob runs regardless of file matches. Add a pattern if the task should only run for selected file types.

If a task writes files outside the step’s selected paths, declare suitable dependencies or use exclusive = true to keep it from interfering with other steps.

Share environment variables

Use mise’s [env] section for variables that should apply to project commands:

[env]
NODE_ENV = "development"

Use hk’s global, hook, or step env blocks for variables specific to linter commands. See mise environments and hk configuration.

Run in CI

Once mise is available:

mise install
mise exec -- hk check --all

Install language package dependencies too, if the steps use them. See continuous integration for branch comparisons, profiles, and diagnostics.

Per-directory environments (monorepos)

When HK_MISE=1 is set, hk resolves the mise environment for each step's dir by running mise env in that directory (cached, once per directory per run). Tools and env vars defined by a subdirectory's mise config — such as a mise monorepo config root's mise.toml — are available to steps running in that directory, even when hk is started from the repo root:

hooks {
    ["check"] {
        steps {
            ["oxlint"] = (Builtins.ox_lint) {
                // with HK_MISE=1, tools from subproject/mise.toml are on PATH
                dir = "subproject"
            }
        }
    }
}

Explicit step env values always win over the mise-provided environment.