# Process Management Tools in Desktop Commander MCP: Complete Technical Guide

> Explore seven process management tools in Desktop Commander MCP. Spawn processes stream output send input and terminate processes. Get the complete technical guide now.

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

---

**Desktop Commander MCP exposes seven RPC-style process management tools through [`src/tools/improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/improved-process-tools.ts) and [`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts), enabling clients to spawn processes, stream output, send interactive input, and terminate both real OS processes and virtual Node sessions.**

Desktop Commander MCP provides a self-contained process management suite that bridges AI clients with operating system-level command execution. These tools allow programmatic control over process lifecycle, output pagination, and interactive terminal sessions directly through the Model Context Protocol (MCP) server architecture.

## Core Process Management Tools

The process management API divides functionality between high-level interactive session controls and low-level OS utilities. All tools validate arguments against Zod schemas defined in [`src/tools/schemas.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts) and wire into the server via [`src/handlers/process-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/process-handlers.ts).

### Interactive Session Controls

Located in [`src/tools/improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/improved-process-tools.ts), these five tools handle sophisticated process interactions with state detection and virtual session support:

**`start_process`** (implemented in `startProcess`, lines 99‑108)  
Spawns a new command or initiates a virtual Node session via the special `node:local` directive. The function handles automatic shell detection, configurable timeouts via `timeout_ms`, and optional verbose timing telemetry. When starting virtual sessions, it creates temporary `.mjs` files and assigns negative PIDs for tracking in the `virtualNodeSessions` registry.

**`read_process_output`** (implemented in `readProcessOutput`, lines 42‑82)  
Reads output from running processes with pagination support using `offset` and `length` parameters. Supports three read modes: "new-output" (delta since last read), absolute positioning, and tail reading. Returns process status messages, state detection results, and optional timing information.

**`interact_with_process`** (implemented in `interactWithProcess`, lines 88‑146)  
Sends input strings to running processes and optionally waits for prompt detection. The tool recognizes standard prompt patterns (`>>>`, `>`, `$`, `#`) and returns cleaned output with state emojis, truncation handling, and execution timing telemetry.

**`force_terminate`** (implemented in `forceTerminate`, lines 60‑71)  
Force-terminates running processes by PID. Distinguishes between real OS processes (managed by the terminal manager) and virtual Node sessions (negative PIDs), removing the latter from the `virtualNodeSessions` map while sending appropriate kill signals to the former.

**`list_sessions`** (implemented in `listSessions`, lines 96‑107)  
Enumerates all active sessions, combining real OS processes from the terminal manager with virtual Node sessions. Returns runtime statistics, blocking status, and timeout configurations for each session.

### System-Level Process Utilities

Found in [`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts), these tools provide direct OS integration without session management overhead:

**`list_processes`** (implemented in `listProcesses`, lines 9‑33)  
Executes platform-specific process enumeration commands (`tasklist` on Windows, `ps aux` on Unix-like systems) and parses results into structured PID/command/CPU/Memory tables.

**`kill_process`** (implemented in `killProcess`, lines 42‑61)  
Sends POSIX `SIGTERM` signals (or Windows-equivalent termination) to specific PIDs, returning success or error status based on process existence and permissions.

## Architecture and Implementation

### Terminal Manager Backend

The `terminalManager` imported from [`src/terminal-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/terminal-manager.ts) owns the actual process lifecycle. It provides the underlying primitives used by the improved tools: `executeCommand` for spawning, `readOutputPaginated` for streaming, and `sendInputToProcess` for interaction. This abstraction layer separates the RPC handlers from OS-specific process management.

### Command Validation

Before any process tool executes, `commandManager.validateCommand` screens incoming commands for security and syntax validity. This validation layer runs prior to the terminal manager invocation in [`src/tools/improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/improved-process-tools.ts).

### Process State Detection

The `analyzeProcessState` utility in [`src/utils/process-detection.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/process-detection.ts) powers intelligent interaction capabilities. It analyzes output streams to determine whether a process is awaiting input, finished execution, or actively running, enabling the prompt-waiting behavior in `interact_with_process`.

### Virtual Node Sessions

When clients send the special command `node:local`, Desktop Commander MCP creates temporary `.mjs` files and executes them within the MCP runtime rather than spawning separate OS processes. These sessions receive negative PID values (e.g., `-1001`) and reside in the `virtualNodeSessions` map, yet expose an identical API surface for start, interact, and terminate operations.

## Practical Usage Examples

Clients interact with these tools via JSON-RPC payloads matching the schemas in [`src/tools/schemas.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts).

### Starting a Process

```json
{
  "tool": "start_process",
  "args": {
    "command": "ping -c 4 example.com",
    "timeout_ms": 10000,
    "verbose_timing": true
  }
}

```

### Reading Paginated Output

```json
{
  "tool": "read_process_output",
  "args": {
    "pid": 1234,
    "offset": 0,
    "length": 100,
    "verbose_timing": false
  }
}

```

### Interactive Input with Prompt Detection

```json
{
  "tool": "interact_with_process",
  "args": {
    "pid": 1234,
    "input": "ls -la\n",
    "wait_for_prompt": true,
    "verbose_timing": true
  }
}

```

### Force Termination

```json
{
  "tool": "force_terminate",
  "args": { "pid": 1234 }
}

```

### Listing Active Sessions

```json
{
  "tool": "list_sessions",
  "args": {}
}

```

Sample response:

```

PID: 5678, Blocked: false, Runtime: 12s
PID: -1001 (node:local), Timeout: 30000ms

```

### System Process Enumeration

```json
{
  "tool": "list_processes",
  "args": {}
}

```

Yields formatted output:

```

PID: 3124, Command: /usr/bin/bash, CPU: 0.0, Memory: 0.1
PID: 8421, Command: node, CPU: 0.2, Memory: 1.3

```

### Killing a Specific Process

```json
{
  "tool": "kill_process",
  "args": { "pid": 8421 }
}

```

## Key Source Files

| Feature | Source File |
|---------|-------------|
| Process spawning and interaction | [`src/tools/improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/improved-process-tools.ts) |
| Low-level OS utilities | [`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts) |
| RPC handler wiring | [`src/handlers/process-handlers.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/process-handlers.ts) |
| Zod argument schemas | [`src/tools/schemas.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts) |
| Process state detection | [`src/utils/process-detection.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/process-detection.ts) |
| Terminal lifecycle backend | [`src/terminal-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/terminal-manager.ts) |

## Summary

- **Seven distinct tools** provide comprehensive process management: `start_process`, `read_process_output`, `interact_with_process`, `force_terminate`, `list_sessions`, `list_processes`, and `kill_process`.
- **Dual architecture** separates interactive session controls ([`improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/improved-process-tools.ts)) from basic OS utilities ([`process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/process.ts)), with both delegating to [`terminal-manager.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/terminal-manager.ts).
- **Virtual Node sessions** enable JavaScript execution within the MCP runtime using negative PIDs and temporary `.mjs` files, distinct from standard OS process spawning.
- **State-aware interaction** via `analyzeProcessState` allows tools to detect prompts and block states, supporting complex CLI workflows.
- **Platform abstraction** handles Windows (`tasklist`) and Unix (`ps aux`) differences transparently in `listProcesses`.

## Frequently Asked Questions

### What is the difference between `list_sessions` and `list_processes` in Desktop Commander MCP?

`list_sessions` queries the internal terminal manager and virtual session registry to return Desktop Commander MCP's actively managed processes, including virtual Node sessions with negative PIDs. `list_processes` executes system commands (`tasklist` or `ps aux`) to enumerate all OS-level processes regardless of origin, providing a complete system view.

### How does Desktop Commander MCP handle virtual Node sessions differently from OS processes?

Virtual Node sessions execute JavaScript code within the MCP runtime via temporary `.mjs` files rather than spawning separate OS processes. These sessions receive negative PID values (e.g., `-1001`) and reside in the `virtualNodeSessions` map. While they share the same API surface for interaction, `force_terminate` handles them by removing the map entry rather than sending OS kill signals.

### What signals are used when `force_terminate` or `kill_process` is called?

`kill_process` in [`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts) sends POSIX `SIGTERM` on Unix-like systems or Windows-equivalent termination commands. `force_terminate` in [`src/tools/improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/improved-process-tools.ts) distinguishes between virtual sessions (map removal) and real processes, delegating to the terminal manager for actual OS signal delivery.

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

The `analyzeProcessState` utility in [`src/utils/process-detection.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/process-detection.ts) scans output streams for standard prompt patterns including `>>>`, `>`, `$`, and `#`. When `interact_with_process` is called with `wait_for_prompt: true`, it polls the output buffer until these patterns appear or a timeout occurs, indicating the process is blocked awaiting user input.