How to List Active Terminal Sessions with Desktop Commander MCP

Desktop Commander MCP exposes a list_sessions command that queries the internal terminalManager to return real-time metadata for both active shell processes and virtual Node.js sessions, including PID, runtime, and blocking status.

Desktop Commander MCP is a Model Context Protocol server that manages interactive shell environments and inline code execution. When monitoring long-running tasks or debugging hanging processes, the ability to list active terminal sessions provides critical visibility into system state. This guide examines the implementation details within the wonderwhy-er/DesktopCommanderMCP repository, tracing how session data flows from the OS level to your client interface.

Understanding the Session Architecture

Desktop Commander MCP maintains two distinct categories of executable contexts. Real OS processes represent standard shell processes spawned through terminalManager.executeCommand, while virtual "node:local" sessions execute user-supplied JavaScript code directly inside the MCP process itself. Both session types are tracked in-memory without requiring external network calls.

The terminalManager instance stores metadata for shell processes, including process IDs and execution duration. Virtual sessions reside in a separate virtualNodeSessions map within the process tools module. This dual-track architecture ensures comprehensive visibility into every active computation, whether it originates from a system shell command or an inline Node.js snippet.

How the listSessions Tool Works

Handler Routing in terminal-handlers.ts

When a client sends the list_sessions command, the MCP server routes the request through handleListSessions in src/handlers/terminal-handlers.ts. Lines 51-55 of this file map the incoming command directly to the listSessions() implementation:

// Simplified excerpt from src/handlers/terminal-handlers.ts
export async function handleListSessions() {
  return await listSessions();
}

This thin wrapper pattern keeps the handler layer separate from business logic, delegating immediately to the core implementation in the tools layer.

Session Aggregation in improved-process-tools.ts

The actual retrieval logic resides in src/tools/improved-process-tools.ts (lines 94-125). The listSessions function aggregates data from two distinct sources:

1. Real processes: Calls terminalManager.listActiveSessions() to fetch OS-level shell processes spawned by executeCommand
2. Virtual sessions: Iterates over the virtualNodeSessions map to capture active node:local executions

The function merges these datasets into a unified view, handling the semantic differences between system processes and in-process JavaScript execution contexts.

Output Formatting Standards

The function transforms raw process metadata into human-readable strings. For real processes, the output includes PID, blocked status, and runtime duration. Virtual sessions display a negative PID identifier (e.g., -1001), the node:local label, and their timeout value rather than runtime.

The formatted text is wrapped in a ServerResult object where content[0].text contains the complete session list.

Practical Implementation Examples

Calling Sessions via HTTP API

To retrieve active sessions from a client application or chat interface:

const response = await fetch("/api/command", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ command: "list_sessions" })
});

const result = await response.json();
console.log(result.content[0].text);

Sample output showing mixed session types:

PID: 12345, Blocked: false, Runtime: 12s
PID: 12346, Blocked: true, Runtime: 0s
PID: -1001 (node:local), Timeout: 30000ms

Direct Node.js Integration

For internal tooling or custom MCP clients, import and invoke listSessions directly without HTTP overhead:

import { listSessions } from "./src/tools/improved-process-tools.js";

const result = await listSessions();
console.log(result.content[0].text);
// Output: Formatted list of all active sessions

This approach returns the same ServerResult structure, providing programmatic access to session metadata for dashboard updates or automated monitoring.

Key Source Files and Responsibilities

Several modules collaborate to provide session listing functionality:

• src/handlers/terminal-handlers.ts: Maps the list_sessions command to handleListSessions (lines 51-55)
• src/tools/improved-process-tools.ts: Contains the core listSessions logic that merges real and virtual session data (lines 94-125)
• src/terminal-manager.ts: Maintains the in-memory store of active OS processes and exposes listActiveSessions()
• src/utils/process-detection.ts: Supplies utilities for determining if processes are awaiting input (relevant for block status detection in session listings)

Summary

• Desktop Commander MCP tracks both shell processes and inline Node.js executions as "sessions" through separate but unified mechanisms
• The list_sessions command routes through src/handlers/terminal-handlers.ts to the listSessions() function in improved-process-tools.ts
• Session data originates from terminalManager for real processes and virtualNodeSessions for virtual ones, requiring no network I/O
• Output includes PID, runtime or timeout values, and blocking status formatted as human-readable text
• Developers can access session data either via MCP command protocol or by importing listSessions directly for programmatic use

Frequently Asked Questions

What types of sessions does Desktop Commander MCP track?

The system tracks two distinct session types: real OS processes spawned via standard shell commands (tracked by the terminalManager class) and virtual "node:local" sessions that execute JavaScript code directly within the MCP process (stored in the virtualNodeSessions map). Both types appear in the list_sessions output with appropriate distinguishing metadata.

How can I distinguish between real and virtual sessions in the output?

Real processes display positive PIDs with Runtime in seconds and Blocked status indicators (true/false). Virtual sessions show negative PID identifiers (commonly -1001) with the (node:local) suffix, and display a Timeout value in milliseconds rather than runtime duration.

Is it possible to list sessions without using the MCP command interface?

Yes. You can import listSessions directly from src/tools/improved-process-tools.js in your Node.js application code and await the function call. This returns a ServerResult object containing the formatted session list in the content[0].text property, bypassing the command routing layer and HTTP transport entirely.

Where is session metadata stored during execution?

Real process metadata lives in the terminalManager class instance, which maintains internal maps of active PIDs and their execution state. Virtual session metadata resides in the virtualNodeSessions map within improved-process-tools.ts. Both storage mechanisms are strictly in-memory and synchronous, enabling instantaneous session listing without database or filesystem overhead.

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