# hk

> Run linters concurrently without letting overlapping fixes race

## Start here

- [Getting started](https://hk.jdx.dev/getting_started.html): Set up hk in an existing Git repository, then use the same linters when you commit, work locally, and run CI.
- [Migrating to hk v2](https://hk.jdx.dev/migration-v2.html): hk v2 removes deprecated configuration entry points and makes shared steps and staging behavior explicit.
- [Why hk?](https://hk.jdx.dev/why-hk.html): hk is designed for projects that run several linters and formatters over overlapping files. It combines concurrent execution with file-level coordination, so tools can work together without writing to…
- [Pkl essentials](https://hk.jdx.dev/pkl_introduction.html): hk uses Pkl for typed configuration. Most projects need only a few features: amend the schema, import builtins, define steps, and reuse them across hooks.

## Guides

- [Git hooks and stashing](https://hk.jdx.dev/hooks.html): A hook is a named collection of steps. Git invokes installed hooks at specific events; hk run invokes them directly. The check and fix hooks are also available through hk check and hk fix.
- [Continuous integration](https://hk.jdx.dev/ci.html): Use hk check --all to run the project’s checks against a checkout. CI must install hk and every tool used by the configured steps, just as a developer’s machine does.
- [mise integration](https://hk.jdx.dev/mise_integration.html): 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.
- [Troubleshooting](https://hk.jdx.dev/logging.html): Start with a plan and verbose output. They usually show whether the problem is file selection, configuration, or a linter command.
- [Coding agents](https://hk.jdx.dev/agents.html): hk gives coding agents a narrow, inspectable way to run project checks and fixes. Agents can use structured CLI output everywhere, or the MCP server for persistent runs, cancellation, paged logs,…
- [Configuration examples](https://hk.jdx.dev/reference/examples/): Choose a starting point, save its downloadable Pkl file as hk.pkl, and adapt the tools and paths to your project. Each page includes the exact file it offers for download.
- [JavaScript and TypeScript](https://hk.jdx.dev/reference/examples/javascript-project.html): Run ESLint before Prettier, and enable TypeScript checking when you need it.
- [Python](https://hk.jdx.dev/reference/examples/python-project.html): Use Ruff for linting and formatting, with mypy behind the types profile.
- [Monorepo](https://hk.jdx.dev/reference/examples/monorepo.html): Organize frontend, backend, and infrastructure checks into groups, then add repository-wide Markdown and YAML checks.
- [Custom steps](https://hk.jdx.dev/reference/examples/custom-linters.html): A step can invoke any shell command. Define which files it uses, how to check them without writes, and how to apply fixes.

## Reference

- [Configuration](https://hk.jdx.dev/configuration.html): hk reads hk.pkl to decide which steps to run and how to run them. Start with a shared set of linters, then add file filters, dependencies, and profiles as your project needs them.
- [Built-in linters](https://hk.jdx.dev/builtins.html): Builtins are reusable Pkl step definitions for linters, formatters, and hk’s own utilities. They supply file patterns, check and fix commands, and optimizations such as diff output.
- [Environment variables](https://hk.jdx.dev/environment_variables.html): Use environment variables for a single invocation or an environment-wide preference. Runtime settings generally override Git and Pkl settings; CLI flags take precedence. See configuration precedence.
- [Glossary](https://hk.jdx.dev/glossary.html): Definitions of hooks, steps, groups, profiles, file locks, stashing, and workspaces in hk.
- [CLI commands](https://hk.jdx.dev/cli/): Run the same configured steps locally, in Git hooks, and in CI.
- [agent](https://hk.jdx.dev/cli/agent.html): Generate integration snippets for coding agents
- [agent hooks](https://hk.jdx.dev/cli/agent/hooks.html): Print a hook configuration for an agent or editor
- [agent instructions](https://hk.jdx.dev/cli/agent/instructions.html): Print project instructions for a coding agent
- [agent mcp](https://hk.jdx.dev/cli/agent/mcp.html): Print an MCP server configuration
- [builtins](https://hk.jdx.dev/cli/builtins.html): List all available builtin linters
- [cache clear](https://hk.jdx.dev/cli/cache/clear.html): Clear the cache directory
- [check](https://hk.jdx.dev/cli/check.html): Run the check hook
- [completion](https://hk.jdx.dev/cli/completion.html): Generate shell completion scripts
- [config](https://hk.jdx.dev/cli/config.html): Inspect hk's configuration
- [config dump](https://hk.jdx.dev/cli/config/dump.html): Print the effective runtime settings
- [config explain](https://hk.jdx.dev/cli/config/explain.html): Explain where a configuration value comes from
- [config get](https://hk.jdx.dev/cli/config/get.html): Get a specific configuration value
- [config sources](https://hk.jdx.dev/cli/config/sources.html): Show the configuration source precedence order
- [fix](https://hk.jdx.dev/cli/fix.html): Run the fix hook
- [init](https://hk.jdx.dev/cli/init.html): Generate a new hk.pkl file for a project
- [install](https://hk.jdx.dev/cli/install.html): Set up git hooks to run hk.
- [mcp](https://hk.jdx.dev/cli/mcp.html): Run an MCP server for coding agents over standard input/output
- [migrate](https://hk.jdx.dev/cli/migrate.html): Migrate from other hook managers to hk
- [migrate pre-commit](https://hk.jdx.dev/cli/migrate/pre-commit.html): Migrate from pre-commit (or prek) to hk
- [run](https://hk.jdx.dev/cli/run.html): Run a hook
- [run commit-msg](https://hk.jdx.dev/cli/run/commit-msg.html): Run the commit-msg hook
- [run post-checkout](https://hk.jdx.dev/cli/run/post-checkout.html): Run the post-checkout hook
- [run post-commit](https://hk.jdx.dev/cli/run/post-commit.html): Run the post-commit hook
- [run post-merge](https://hk.jdx.dev/cli/run/post-merge.html): Run the post-merge hook
- [run post-rewrite](https://hk.jdx.dev/cli/run/post-rewrite.html): Run the post-rewrite hook
- [run pre-commit](https://hk.jdx.dev/cli/run/pre-commit.html): Run the pre-commit hook
- [run pre-push](https://hk.jdx.dev/cli/run/pre-push.html): Run the pre-push hook
- [run pre-rebase](https://hk.jdx.dev/cli/run/pre-rebase.html): Run the pre-rebase hook
- [run prepare-commit-msg](https://hk.jdx.dev/cli/run/prepare-commit-msg.html): Run the prepare-commit-msg hook
- [sponsors](https://hk.jdx.dev/cli/sponsors.html): Show the companies sponsoring hk and the jdx.dev open source tools
- [test](https://hk.jdx.dev/cli/test.html): Run step-defined tests
- [uninstall](https://hk.jdx.dev/cli/uninstall.html): Remove hk hooks
- [util](https://hk.jdx.dev/cli/util.html): Utility commands for file operations
- [util check-added-large-files](https://hk.jdx.dev/cli/util/check-added-large-files.html): Check for large files being added to the repository
- [util check-byte-order-marker](https://hk.jdx.dev/cli/util/check-byte-order-marker.html): Check for UTF-8 byte order marker (BOM)
- [util check-case-conflict](https://hk.jdx.dev/cli/util/check-case-conflict.html): Check for case-insensitive filename conflicts
- [util check-conventional-commit](https://hk.jdx.dev/cli/util/check-conventional-commit.html): Check that a commit message follows the Conventional Commits format
- [util check-executables-have-shebangs](https://hk.jdx.dev/cli/util/check-executables-have-shebangs.html): Check that executable files have shebangs
- [util check-merge-conflict](https://hk.jdx.dev/cli/util/check-merge-conflict.html): Check for merge conflict markers
- [util check-shebang-scripts-are-executable](https://hk.jdx.dev/cli/util/check-shebang-scripts-are-executable.html): Check that files with shebangs are executable
- [util check-symlinks](https://hk.jdx.dev/cli/util/check-symlinks.html): Check for broken symlinks
- [util destroyed-symlinks](https://hk.jdx.dev/cli/util/destroyed-symlinks.html): Check for symlinks replaced by regular files containing their target path
- [util detect-private-key](https://hk.jdx.dev/cli/util/detect-private-key.html): Detect private keys in files
- [util end-of-file-fixer](https://hk.jdx.dev/cli/util/end-of-file-fixer.html): Check for and optionally fix missing final newlines
- [util fix-byte-order-marker](https://hk.jdx.dev/cli/util/fix-byte-order-marker.html): Remove UTF-8 byte order marker (BOM)
- [util fix-smart-quotes](https://hk.jdx.dev/cli/util/fix-smart-quotes.html): Replace smart quotes with plain ASCII quotes
- [util forbid-submodules](https://hk.jdx.dev/cli/util/forbid-submodules.html): Check that the repository contains no git submodules
- [util format-diff](https://hk.jdx.dev/cli/util/format-diff.html): Print a patch of what a formatter would change, for a check_diff command
- [util mixed-line-ending](https://hk.jdx.dev/cli/util/mixed-line-ending.html): Detect and fix mixed line endings
- [util no-commit-to-branch](https://hk.jdx.dev/cli/util/no-commit-to-branch.html): Prevent commits to specific branches
- [util python-check-ast](https://hk.jdx.dev/cli/util/python-check-ast.html): Check Python files for valid syntax
- [util python-debug-statements](https://hk.jdx.dev/cli/util/python-debug-statements.html): Detect Python debug statements
- [util sarif-diff](https://hk.jdx.dev/cli/util/sarif-diff.html): Print a patch from the fixes in a tool's SARIF report, for a check_diff command
- [util trailing-whitespace](https://hk.jdx.dev/cli/util/trailing-whitespace.html): Check for and optionally fix trailing whitespace
- [validate](https://hk.jdx.dev/cli/validate.html): Validate the config file
- [version](https://hk.jdx.dev/cli/version.html): Print the version of hk

## Project

- [Benchmarks](https://hk.jdx.dev/benchmarks.html): This benchmark compares hk, lefthook, pre-commit, and prek on everyday tasks: fixing files, checking a repository, and running pre-commit hooks on a large and a small commit.
- [About hk](https://hk.jdx.dev/about.html): hk is a Git hook manager and project linting tool built by @jdx. It is written in Rust and released under the MIT license.
- [Contributing](https://hk.jdx.dev/contributing.html): Bug fixes, documentation improvements, and builtin definitions are welcome. For a substantial feature or behavior change, discuss the direction before investing in implementation.
- [Sea shanty](https://hk.jdx.dev/shanty.html): A sea shanty celebrating the hk git hook manager
