diff --git a/codegen/src/env_variables.rs b/codegen/src/env_variables.rs
index 173a87a32..a478b7f29 100644
--- a/codegen/src/env_variables.rs
+++ b/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<()> {
diff --git a/src/content/docs/guides/big-projects.mdx b/src/content/docs/guides/big-projects.mdx
index c49b1f0d9..32c0a6f72 100644
--- a/src/content/docs/guides/big-projects.mdx
+++ b/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
diff --git a/src/content/docs/reference/environment-variables.md b/src/content/docs/reference/environment-variables.md
index 9e0b1bc2d..a96a86e40 100644
--- a/src/content/docs/reference/environment-variables.md
+++ b/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
+```
diff --git a/src/content/docs/reference/environment_variables.md b/src/content/docs/reference/environment_variables.md
index 9e0b1bc2d..a96a86e40 100644
--- a/src/content/docs/reference/environment_variables.md
+++ b/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
+```