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,35 @@ pub(crate) static USE_COLOR: LazyLock<bool> =
         ColorChoice::Auto => unreachable!(),
     });
 
+fn resolve_max_concurrency(cpu: usize, max_concurrency: Option<&str>) -> usize {
+    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(|| {
     if EnvVars::is_set(EnvVars::PREK_NO_CONCURRENCY) {
-        1
-    } else {
-        std::thread::available_parallelism()
-            .map(std::num::NonZero::get)
-            .unwrap_or(1)
+        return 1;
     }
+
+    let cpu = std::thread::available_parallelism()
+        .map(std::num::NonZero::get)
+        .unwrap_or(1);
+
+    resolve_max_concurrency(
+        cpu,
+        EnvVars::var(EnvVars::PREK_MAX_CONCURRENCY).ok().as_deref(),
+    )
 });
 
 fn target_concurrency(serial: bool) -> usize {
@@ -352,6 +373,36 @@ mod tests {
         assert_eq!(total_files, 100);
     }
 
+    #[test]
+    fn test_resolve_max_concurrency_none() {
+        assert_eq!(resolve_max_concurrency(16, None), 16);
+    }
+
+    #[test]
+    fn test_resolve_max_concurrency_valid() {
+        assert_eq!(resolve_max_concurrency(16, Some("4")), 4);
+    }
+
+    #[test]
+    fn test_resolve_max_concurrency_above_cpu() {
+        assert_eq!(resolve_max_concurrency(8, Some("32")), 32);
+    }
+
+    #[test]
+    fn test_resolve_max_concurrency_zero_floors_to_one() {
+        assert_eq!(resolve_max_concurrency(16, Some("0")), 1);
+    }
+
+    #[test]
+    fn test_resolve_max_concurrency_invalid_falls_back() {
+        assert_eq!(resolve_max_concurrency(16, Some("abc")), 16);
+    }
+
+    #[test]
+    fn test_resolve_max_concurrency_empty_falls_back() {
+        assert_eq!(resolve_max_concurrency(16, Some("")), 16);
+    }
+
     #[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: