# How to List Active Terminal Sessions with Desktop Commander MCP

> Learn how to list active terminal sessions with Desktop Commander MCP using the list_sessions command. Get real-time PID, runtime, and blocking status for shell and Node.js sessions.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-07-15

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/terminal-handlers.ts). Lines 51-55 of this file map the incoming command directly to the `listSessions()` implementation:

```typescript
// 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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/terminal-handlers.ts)**: Maps the `list_sessions` command to `handleListSessions` (lines 51-55)
- **[`src/tools/improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/terminal-manager.ts)**: Maintains the in-memory store of active OS processes and exposes `listActiveSessions()`
- **[`src/utils/process-detection.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/handlers/terminal-handlers.ts) to the `listSessions()` function in [`improved-process-tools.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/improved-process-tools.ts). Both storage mechanisms are strictly in-memory and synchronous, enabling instantaneous session listing without database or filesystem overhead.