# How to Use VS Code-Ripgrep Based Code and Text Search in Desktop Commander MCP

> Master vscode-ripgrep code search in Desktop Commander MCP. Quickly find files & text across folders using the powerful start_search tool. Optimize your workflow today.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-07-28

---

**Desktop Commander MCP provides a high-performance search engine powered by `@vscode/ripgrep` that enables fast file and content searches across folders through the `start_search` tool, with results streamed as JSON and paginated via `get_more_search_results`.**

Desktop Commander MCP ships with a built-in search infrastructure that leverages the `@vscode/ripgrep` package for blazing-fast codebase exploration. The system wraps the ripgrep binary in an ESM-compatible shim and exposes search functionality through MCP tools like `start_search` and `get_more_search_results`. This guide explains how to invoke searches, manage sessions, and configure advanced matching options using the actual source implementation from the `wonderwhy-er/DesktopCommanderMCP` repository.

## Search Architecture and Binary Resolution

The search system relies on a robust binary resolution chain to ensure ripgrep executes correctly across platforms.

### Ripgrep Wrapper and Resolver

The entry point for binary resolution is `getRipgrepPath()` in [[`src/utils/ripgrep-resolver.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/ripgrep-resolver.ts)](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/ripgrep-resolver.ts). This function attempts three strategies in order:

1. Import `@vscode/ripgrep` and use the bundled binary (`rg-<target>`)
2. Use `which` or `where` to locate a system `rg` installation
3. Scan common install locations (Homebrew, Chocolatey, Cargo)

If all strategies fail, the function throws an informative error (lines 75-82). The [[`scripts/ripgrep-wrapper.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/ripgrep-wrapper.js)](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/ripgrep-wrapper.js) provides an alternative ESM-compatible shim that selects the correct binary for the current platform and guarantees executable permissions.

### Session Lifecycle Management

When a client invokes the **`start_search`** tool, [[`src/search-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/search-manager.ts)](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/search-manager.ts) creates a search session. The `SearchManager.startSearch` method validates the root path, generates a unique session ID, builds command-line arguments via `buildRipgrepArgs`, and spawns the ripgrep process. Results are streamed back as JSON lines for content searches or plain lines for file searches, with pagination handled by `readSearchResults`.

## Starting a Search Session

### Basic Search Parameters

The **`start_search`** tool accepts a payload matching the `StartSearchArgsSchema` defined in [[`src/tools/schemas.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts)](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts). At minimum, you must specify:

```typescript
{
  rootPath: '/home/user/projects',  // Absolute path to search folder
  pattern: 'TODO',                  // Search string or glob pattern
  searchType: 'content'             // 'files' or 'content'
}

```

