# How to Override Default Worker Count for Indexing with CBM_WORKERS

> Override default worker count for indexing with CBM_WORKERS by setting the environment variable. Manually control parallel workers instead of auto-detected CPU count.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-12

---

**Set the `CBM_WORKERS` environment variable to an integer value before launching the indexer to manually control parallel worker allocation instead of using the auto-detected CPU count.**

The `codebase-memory-mcp` repository indexing system automatically scales worker processes based on the host machine's CPU core count. When you need to override default worker count for indexing with CBM_WORKERS, you gain explicit control over resource consumption, allowing you to limit CPU usage on shared machines or maximize throughput on dedicated CI runners.

## How CBM_WORKERS Overrides Auto-Detection

By default, `codebase-memory-mcp` queries the host system to determine the number of available CPU cores and spawns a corresponding worker pool for repository indexing. This auto-detection logic executes during initialization in [`pkg/go/cmd/codebase-memory-mcp/main.go`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/go/cmd/codebase-memory-mcp/main.go), where the environment configuration is loaded.

When you define **`CBM_WORKERS`**, the startup sequence reads this variable and uses the specified integer value, completely bypassing the CPU detection heuristics. The resolved worker count is then passed to the internal indexing implementation, which spawns exactly that number of goroutines or threads for parallel processing.

**Key characteristics:**

- **Precedence**: Environment variable overrides any internal auto-detection
- **Scope**: Applies to all indexing operations within the same process lifetime
- **Format**: Must be a valid integer (e.g., `4`, `8`, `16`)

## Configuring CBM_WORKERS Across Operating Systems

You can set the `CBM_WORKERS` variable temporarily for a single session or persist it across environment configurations.

### Unix and macOS (Bash/Zsh)

For the current shell session, export the variable before invoking the command:

```bash
export CBM_WORKERS=6
codebase-memory-mcp index /path/to/repo

```

To apply the setting to a single command without persisting it in the session:

```bash
CBM_WORKERS=4 codebase-memory-mcp index /path/to/repo

```

### Windows (PowerShell)

In PowerShell, use the `$env:` syntax to set the variable for the current session:

```powershell
$env:CBM_WORKERS = "4"
codebase-memory-mcp.exe index C:\path\to\repo

```

Or for a single invocation:

```powershell
$env:CBM_WORKERS="8"; codebase-memory-mcp.exe index C:\path\to\repo

```

### Persistent Configuration with .env Files

For CI pipelines or containerized deployments, store the configuration in a `.env` file:

```text
CBM_WORKERS=8

```

Source this file before running the indexer, or ensure your container orchestration platform injects the variable when launching the process from [`pkg/go/cmd/codebase-memory-mcp/main.go`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/go/cmd/codebase-memory-mcp/main.go).

## Selecting Optimal Worker Count Values

The appropriate value for `CBM_WORKERS` depends on your execution environment and resource constraints:

- **Low-resource environments**: Set `1` or `2` workers to prevent CPU saturation on shared development machines or laptops
- **Typical development**: Use `4` to `8` workers for standard desktop workstations with 4-8 physical cores
- **High-throughput CI**: Configure `16` or more workers for dedicated CI runners with substantial CPU allocation

According to the source code in [`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md), these values directly determine the size of the worker pool allocated during the indexing phase, affecting both memory consumption and I/O parallelism.

## Implementation Details

The override mechanism is implemented in two key locations within the repository:

**[`docs/CONFIGURATION.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docs/CONFIGURATION.md)** documents the variable's behavior, specifying that `CBM_WORKERS` accepts integer values and takes precedence over automatic core detection.

**[`pkg/go/cmd/codebase-memory-mcp/main.go`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/go/cmd/codebase-memory-mcp/main.go)** serves as the entry point where the environment variable is parsed and applied to the indexing subsystem. This file initializes the worker pool that executes the actual repository scanning and memory mapping operations.

The internal indexing implementation consumes this resolved count to spawn the appropriate number of parallel execution units, ensuring the constraint is respected throughout the indexing lifecycle.

## Summary

- **`CBM_WORKERS`** overrides the automatic CPU core detection in `codebase-memory-mcp`
- Set the variable to an integer value before launch to control indexing parallelism
- **Unix/macOS**: Use `export CBM_WORKERS=N`; **Windows**: Use `$env:CBM_WORKERS="N"`
- Typical values range from `1-2` (constrained environments) to `16+` (high-performance CI)
- The setting is processed in [`pkg/go/cmd/codebase-memory-mcp/main.go`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/go/cmd/codebase-memory-mcp/main.go) and affects all subsequent indexing operations

## Frequently Asked Questions

### What is the default behavior when CBM_WORKERS is not set?

When `CBM_WORKERS` is undefined, the system queries the host's CPU core count and spawns a worker pool of corresponding size. This auto-detection ensures out-of-the-box performance optimization without manual configuration.

### Does CBM_WORKERS affect repository querying or only indexing?

The variable specifically controls the **indexing** worker pool—the parallel processes that scan and map repository files into memory. Query operations typically use separate concurrency controls and are not affected by this setting.

### How do I configure CBM_WORKERS in a Docker container?

Pass the environment variable using the `-e` flag when running the container: `docker run -e CBM_WORKERS=4 deusdata/codebase-memory-mcp`. Alternatively, include it in your [`docker-compose.yml`](https://github.com/DeusData/codebase-memory-mcp/blob/main/docker-compose.yml) environment section or Kubernetes pod specification to ensure it is available when the entry point in [`pkg/go/cmd/codebase-memory-mcp/main.go`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/go/cmd/codebase-memory-mcp/main.go) executes.

### What happens if I set CBM_WORKERS to an invalid value?

If `CBM_WORKERS` is set to a non-integer or negative value, the startup sequence in [`pkg/go/cmd/codebase-memory-mcp/main.go`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/go/cmd/codebase-memory-mcp/main.go) may fail to parse the environment variable, potentially falling back to the default auto-detection behavior or exiting with a configuration error depending on the specific error handling implemented in that version.