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

> Discover how context-mode detects Bun for 3-5x faster JavaScript execution by checking availability and fallback paths. Automatically prefers Bun over Node.js.

- Repository: [Mert Köseoğlu/context-mode](https://github.com/mksglu/context-mode)
- Tags: how-to-guide
- Published: 2026-04-24

---

**`context-mode` detects the Bun JavaScript runtime by checking command availability and fallback installation paths in [`src/runtime.ts`](https://github.com/mksglu/context-mode/blob/main/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`](https://github.com/mksglu/context-mode/blob/main/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`](https://github.com/mksglu/context-mode/blob/main/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`](https://github.com/mksglu/context-mode/blob/main/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`](https://github.com/mksglu/context-mode/blob/main/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).

```typescript
// 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`](https://github.com/mksglu/context-mode/blob/main/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.

```typescript
// 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`](https://github.com/mksglu/context-mode/blob/main/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.

```typescript
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`](https://github.com/mksglu/context-mode/blob/main/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`](https://github.com/mksglu/context-mode/blob/main/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.