How mksglu/context-mode Handles Bun Runtime Detection for Faster JavaScript Execution

context-mode detects the Bun JavaScript runtime by checking command availability and fallback installation paths in src/runtime.ts, then automatically prefers it over Node.js for 3–5× faster script execution.

The mksglu/context-mode repository implements a robust Bun runtime detection system that locates the Bun binary across different installation scenarios. This detection logic lives entirely within src/runtime.ts and enables automatic performance optimization for JavaScript and TypeScript execution without requiring manual configuration.

The Three-Step Detection Logic in src/runtime.ts

The detection mechanism follows a hierarchical approach to locate the Bun executable reliably across Windows, macOS, and Linux environments.

Step 1: Verify bun Command Availability

The bunExists() function first attempts to locate Bun through the system PATH. It invokes commandExists("bun"), which internally runs where bun on Windows or command -v bun on POSIX systems to verify the binary is accessible.

Source: Lines 40–44 and the wrapper implementation at lines 50–57 in src/runtime.ts.

Step 2: Check Default Installation Path

When the bun command is not found on PATH, the system falls back to the standard Bun installation directory. The code specifically checks for the binary at $HOME/.bun/bin/bun, which accommodates MCP server environments where Bun is installed but not exported to the shell environment.

Source: Lines 54–56 in src/runtime.ts.

Step 3: Resolve the Executable Path

The bunCommand() function returns the appropriate executable string based on the previous detection steps. If Bun was found on PATH, it returns "bun"; otherwise, it returns the absolute fallback path to the binary.

Source: Lines 60–64 in src/runtime.ts.

Integrating Bun into the Runtime Map

The detectRuntimes() function assembles a runtime map that prioritizes Bun for JavaScript execution. When Bun is detected, the map uses it as the JavaScript runtime; otherwise, it falls back to process.execPath (Node.js).

// src/runtime.ts
export function detectRuntimes(): RuntimeMap {
  const hasBun = bunExists();               // ← detection check
  const bun = hasBun ? bunCommand() : null; // ← executable path
  return {
    javascript: bun ?? process.execPath,    // Prefer Bun, fallback to Node
    // …other languages omitted
  };
}

Source: Lines 12–18 in src/runtime.ts.

Building Execution Commands with Bun Support

When constructing the final execution command via buildCommand(), the system detects whether the selected runtime is Bun by checking if the path ends with "bun". If so, it automatically injects the run subcommand to ensure proper script execution using Bun's fast runner.

// Usage example
import { detectRuntimes, buildCommand } from "./runtime";

const runtimes = detectRuntimes();
const cmd = buildCommand(runtimes, "javascript", "script.js");

// With Bun present: ["bun", "run", "script.js"]
// Without Bun: ["/usr/local/bin/node", "script.js"]

Source: Lines 36–41 in src/runtime.ts.

Utility Functions for Runtime Checking

Checking Availability with hasBunRuntime()

The hasBunRuntime() function provides a simple boolean interface exposing the detection result to other application components. This utility enables UI hints and conditional logic elsewhere in the codebase, such as displaying "install Bun for faster execution" tips in the CLI interface.

import { hasBunRuntime } from "./runtime";

if (hasBunRuntime()) {
  console.log("🚀 Bun is available – will use it for JS/TS.");
}

Source: Lines 47–49 in src/runtime.ts.

Performance Benefits of Bun Detection

By implementing cross-platform Bun runtime detection, context-mode delivers significant performance improvements:

• Execution speed: Bun runs JavaScript 3–5× faster than Node.js according to the source code implementation
• Zero configuration: Automatic detection requires no manual PATH modifications or config files
• Fallback safety: Seamless degradation to Node.js when Bun is unavailable ensures reliability

Summary

• Bun detection occurs in src/runtime.ts through the bunExists() and bunCommand() functions
• The system checks PATH first, then falls back to $HOME/.bun/bin/bun for standard installations
• detectRuntimes() returns a runtime map that prefers Bun over Node.js when available
• buildCommand() automatically appends the run subcommand for Bun executions
• hasBunRuntime() exposes detection results for UI hints and conditional logic
• The implementation supports Windows (where) and POSIX (command -v) systems equally

Frequently Asked Questions

How does context-mode detect Bun if it's not in PATH?

The detection system implements a fallback mechanism that checks for the binary at $HOME/.bun/bin/bun when the bun command is not found on the system PATH. This handles scenarios where Bun is installed but the shell environment hasn't been reloaded or properly configured.

What happens if Bun is installed but not detected?

If both the PATH check and the fallback path check fail, detectRuntimes() returns process.execPath (Node.js) as the JavaScript runtime. The application continues functioning normally using Node.js, ensuring execution reliability even without Bun present.

Does context-mode automatically use Bun for TypeScript files?

Yes, the runtime detection applies to both JavaScript and TypeScript execution. Since Bun natively supports TypeScript without additional transpilation steps, the buildCommand() logic uses the same Bun detection for .ts files, offering the same 3–5× performance improvement over Node.js with ts-node.

How much faster is Bun compared to Node.js in context-mode?

According to the source code comments and implementation, Bun provides 3–5× faster execution compared to Node.js for JavaScript and TypeScript scripts. This performance gain is realized automatically whenever hasBunRuntime() returns true and the system uses bun run instead of node for script execution.

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