paulnsorensen/prek

prek

Onboard and configure prek — a fast, Rust-powered pre-commit hook manager.

When to use

• Project has no prek.toml and would benefit from pre-commit hooks
• User wants to add/audit/extend hooks in an existing prek.toml
• User is migrating from .pre-commit-config.yaml to prek's native TOML format

Protocol

1. Detect project type

Scan the repo root for language markers:

| Marker file | Language/Framework | |---|---| | Cargo.toml | Rust | | pyproject.toml, setup.py, requirements.txt | Python | | package.json | TypeScript/JavaScript | | go.mod | Go | | Gemfile | Ruby | | *.sh, zsh/, bin/ | Shell | | Dockerfile | Docker |

Multiple markers = polyglot project. Suggest hooks for all detected languages.

2. Check existing config

• If prek.toml exists, read it and identify what's already configured
• If .pre-commit-config.yaml exists, offer to migrate (prek reads YAML natively, but TOML is the native format with more features like glob patterns)

3. Suggest hooks

Present hooks in categories. Show what each hook does before adding. Use this reference:

Built-in hooks (repo = "builtin")

Fast, offline, zero-setup. Always suggest these as the foundation:

| Hook ID | What it does | |---|---| | trailing-whitespace | Trims trailing whitespace. Args: --markdown-linebreak-ext=md | | end-of-file-fixer | Ensures files end with a newline | | check-yaml | Validates YAML syntax. Args: --allow-multiple-documents | | check-toml | Validates TOML syntax | | check-json | Validates JSON syntax (rejects duplicate keys) | | check-json5 | Validates JSON5 syntax | | check-xml | Validates XML syntax | | check-merge-conflict | Detects unresolved merge conflict markers | | detect-private-key | Catches accidentally committed private keys | | check-added-large-files | Blocks large files. Args: --maxkb=1024 | | check-case-conflict | Detects filenames that differ only by case | | check-symlinks | Validates symlinks point to existing targets | | check-executables-have-shebangs | Ensures executable scripts have shebangs | | mixed-line-ending | Detects mixed line endings (LF vs CRLF) | | fix-byte-order-marker | Removes UTF-8 BOM | | no-commit-to-branch | Blocks direct commits to protected branches |

Language-specific hooks (community repos)

Rust:

# Local hooks (no external repo needed)
[[repos]]
repo = "local"

[[repos.hooks]]
id = "cargo-fmt"
name = "cargo fmt"
language = "system"
entry = "cargo fmt --"
files = "\\.rs$"
pass_filenames = true

[[repos.hooks]]
id = "cargo-clippy"
name = "cargo clippy"
language = "system"
entry = "cargo clippy --all-targets --all-features -- -D warnings"
files = "\\.rs$"
pass_filenames = false
always_run = true

Python:

# Ruff (linter + formatter)
[[repos]]
repo = "https://github.com/astral-sh/ruff-pre-commit"
rev = "v0.11.6"
hooks = [
  { id = "ruff", args = ["--fix"] },
  { id = "ruff-format" },
]

TypeScript/JavaScript:

[[repos]]
repo = "local"

[[repos.hooks]]
id = "eslint"
name = "eslint"
language = "system"
entry = "npx eslint --fix"
files = "\\.(ts|tsx|js|jsx)$"
pass_filenames = true

[[repos.hooks]]
id = "prettier"
name = "prettier"
language = "system"
entry = "npx prettier --write"
files = "\\.(ts|tsx|js|jsx|json|css|md)$"
pass_filenames = true

Go:

[[repos]]
repo = "local"

[[repos.hooks]]
id = "go-fmt"
name = "go fmt"
language = "system"
entry = "gofmt -w"
files = "\\.go$"
pass_filenames = true

[[repos.hooks]]
id = "go-vet"
name = "go vet"
language = "system"
entry = "go vet ./..."
pass_filenames = false
always_run = true

Shell:

[[repos]]
repo = "https://github.com/shellcheck-py/shellcheck-py"
rev = "a23f6b85d0fdd5bb9d564e2579e678033debbdff"
hooks = [
  { id = "shellcheck" },
]

4. Fetch latest versions

Before writing config, use Context7 MCP to check for current recommended versions of community hook repos (ruff-pre-commit, shellcheck-py, etc.). Fall back to the versions listed above if Context7 is unavailable.

5. Generate or augment prek.toml

New project: Generate a complete prek.toml with:

1. Built-in hooks (always include: trailing-whitespace, end-of-file-fixer, check-merge-conflict, detect-private-key, check-added-large-files)
2. Language-specific hooks based on detection
3. Comments explaining each section

Existing project: Show a diff of what would be added. Don't duplicate hooks already present.

6. Install and verify

After writing config:

prek install
prek run --all-files

If prek isn't installed, tell the user to install it (cargo install prek or brew install prek) and add it to their packages.yaml if one exists.

Advanced options

Stage-specific hooks

Slow checks (tests, full builds) belong on pre-push, not pre-commit:

[[repos.hooks]]
id = "pytest"
name = "Run tests"
language = "system"
entry = "pytest -x"
pass_filenames = false
always_run = true
stages = ["pre-push"]
priority = 100

Global filters

Exclude vendored/generated code from all hooks:

exclude = "^(vendor/|generated/|node_modules/)"

Glob patterns (prek-only)

Prek supports glob patterns as an alternative to regex (not compatible with upstream pre-commit):

files = { glob = "src/**/*.py" }
exclude = { glob = ["vendor/**", "dist/**"] }

Migration from pre-commit

If .pre-commit-config.yaml exists:

1. prek reads YAML natively — the existing config works as-is
2. Offer to convert to prek.toml for access to prek-only features (glob patterns, repo: builtin)
3. Replace repo: https://github.com/pre-commit/pre-commit-hooks with repo: builtin where hooks are supported

What You Don't Do

• Configure CI pipelines, GitHub Actions, or other CI hook systems
• Manage husky, lint-staged, or pre-commit (Python) configs
• Remove existing hooks without user confirmation
• Modify .pre-commit-config.yaml directly — only generates prek.toml

Gotchas

• Context7 may be unavailable — fall back to training data for hook recommendations
• prek run --all-files can fail on first run if auto-fix hooks reformat everything
• Rev pinning in prek.toml goes stale — recommend periodic updates
• prek install needs write access to .git/hooks/ — fails in worktrees with shared hooks