The tool handler in [[`src/handlers/search-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/search-handlers.ts)](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/search-handlers.ts) processes these requests and delegates to the `SearchManager`.

### File Search vs. Content Search

The `searchType` parameter determines the ripgrep invocation strategy implemented in `SearchManager.buildRipgrepArgs` (lines 333-389):

- **File search** (`searchType: "files"`): Adds the `--files` flag and uses `--iglob` or `--glob` for filtering. Exact filenames pass through unchanged; substrings wrap with `*…*` wildcards.
- **Content search** (`searchType: "content"`): Adds `--json --line-number` for structured output, plus optional flags for case sensitivity, context lines, and literal matching.

## Retrieving and Managing Results

### Pagination with get_more_search_results

After starting a search, retrieve results using the **`get_more_search_results`** tool, implemented by `readSearchResults` in the search manager:

```typescript
{
  sessionId: 'search_3_1690567890123',  // Returned by start_search
  offset: 0,                            // Start index (use negative for tail)
  length: 100                           // Number of results to return
}

```

The API returns `results`, `totalResults`, `totalMatches`, and a `hasMoreResults` flag. Use a **negative offset** to implement a "tail" view that returns the last N results, mirroring file-reading semantics.

### Session Control Tools

- **`stop_search`**: Immediately terminates a running search process by session ID.
- **`list_searches`**: Returns an array of active sessions with metadata including `id`, `searchType`, `pattern`, and `isComplete`.

A global cleanup interval (started by `startCleanupIfNeeded`) runs every five minutes to delete completed sessions older than the default five-minute window.

## Advanced Search Configuration

### Literal String Matching

Set `literalSearch: true` to force fixed-string matching instead of regular expressions. This adds the `-F` flag to ripgrep (lines 41-44 in `buildRipgrepArgs`) and prevents regex-based ReDoS attacks when searching user input.

### Context Lines and Case Sensitivity

- **`contextLines: N`**: Adds `-C N` to show N lines of surrounding context for each match (lines 45-47).
- **`ignoreCase: true`**: Adds the `-i` flag for case-insensitive matching (default true for content searches).

### File Filtering and Result Limits

- **`filePattern`**: Pipe-separated glob patterns (e.g., `"*.ts|*.md"`) that translate to `-g` filters for content searches or `--iglob`/`--glob` for file searches (lines 66-84).
- **`maxResults: N`**: Hard limit on total matches, translated to the `-m N` ripgrep flag (lines 62-64).
- **`includeHidden: true`**: Adds the `--hidden` flag to search dotfiles and hidden directories (lines 58-60).

### Early Termination Optimization

By default, `earlyTermination: true` enables an optimization that stops the search immediately when an exact filename match is found (lines 31-49 in `processBufferedOutput`). Disable this when you need comprehensive results.

## Summary

- Desktop Commander MCP uses `@vscode/ripgrep` through platform-aware wrappers in [`scripts/ripgrep-wrapper.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/ripgrep-wrapper.js) and [`src/utils/ripgrep-resolver.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/ripgrep-resolver.ts).
- Invoke searches via the **`start_search`** tool with parameters like `rootPath`, `pattern`, and `searchType`.
- Retrieve paginated results using **`get_more_search_results`** with offset-based or tail-based semantics.
- Control matching behavior through `literalSearch`, `ignoreCase`, `contextLines`, and `filePattern` options that map directly to ripgrep flags.
- Manage long-running searches with **`stop_search`** and monitor active sessions via **`list_searches`**.

## Frequently Asked Questions

### What is the difference between file search and content search in Desktop Commander MCP?

File search (`searchType: "files"`) uses the `--files` flag to return matching filenames only, while content search (`searchType: "content"`) uses `--json --line-number` to return structured data including line numbers, match text, and context lines. File search applies glob patterns via `--iglob`, whereas content search uses `-g` filters.

### How does Desktop Commander MCP handle ripgrep binary resolution across different platforms?

The `getRipgrepPath()` function in [`src/utils/ripgrep-resolver.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/ripgrep-resolver.ts) attempts three resolution strategies: importing the bundled `@vscode/ripgrep` binary, locating a system `rg` via `which`/`where`, and scanning common installation directories. The [`scripts/ripgrep-wrapper.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/scripts/ripgrep-wrapper.js) shim ensures the correct platform-specific binary (e.g., `rg-x86_64-unknown-linux-musl` on Linux) is selected and executable permissions are set.

### Can I search using literal strings instead of regular expressions?

Yes. Set `literalSearch: true` in your `start_search` payload. This adds the `-F` flag to the ripgrep invocation, treating the pattern as a fixed string rather than a regex. This is implemented in `SearchManager.buildRipgrepArgs` and is recommended when searching for special characters or user-provided input.

### How do I paginate through large search results?

Use the **`get_more_search_results`** tool with the `sessionId` returned by `start_search`. Specify an `offset` (0-based index) and `length` (number of results). For viewing the most recent results first, use a negative offset value. The response includes `hasMoreResults` to indicate if additional pages exist and `isComplete` to show whether the underlying ripgrep process has finished executing.