Add PREK_MAX_CONCURRENCY environment variable

Allow users to cap the maximum number of concurrent hooks via the
PREK_MAX_CONCURRENCY environment variable. The value is clamped
between 1 and the available CPU core count.

This is useful when ulimit -n is low and concurrent hook execution
can exhaust file descriptors. Unlike ulimit, an environment variable
can be set in CI configs, .env files, and wrapper scripts without
requiring shell builtins.

Closes #1696

Assisted by AI

Co-Authored-By: Claude <noreply@anthropic.com>

Author: drichardson

crates/prek-consts/src/env_vars.rs

@@ -22,6 +22,7 @@ impl EnvVars {
     pub const PREK_SKIP: &'static str = "PREK_SKIP";
     pub const PREK_ALLOW_NO_CONFIG: &'static str = "PREK_ALLOW_NO_CONFIG";
     pub const PREK_NO_CONCURRENCY: &'static str = "PREK_NO_CONCURRENCY";
+    pub const PREK_MAX_CONCURRENCY: &'static str = "PREK_MAX_CONCURRENCY";
     pub const PREK_NO_FAST_PATH: &'static str = "PREK_NO_FAST_PATH";
     pub const PREK_UV_SOURCE: &'static str = "PREK_UV_SOURCE";
     pub const PREK_NATIVE_TLS: &'static str = "PREK_NATIVE_TLS";

crates/prek/src/run.rs

@@ -19,14 +19,36 @@ pub(crate) static USE_COLOR: LazyLock<bool> =
         ColorChoice::Auto => unreachable!(),
     });
 
-pub(crate) static CONCURRENCY: LazyLock<usize> = LazyLock::new(|| {
-    if EnvVars::is_set(EnvVars::PREK_NO_CONCURRENCY) {
-        1
-    } else {
-        std::thread::available_parallelism()
-            .map(std::num::NonZero::get)
-            .unwrap_or(1)
+fn resolve_concurrency(no_concurrency: bool, max_concurrency: Option<&str>, cpu: usize) -> usize {
+    if no_concurrency {
+        return 1;
     }
+
+    if let Some(v) = max_concurrency {
+        match v.parse::<usize>() {
+            Ok(cap) => return cap.max(1),
+            Err(_) => {
+                tracing::warn!(
+                    "Invalid value for {}: {v:?}, using default ({cpu})",
+                    EnvVars::PREK_MAX_CONCURRENCY,
+                );
+            }
+        }
+    }
+
+    cpu
+}
+
+pub(crate) static CONCURRENCY: LazyLock<usize> = LazyLock::new(|| {
+    let cpu = std::thread::available_parallelism()
+        .map(std::num::NonZero::get)
+        .unwrap_or(1);
+
+    resolve_concurrency(
+        EnvVars::is_set(EnvVars::PREK_NO_CONCURRENCY),
+        EnvVars::var(EnvVars::PREK_MAX_CONCURRENCY).ok().as_deref(),
+        cpu,
+    )
 });
 
 fn target_concurrency(serial: bool) -> usize {
@@ -352,6 +374,46 @@ mod tests {
         assert_eq!(total_files, 100);
     }
 
+    #[test]
+    fn test_resolve_concurrency_defaults_to_cpu() {
+        assert_eq!(resolve_concurrency(false, None, 16), 16);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_max_caps_value() {
+        assert_eq!(resolve_concurrency(false, Some("4"), 16), 4);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_max_above_cpu() {
+        assert_eq!(resolve_concurrency(false, Some("32"), 8), 32);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_max_zero_floors_to_one() {
+        assert_eq!(resolve_concurrency(false, Some("0"), 16), 1);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_max_invalid_falls_back() {
+        assert_eq!(resolve_concurrency(false, Some("abc"), 16), 16);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_max_empty_falls_back() {
+        assert_eq!(resolve_concurrency(false, Some(""), 16), 16);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_no_concurrency() {
+        assert_eq!(resolve_concurrency(true, None, 16), 1);
+    }
+
+    #[test]
+    fn test_resolve_concurrency_no_concurrency_overrides_max() {
+        assert_eq!(resolve_concurrency(true, Some("8"), 16), 1);
+    }
+
     #[test]
     fn test_partitions_respects_cli_length_limit() {
         // Create files that will exceed CLI length limit

docs/configuration.md

@@ -1332,6 +1332,8 @@ prek supports the following environment variables:
 
 - `PREK_NO_CONCURRENCY` — Disable parallelism for installs and runs (If set, force concurrency to 1).
 
+- `PREK_MAX_CONCURRENCY` — Set the maximum number of concurrent hooks (minimum 1). Defaults to the number of CPU cores when unset. Ignored when `PREK_NO_CONCURRENCY` is set. If you encounter "Too many open files" errors, lowering this value or raising the file descriptor limit with `ulimit -n` can help.
+
 - `PREK_NO_FAST_PATH` — Disable Rust-native built-in hooks; always use the original hook implementation. See [Built-in Fast Hooks](builtin.md) for details.
 
 - `PREK_UV_SOURCE` — Control how uv (Python package installer) is installed. Options: