docs: add RAYON_NUM_THREADS environment variable documentation

codegen/src/env_variables.rs

@@ -20,6 +20,23 @@ If you don't define this variable, Biome will automatically detect the correct b
 ```
 # Nix derivation example; the binary path comes from "${pkgs.biome}/bin/biome"
 BIOME_BINARY=/nix/store/68fyfw1hidsqkal1839whi3nzgvqv4pa-biome-1.0.0/bin/biome npx @biomejs/biome format .
+```
+
+### `RAYON_NUM_THREADS`
+
+Controls the number of threads used by Biome's internal thread pool (via the Rayon library). This environment variable applies to **all** Biome commands, not just the `ci` command.
+
+Useful for:
+- Limiting CPU usage in resource-constrained environments
+- Running multiple Biome instances in parallel (e.g., in monorepos or agentic workflows)
+- Preventing resource contention when multiple agents/processes run Biome simultaneously
+
+```bash
+# Limit Biome to use only 1 thread
+RAYON_NUM_THREADS=1 biome lint .
+
+# Set globally for all Biome commands
+export RAYON_NUM_THREADS=2
 ```"#;
 
 pub fn generate_env_variables() -> Result<()> {

src/content/docs/guides/big-projects.mdx

@@ -148,6 +148,22 @@ case, we suggest ignoring the nested project entirely using
 [the `files.includes` field](/reference/configuration/#filesincludes).
 :::
 
+:::caution[Agentic Workflows and Parallel Processes]
+When running multiple Biome processes in parallel (e.g., in CI/CD pipelines or agentic workflows), you may experience high CPU usage and resource contention. Each Biome instance can use 60-80% CPU, which can slow down overall execution when many agents run simultaneously.
+
+To limit the number of threads Biome uses across all commands, set the `RAYON_NUM_THREADS` environment variable:
+
+```bash
+# Limit Biome to use only 1 thread per instance
+RAYON_NUM_THREADS=1 biome lint .
+
+# Or set it globally for all Biome commands in your environment
+export RAYON_NUM_THREADS=1
+```
+
+This approach is more convenient than using the `--threads` flag (which is only available for the `ci` command) because it applies to all Biome commands automatically without modifying individual command invocations.
+:::
+
 ## Other ways to share a configuration file
 
 As we saw above, the `extends` field allows you to split your configuration

src/content/docs/reference/environment-variables.md

@@ -27,3 +27,20 @@ If you don't define this variable, Biome will automatically detect the correct b
 # Nix derivation example; the binary path comes from "${pkgs.biome}/bin/biome"
 BIOME_BINARY=/nix/store/68fyfw1hidsqkal1839whi3nzgvqv4pa-biome-1.0.0/bin/biome npx @biomejs/biome format .
 ```
+
+### `RAYON_NUM_THREADS`
+
+Controls the number of threads used by Biome's internal thread pool (via the Rayon library). This environment variable applies to **all** Biome commands, not just the `ci` command.
+
+Useful for:
+- Limiting CPU usage in resource-constrained environments
+- Running multiple Biome processes in parallel (e.g., in monorepos or agentic workflows)
+- Preventing resource contention when multiple agents/processes run Biome simultaneously
+
+```bash
+# Limit Biome to use only 1 thread
+RAYON_NUM_THREADS=1 biome lint .
+
+# Set globally for all Biome commands
+export RAYON_NUM_THREADS=2
+```

src/content/docs/reference/environment_variables.md

@@ -27,3 +27,20 @@ If you don't define this variable, Biome will automatically detect the correct b
 # Nix derivation example; the binary path comes from "${pkgs.biome}/bin/biome"
 BIOME_BINARY=/nix/store/68fyfw1hidsqkal1839whi3nzgvqv4pa-biome-1.0.0/bin/biome npx @biomejs/biome format .
 ```
+
+### `RAYON_NUM_THREADS`
+
+Controls the number of threads used by Biome's internal thread pool (via the Rayon library). This environment variable applies to **all** Biome commands, not just the `ci` command.
+
+Useful for:
+- Limiting CPU usage in resource-constrained environments
+- Running multiple Biome processes in parallel (e.g., in monorepos or agentic workflows)
+- Preventing resource contention when multiple agents/processes run Biome simultaneously
+
+```bash
+# Limit Biome to use only 1 thread
+RAYON_NUM_THREADS=1 biome lint .
+
+# Set globally for all Biome commands
+export RAYON_NUM_THREADS=2
+```