What Is the DesktopCommanderMCP bootstrap.ts Module and Why It Configures libuv First

The bootstrap.ts module is a mandatory entry-point that sets UV_THREADPOOL_SIZE to 16 before any other imports, preventing filesystem bottlenecks by expanding libuv's default 4-thread pool.

The bootstrap.ts module in DesktopCommanderMCP is a critical initialization script that ensures high-performance file operations across the application. This tiny module configures the libuv thread pool size by setting the UV_THREADPOOL_SIZE environment variable before any filesystem work begins. Understanding this bootstrap mechanism is essential for maintaining responsive I/O when multiple agents perform parallel file operations on slow or cloud-synced filesystems.

Why libuv Thread Pool Size Matters

Node.js delegates all blocking filesystem operations to libuv's internal thread pool. By default, this pool contains only 4 threads, which becomes a severe bottleneck under parallel load.

When many agents perform simultaneous file operations—reading, writing, or editing blocks—these four threads can become blocked for minutes on slow filesystems. Subsequent file calls queue up behind the blocked threads, causing the entire system to slow dramatically. The comments in lines 4-10 of src/bootstrap.ts explicitly document this risk, explaining that the default size is insufficient for heavy parallel I/O workloads.

How bootstrap.ts Works

Located at src/bootstrap.ts, this module assigns process.env.UV_THREADPOOL_SIZE to a safer default of 16 threads unless a user-provided value already exists. Libuv reads this environment variable only once, when the thread pool is first initialized upon the first submitted work item.

Because libuv evaluates UV_THREADPOOL_SIZE at initialization time, the variable must be set before any filesystem API is called. Once the pool initializes, the size is locked for the process lifetime. This architectural constraint makes the import order non-negotiable.

Import Order Requirements

To guarantee the thread pool configuration takes effect, bootstrap.ts must be imported as the very first statement in the application entry point. In src/index.ts, the import appears before any other module loads:

// src/index.ts – the very first line must import bootstrap.ts
import "./bootstrap";   // <-- guarantees thread-pool size is set early
import { startApp } from "./app";

startApp();

If bootstrap.ts were imported after modules that trigger filesystem operations, libuv would initialize with the default 4 threads, rendering the configuration ineffective.

Configuring the Thread Pool

You can override the default 16-thread value by setting UV_THREADPOOL_SIZE before launching the process. The bootstrap.ts module respects existing environment variables, allowing customization based on hardware capabilities or workload intensity.

Set the variable in your shell or .env file:

// Custom thread-pool size via environment variable
// e.g. in a .env file or before launching the process
process.env.UV_THREADPOOL_SIZE = "32";   // will be respected by bootstrap.ts

Verify the effective configuration at runtime:

// Verifying the effective thread-pool size at runtime
console.log("UV_THREADPOOL_SIZE =", process.env.UV_THREADPOOL_SIZE);
// Output: UV_THREADPOOL_SIZE = 16   (or the user-provided value)

Summary

• The bootstrap.ts module prevents I/O starvation by raising libuv's thread pool from 4 to 16 threads.
• It must be imported first in src/index.ts because libuv reads UV_THREADPOOL_SIZE only at pool initialization.
• The module respects user-defined values, defaulting to 16 only when the environment variable is unset.
• This configuration is critical for DesktopCommanderMCP when multiple agents perform parallel filesystem operations on slow or network-backed storage.

Frequently Asked Questions

What happens if I import bootstrap.ts after other modules?

If bootstrap.ts is imported after modules that trigger filesystem operations, libuv initializes its thread pool with the default 4 threads before the environment variable is set. Once initialized, the pool size cannot be changed, and your application will face the original bottleneck risks documented in lines 4-10 of the source file.

Can I change the thread pool size while the application is running?

No. Libuv reads UV_THREADPOOL_SIZE exactly once when the thread pool is first initialized, which occurs on the first filesystem operation. After initialization, the thread count is fixed for the process lifetime. You must set the variable before any I/O operations begin.

Why does DesktopCommanderMCP use 16 threads instead of the default 4?

The default 4 threads suffice for simple scripts but become saturated when multiple AI agents perform parallel reads, writes, and configuration persists—especially on cloud-synced or high-latency filesystems. Sixteen threads provide sufficient concurrency to prevent queue buildup while avoiding excessive memory overhead on typical developer machines.

How do I verify that the custom thread pool size is active?

Check the environment variable after importing bootstrap.ts but before heavy I/O begins. Use console.log(process.env.UV_THREADPOOL_SIZE) or inspect the value in your debugger. If the output shows your custom value (or 16), the bootstrap module executed correctly. If undefined, the import order was likely incorrect.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}