Desktop Commander MCP verbose_timing Parameter: Debug Process Performance

The verbose_timing parameter is an optional boolean flag that, when set to true, records detailed timing telemetry—including exit reasons, total duration, time-to-first-output, and output-event timelines—to help developers diagnose performance bottlenecks in terminal processes.

The verbose_timing parameter appears across the process toolset in the wonderwhy-er/DesktopCommanderMCP repository, providing deep visibility into command execution latency. When enabled, it surfaces granular timing data that reveals exactly why a process stopped, how quickly it began producing output, and which detection mechanisms triggered early termination.

What Is the verbose_timing Parameter?

The verbose_timing parameter is defined in src/tools/schemas.ts as an optional boolean field within the argument schemas for process-related tools. It defaults to false to keep ordinary interactions lightweight and is implemented in StartProcessArgsSchema, ReadProcessOutputArgsSchema, and InteractWithProcessArgsSchema.

When you invoke process tools with verbose_timing: true, the underlying terminal manager captures comprehensive timing metadata. According to the source code in src/tools/improved-process-tools.ts, this flag is forwarded to terminalManager.executeCommand(..., parsed.data.verbose_timing || false), which then instruments the process lifecycle.

Timing Telemetry Exposed by verbose_timing

Enabling this flag returns structured timing information that includes:

• Exit reason – Identifies why execution stopped, such as early_exit_quick_pattern, process_exit, or timeout.
• Total duration and time-to-first-output – Measures overall latency and the interval before the process emits its first data chunk.
• Output-event timeline – Chronological list of every output event, including timestamps, source streams (stdout/stderr), byte lengths, and matched patterns.
• Detection mechanism – Indicates which heuristic triggered early exit, such as pattern checks or periodic checks, enabling you to tune detection patterns for faster REPL prompts.

This data is formatted for human readability via the formatTimingInfo function in src/tools/improved-process-tools.ts, producing output blocks that start with 📊 Timing Information:.

Implementation Across the Codebase

You can trace the verbose_timing implementation through three critical files:

1. src/tools/schemas.ts – Defines the optional verbose_timing?: boolean field for all process tool argument schemas.
2. src/tools/improved-process-tools.ts – Propagates the flag to the terminal manager and formats the timing telemetry for tool responses.
3. src/server.ts – Documents the debugging benefits of verbose_timing for each process tool, explaining its utility for performance analysis.

How to Use verbose_timing in Process Tools

Starting a Process with Timing

When launching a new process, include verbose_timing: true in your arguments to capture the full execution timeline:

const result = await start_process({
  command: "python3 -i",
  timeout_ms: 8000,
  verbose_timing: true  // Enable detailed timing capture
});

The response includes a timingInfo block describing total duration, first-output latency, and each discrete output event.

Reading Output with Timing Telemetry

You can request timing data when reading from an already-running process:

const out = await read_process_output({
  pid: result.pid,
  offset: 0,            // Read from current position
  length: 200,
  verbose_timing: true  // Request timing telemetry
});

The returned content contains both captured text and a formatted timing section:

📊 Timing Information:
  Exit Reason: process_exit
  Total Duration: 1453ms
  Time to First Output: 87ms
  Output Events (12 total):
    [1] +87ms | stdout | 120b | ">>> "
    ...

Interacting with REPLs and Measuring Latency

For interactive sessions, verbose_timing helps quantify command latency within the REPL:

const reply = await interact_with_process({
  pid: pyPid,
  input: "import pandas as pd; df = pd.read_csv('data.csv')",
  timeout_ms: 10000,
  wait_for_prompt: true,
  verbose_timing: true  // Capture timing for this interaction
});

This reveals exactly how long the import took and when the first output rows appeared, allowing you to validate that data pipelines remain within acceptable latency bounds.

Summary

• The verbose_timing parameter exposes exit reasons and granular latency metrics for process execution.
• Implemented in src/tools/schemas.ts and src/tools/improved-process-tools.ts, it forwards timing instructions to the terminal manager.
• Defaults to false to maintain lightweight interactions, and should be enabled only when debugging.
• Essential for optimizing early-exit detection patterns and diagnosing stuck REPLs or slow commands.

Frequently Asked Questions

Does enabling verbose_timing slow down process execution?

No, the verbose_timing flag only instruments telemetry collection and does not alter the execution speed of the underlying process. The overhead is limited to timestamp recording and memory allocation for timing events, which is negligible for most debugging scenarios.

Where is the timing data formatted for display?

The formatTimingInfo function in src/tools/improved-process-tools.ts handles the formatting of raw timing metadata into human-readable charts and lists, including the 📊 Timing Information: header and chronological event logs.

Can I enable verbose_timing on processes that are already running?

Yes, you can request timing telemetry when calling read_process_output or interact_with_process on existing process IDs. However, timing data collection begins when you enable the flag, so you cannot retroactively capture timing from before the flag was set.

What exit reasons indicate that early-exit detection triggered?

When verbose_timing is enabled, an exit reason of early_exit_quick_pattern indicates that the process terminated because its output matched a predefined early-exit pattern, while timeout indicates the command exceeded its allocated duration without satisfying completion criteria.

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