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

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 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 and 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 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

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

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 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 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 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.

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