# Desktop Commander MCP: list_processes/kill_process vs Session-Based Process Management Explained

> Understand Desktop Commander MCP process management: stateless list_processes/kill_process vs stateful session-based control. Choose the right tool for your needs.

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

---

**Desktop Commander MCP provides two distinct process management paradigms: stateless `list_processes` and `kill_process` commands for immediate system snapshots, and stateful session-based management that maintains persistent TerminalSession objects for interactive process control.**

Desktop Commander MCP is a Model Context Protocol server that exposes operating system process capabilities to AI assistants. While both approaches interact with OS processes, they serve fundamentally different architectural purposes—one provides fire-and-forget utilities for system administration, while the other enables long-lived interactive workflows with buffered I/O.

## Stateless Process Inspection with list_processes and kill_process

### Implementation in src/tools/process.ts

The simple process wrappers are implemented in [`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts). The **listProcesses** function (lines 9‑40) executes native OS commands like `tasklist` on Windows or `ps` on Unix, parsing the output to return PID, command, CPU, and memory metadata. The **killProcess** function (lines 42‑61) provides a thin wrapper around Node.js `process.kill`, immediately signaling the target process for termination.

### Stateless Architecture Characteristics

These commands operate on a **request-response cycle** without server-side persistence. Each invocation executes a fresh shell command, returns the current system state, and discards all context. This design allows inspection and termination of any OS process—including those not started by Desktop Commander MCP—but provides no mechanism for output buffering or subsequent interaction.

### Use Cases

- **System auditing**: Quickly enumerate all running processes to identify resource usage
- **Emergency termination**: Kill rogue or hanging processes by PID without session overhead
- **One-off diagnostics**: Check process status without establishing persistent connections

## Stateful Session-Based Process Management

### TerminalSession Architecture

The advanced implementation in [`src/tools/improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/improved-process-tools.ts) creates **TerminalSession** objects that persist for the duration of the child process. When **startProcess** (lines 94‑108) spawns a process, the server allocates a unique session identifier (the PID), initializes a line-buffered output queue, and begins tracking process lifecycle events. Unlike the stateless approach, this maintains active state between MCP tool invocations.

### Session Control API

Session-based management exposes granular control through specialized functions:

- **startProcess** (lines 94‑108): Spawns processes with optional custom shell and timeout configuration, returning a session PID for subsequent operations
- **readProcessOutput** (lines 42‑45): Retrieves paginated output from the session buffer without blocking, enabling polling-based clients to consume long-running command results
- **interactWithProcess** (lines 84‑86): Sends input strings to processes waiting on stdin, supporting REPLs and interactive shells
- **forceTerminate** (lines 58‑61): Gracefully or forcibly terminates the session with proper resource cleanup
- **listSessions** (lines 96‑100): Enumerates all active sessions including metadata about execution state and output buffer status

### Virtual Sessions and Node Execution

Desktop Commander MCP supports **virtual sessions** identified by "node:local" prefixes and negative PID values. These sessions execute JavaScript code directly within the MCP server process rather than spawning external OS processes, treated identically to standard sessions by the API but optimized for lightweight automation tasks.

## Architectural Comparison

| Feature | list_processes / kill_process | Session-Based Management |
|---|---|---|
| **Source File** | [`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts) | [`src/tools/improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/improved-process-tools.ts) |
| **State Model** | Stateless snapshot | Stateful TerminalSession |
| **Process Lifecycle** | Fire-and-forget | Tracked from spawn to termination |
| **I/O Capabilities** | None (metadata only) | Buffered output, interactive input |
| **Scope** | Any system process | Only processes started via startProcess (plus virtual sessions) |
| **Virtual Sessions** | Not supported | "node:local" with negative PIDs |

## Practical Code Examples

### Listing and Killing System Processes

To enumerate all processes and terminate a specific PID using the stateless API:

```typescript
// Reference: src/tools/process.ts
// List all system processes
const processes = await listProcesses();
// Returns: [{ pid: 1234, command: "node", cpu: 2.5, memory: "156MB" }, ...]

// Terminate by PID (line 42-61)
await killProcess(1234, "SIGTERM");

```

### Managing Interactive Sessions

For long-running commands requiring ongoing interaction:

```typescript
// Reference: src/tools/improved-process-tools.ts
// Start process (lines 94-108)
const session = await startProcess("python", ["-i"], { timeout: 300000 });
const pid = session.pid; // Store for subsequent calls

// Read buffered output (lines 42-45)
const output = await readProcessOutput(pid, { lines: 100 });

// Send interactive input (lines 84-86)
await interactWithProcess(pid, "print('Hello World')");

// Force termination when complete (lines 58-61)
await forceTerminate(pid);

```

## Summary

- **list_processes** and **kill_process** in [`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts) provide **stateless**, immediate system-wide process inspection and termination without server-side persistence
- **Session-based management** via [`src/tools/improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/improved-process-tools.ts) creates **stateful TerminalSession objects** that buffer output, track lifecycle, and enable interactive I/O through `startProcess`, `readProcessOutput`, and `interactWithProcess`
- Use stateless commands for ad-hoc system administration and emergency process termination
- Use session-based workflows for REPLs, build scripts, background jobs, or any process requiring incremental output consumption and input injection
- **Virtual sessions** ("node:local") execute inside the MCP server with negative PIDs, offering lightweight alternatives to external process spawning

## Frequently Asked Questions

### Can I kill a session-started process with kill_process?

Yes, since **kill_process** operates on OS-level PIDs, it can terminate any process including those started via **start_process**. However, using **force_terminate** is recommended because it properly cleans up the TerminalSession buffers and metadata in [`src/tools/improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/improved-process-tools.ts), whereas **kill_process** leaves stale session entries in the state manager.

### What are virtual sessions in Desktop Commander MCP?

**Virtual sessions** are "node:local" execution contexts that run JavaScript code directly inside the MCP server process rather than spawning external OS processes. According to the source code in [`src/tools/improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/improved-process-tools.ts), these sessions use negative PID values and are treated identically to regular sessions by **list_sessions**, but offer reduced overhead for automation tasks.

### Why does my process output disappear with list_processes?

The **list_processes** command only retrieves OS process metadata (PID, CPU, memory) from [`src/tools/process.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/process.ts) lines 9‑40. It does not capture stdout/stderr streams. To retain process output, you must use **start_process** to create a TerminalSession, which buffers all output into a per-session line queue accessible via **read_process_output**.

### Which approach should I use for background tasks?

For **long-running background tasks**, always use the session-based API (**start_process**). The stateless commands cannot track process completion or capture output streams. Session management provides timeout handling, exit code detection, and paginated output reading essential for background job monitoring.