How process.kill() Works in Desktop Commander: Node.js Process Termination Explained

Desktop Commander wraps Node.js's native process.kill(pid, [signal]) API within a validated MCP tool that sends SIGTERM by default and returns structured success or error messages.

The process.kill() implementation in Desktop Commander (wonderwhy-er/DesktopCommanderMCP) provides a secure, cross-platform mechanism for terminating system processes through the Model Context Protocol. By combining Zod schema validation with Node.js's built-in process management, the tool ensures that only valid Process IDs (PIDs) trigger system-level termination calls, preventing accidental or malformed requests from reaching the execution layer.

Argument Validation and Schema Definition

Before invoking any system call, Desktop Commander validates incoming arguments against the KillProcessArgsSchema. Defined in src/tools/schemas.ts (lines 51-53), this Zod schema strictly enforces that the pid parameter must be a number:

// src/tools/schemas.ts
const KillProcessArgsSchema = z.object({
  pid: z.number(),
});

This validation layer prevents type-related errors and ensures that only numeric process IDs proceed to the termination logic, shielding the underlying operating system from malformed inputs.

Core Implementation of process.kill()

The primary termination logic resides in src/tools/process.ts at line 52, where the validated PID is passed to Node.js's native process.kill() method.

Signal Dispatch and Default Behavior

When the killProcess tool executes, it calls process.kill(parsed.data.pid) without specifying an explicit signal. As implemented in the Desktop Commander source code, this invokes the operating system's default SIGTERM (signal 15), which requests graceful termination. This behavior mirrors Unix's kill command or Windows' TerminateProcess API, giving the target process opportunity to clean up resources before exiting.

Result Handling and Error Capture

The implementation includes comprehensive error handling in src/tools/process.ts (lines 54-60). Upon successful termination, the tool returns a plain-text confirmation:

// Success response format
`Successfully terminated process ${pid}`

When termination fails—due to non-existent PIDs, permission restrictions, or protected processes—the catch block wraps the error in a ServerResult object with isError: true, providing detailed failure information without crashing the MCP server.

Advanced Termination Strategies

For scenarios requiring guaranteed process cessation, Desktop Commander implements escalation patterns in src/terminal-manager.ts (lines 24-30).

Graceful vs. Forceful Termination

The TerminalManager.forceTerminate(pid) helper method implements a two-stage termination sequence:

1. Initial Interrupt: Sends SIGINT (signal 2) to request polite process interruption
2. Forced Kill: Waits 1 second, then escalates to SIGKILL (signal 9) if the process remains alive, which the OS enforces immediately without allowing cleanup

This pattern ensures that hung or unresponsive terminal sessions can be cleared reliably, balancing politeness with system stability.

Usage in Other Managers

Beyond the dedicated killProcess tool, the same process.kill() primitive appears in auxiliary managers such as src/search-manager.ts. These implementations follow identical patterns—schema validation followed by guarded termination calls—to abort long-running subprocesses like recursive file searches, maintaining architectural consistency across the codebase.

Code Examples

Basic process termination via the MCP tool:

import { killProcess } from './src/tools/process.js';

// Terminate process with PID 12345 using default SIGTERM
const result = await killProcess({ pid: 12345 });
// Returns: "Successfully terminated process 12345"

Force termination with signal escalation:

import { TerminalManager } from './src/terminal-manager.js';

const terminalManager = new TerminalManager();

// Sends SIGINT, waits 1s, then SIGKILL if necessary
terminalManager.forceTerminate(6789);

Summary

• Desktop Commander implements process termination through Node.js's native process.kill() API wrapped in MCP tool semantics according to the wonderwhy-er/DesktopCommanderMCP source code
• The KillProcessArgsSchema in src/tools/schemas.ts validates PIDs before execution
• Default behavior uses SIGTERM for graceful termination, implemented in src/tools/process.ts
• The forceTerminate method in src/terminal-manager.ts escalates from SIGINT to SIGKILL after a timeout
• All implementations return structured results with clear success messages or detailed error objects with isError: true

Frequently Asked Questions

What signal does Desktop Commander use by default for process.kill()?

By default, Desktop Commander uses SIGTERM (signal 15) when calling process.kill(). This follows Node.js's default behavior and allows the target process to perform cleanup operations before exiting, as implemented in src/tools/process.ts.

How does Desktop Commander handle processes that refuse to terminate?

The TerminalManager.forceTerminate() method implements an escalation strategy: it first sends SIGINT to request interruption, waits 1 second, and if the process persists, sends SIGKILL which the operating system enforces immediately without allowing the process to block or clean up.

Can process.kill() fail in Desktop Commander, and how are errors handled?

Yes, process.kill() can fail if the PID doesn't exist, the user lacks permissions, or the process is protected. Desktop Commander catches these errors in src/tools/process.ts (lines 54-60) and returns them as structured ServerResult objects with isError: true, preventing server crashes while reporting specific failure reasons.

Where is the PID validation performed before calling process.kill()?

PID validation occurs in src/tools/schemas.ts (lines 51-53) using Zod's KillProcessArgsSchema, which enforces that the pid parameter must be a number. This validation runs before src/tools/process.ts executes the actual process.kill() call.

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