Process Management Tools in Desktop Commander MCP: Complete Technical Guide

Desktop Commander MCP exposes seven RPC-style process management tools through src/tools/improved-process-tools.ts and 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 and wire into the server via src/handlers/process-handlers.ts.

Interactive Session Controls

Located in 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, 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 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.

Process State Detection

The analyzeProcessState utility in 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.

Starting a Process

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

Reading Paginated Output

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

Interactive Input with Prompt Detection

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

Force Termination

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

Listing Active Sessions

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

Sample response:

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

System Process Enumeration

{
  "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

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

Key Source Files

Feature	Source File
Process spawning and interaction	src/tools/improved-process-tools.ts
Low-level OS utilities	src/tools/process.ts
RPC handler wiring	src/handlers/process-handlers.ts
Zod argument schemas	src/tools/schemas.ts
Process state detection	src/utils/process-detection.ts
Terminal lifecycle backend	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) from basic OS utilities (process.ts), with both delegating to 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 sends POSIX SIGTERM on Unix-like systems or Windows-equivalent termination commands. force_terminate in 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 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.

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