# How the Process Detection Utility Works in DesktopCommanderMCP: Analyzing listProcesses and REPL State

> Understand DesktopCommanderMCP's process detection utility. Discover how listProcesses identifies running applications by analyzing console output and system commands like ps aux or tasklist.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: internals
- Published: 2026-07-19

---

**The DesktopCommanderMCP process detection utility interprets raw console output to determine if a process is running, waiting for input, or finished, while `listProcesses` queries the operating system using platform-specific commands like `ps aux` or `tasklist` to identify running applications.**

The DesktopCommanderMCP repository provides a TypeScript-based process management system that combines real-time REPL session monitoring with system process enumeration. This toolset allows the MCP server to distinguish between interactive processes awaiting input and terminated sessions, while the `listProcesses` function exposes running applications across Windows and Unix-like platforms.

## Core Process Detection Architecture

The process detection utility resides in [`src/utils/process-detection.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/process-detection.ts) and implements heuristic analysis to classify process states without requiring deep OS integration.

### REPL Prompts and Pattern Matching

The utility defines three critical data structures to recognize process behavior:

- **REPL_PROMPTS**: A collection of common interactive prompts (Python `>>>`, Node `>`, R `>`, etc.) defined at lines 15-24 that signal a process waiting for user input
- **ERROR_COMPLETION_PATTERNS**: Regular expressions matching typical error messages (lines 27-40) that indicate process termination with failure
- **COMPLETION_INDICATORS**: Explicit termination strings like "Process finished" or "Exit code" (lines 42-49) that confirm successful completion

These constants enable the utility to parse raw stdout content and categorize process states accurately.

### State Analysis Logic

The exported `analyzeProcessState(output, pid?)` function implements a five-step decision tree to determine process status:

1. **Empty check**: Returns "running" if no output exists
2. **Prompt detection**: Scans the final line for REPL prompts; if found, returns `isWaitingForInput: true`
3. **Completion detection**: Validates against `COMPLETION_INDICATORS` to set `isFinished: true`
4. **Error analysis**: Applies `ERROR_COMPLETION_PATTERNS` to recent lines, marking finished unless a prompt suggests the process remains interactive
5. **Default state**: Assumes still running if no patterns match

The function returns a `ProcessState` object consumed by downstream components to render human-readable status messages.

### Output Cleaning and Formatting

Two additional exports support clean output presentation:

- **`cleanProcessOutput`**: Strips echoed input lines and prompt symbols from raw terminal output
- **`formatProcessStateMessage`**: Converts `ProcessState` objects into concise strings (e.g., "Process 1234 is waiting for input (detected: '> ')")

These utilities are imported by [`src/tools/improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/improved-process-tools.ts) and [`src/terminal-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/terminal-manager.ts) to handle REPL-style interactions.

## Enumerating System Processes with listProcesses

While the detection utility monitors individual process output, the `listProcesses` function in [`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts) enumerates all system applications.

### Platform-Specific Command Execution

The function uses Node's `os.platform()` to select the appropriate system command:

- **Windows**: Executes `tasklist`
- **Unix/Linux/macOS**: Executes `ps aux`

The selected command runs asynchronously via `child_process.exec` wrapped with `util.promisify` (line 10), ensuring non-blocking operation within the MCP server.

### Data Extraction and Formatting

After executing the platform command, `listProcesses` processes the stdout through several transformation steps:

1. Splits output into lines and removes the header row using `.slice(1)`
2. Parses each line with a whitespace regex (`line.split(/\s+/)`)
3. Constructs `ProcessInfo` objects containing:
   - **PID**: Extracted from `parts[1]`
   - **Command**: Taken from `parts[parts.length-1]`
   - **CPU**: Parsed from `parts[2]`
   - **Memory**: Parsed from `parts[3]`

The function returns a `ServerResult` object (lines 28-32) containing formatted text with entries like "PID: 342, Command: node, CPU: 0.2, Memory: 1.3". If execution fails, it returns an error result with `isError: true` (lines 34-38).

## Practical Implementation Examples

The following examples demonstrate usage of both utilities:

### Detecting REPL State

```typescript
import { analyzeProcessState } from './src/utils/process-detection.js';

const output = `>>> print("hello")\nhello\n>>> `;
const state = analyzeProcessState(output, 1234);
console.log(state);
// => { isWaitingForInput: true, isFinished: false, isRunning: true, detectedPrompt: '>>> ' }

```

### Listing Running Processes

```typescript
import { listProcesses } from './src/tools/process.js';

async function showProcesses() {
  const result = await listProcesses();
  console.log(result.content[0].text);
}
// Output:
// PID: 1, Command: init, CPU: 0.0, Memory: 0.1
// PID: 342, Command: node, CPU: 0.2, Memory: 1.3

```

## Summary

- The **process detection utility** in [`src/utils/process-detection.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/process-detection.ts) analyzes console output using `REPL_PROMPTS`, `ERROR_COMPLETION_PATTERNS`, and `COMPLETION_INDICATORS` to classify process states
- **`analyzeProcessState`** implements a five-step heuristic to determine if a process is running, waiting for input, or finished
- **`listProcesses`** in [`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts) executes `tasklist` or `ps aux` based on platform to enumerate system applications
- Both utilities return structured data objects that integrate with the MCP server API for process monitoring and management

## Frequently Asked Questions

### How does the process detection utility determine if a REPL is waiting for input?

The utility scans the final line of output against known prompt strings defined in `REPL_PROMPTS` (such as Python's `>>>` or Node's `>`). When a match is detected in `analyzeProcessState`, the function returns a state object with `isWaitingForInput: true`, indicating the process requires user interaction before continuing execution.

### What platform-specific commands does listProcesses use to identify running applications?

The function checks `os.platform()` to select between Windows `tasklist` and Unix-style `ps aux` commands. These system utilities provide comprehensive process listings that the function parses to extract PID, command name, CPU usage, and memory consumption for each running application.

### Can the process detection utility identify when a process has crashed rather than completed normally?

Yes, the `ERROR_COMPLETION_PATTERNS` regular expressions match typical error message formats in the output tail. When detected without a corresponding REPL prompt, `analyzeProcessState` marks the process as finished with an error state, distinguishing between graceful termination and crash conditions.

### Where are the helper functions for cleaning process output located?

The `cleanProcessOutput` and `formatProcessStateMessage` utilities are exported from [`src/utils/process-detection.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/process-detection.ts) alongside `analyzeProcessState`. These functions strip echoed input lines from raw terminal output and convert `ProcessState` objects into human-readable status messages for MCP server responses.