chore: make GIT_SUBPROCESS_PARALLELISM configurable with smart clamping

Enhances GIT_SUBPROCESS_PARALLELISM to be configurable via env var with
auto-clamping to [1, 2×CPU_COUNT] to prevent runaway process spawning.
Defaults to 4 for backward compatibility. Improves fleet-scale agent
workflows on high-core machines while protecting against misconfiguration.

Updated documentation in docs/install.md to explain the env var, default,
and the auto-clamping safety mechanism.

Fixes #2

Author: AlbinoGeek

docs/install.md

@@ -91,16 +91,18 @@ Omit any `cwd` / `workingDirectory` field unless your client requires it for unr
 
 | Variable | Default | Purpose |
 |----------|---------|---------|
-| `GIT_SUBPROCESS_PARALLELISM` | `4` | Number of parallel git subprocesses for inventory operations and `git_status` submodule rows. Increase on high-core machines or for slow network connections; decrease if system resources are constrained. |
+| `GIT_SUBPROCESS_PARALLELISM` | `4` | Number of parallel git subprocesses for inventory operations and `git_status` submodule rows. Valid range: 1 to 2×CPU count (auto-clamped to prevent runaway spawning). Increase on high-core machines to accelerate large fleet scans; decrease if system resources are constrained. |
 
 Set these in the environment where the MCP client launches the server (e.g. in your shell, in the MCP client config as `env`, or in a startup script).
 
-Example: Running the server with 8 parallel git processes:
+Example: Running the server with 8 parallel git processes on a 4-core machine:
 
 ```bash
 GIT_SUBPROCESS_PARALLELISM=8 npx -y @rethunk/mcp-multi-root-git
 ```
 
+On a 4-core machine (CPU count = 4), the max parallelism is clamped to 8 (2×4). The value requested is used if valid.
+
 ## Cursor
 
 **User scope (all workspaces):** `~/.cursor/mcp.json` on macOS/Linux, or `%USERPROFILE%\.cursor\mcp.json` on Windows.

src/server/git.ts

@@ -1,12 +1,26 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
+import { cpus } from "node:os";
 import { join } from "node:path";
 
-/** Parallel git subprocesses for inventory rows and git_status submodule rows. */
-export const GIT_SUBPROCESS_PARALLELISM = parseInt(
-  process.env.GIT_SUBPROCESS_PARALLELISM ?? "4",
-  10,
-);
+/**
+ * Parallel git subprocesses for inventory rows and git_status submodule rows.
+ * Reads from GIT_SUBPROCESS_PARALLELISM env var (default 4), clamped to [1, 2×CPU_COUNT].
+ */
+function resolveGitSubprocessParallelism(): number {
+  const env = process.env.GIT_SUBPROCESS_PARALLELISM;
+  if (env) {
+    const n = Number.parseInt(env, 10);
+    if (!Number.isNaN(n) && n >= 1) {
+      const cpuCount = cpus().length;
+      const maxParallel = cpuCount * 2;
+      return Math.min(n, maxParallel);
+    }
+  }
+  return 4;
+}
+
+export const GIT_SUBPROCESS_PARALLELISM = resolveGitSubprocessParallelism();
 
 // ---------------------------------------------------------------------------
 // Git on PATH (lazy probe)