How the Doctor Command Aggregates System Diagnostics in llmfit

The doctor command in llmfit compiles a comprehensive markdown diagnostic report by executing external GPU/CPU detection tools, truncating their output to 16 KB sections, and formatting everything into fenced code blocks suitable for GitHub issue pasting.

The diagnostic aggregation logic resides in llmfit-core/src/doctor.rs, where the collect_diagnostics() function orchestrates hardware detection across Linux, macOS, and Windows. This functionality enables users to generate standardized system reports for troubleshooting LLM provider compatibility issues by capturing raw tool output alongside LLMFit-detected specifications.

Capture and Truncation Pipeline

External Tool Execution and Output Limits

The foundation of the diagnostic report is the capture() function (lines 15-38), which spawns subprocesses for hardware detection utilities like nvidia-smi, rocm-smi, and lspci. This function merges stdout and stderr, normalizes empty output, and handles missing binaries gracefully by converting errors into explanatory notes rather than failing.

To prevent runaway output from flooding the report, the truncate() function (lines 41-51) enforces a MAX_SECTION_BYTES limit of 16 KB per section. When content exceeds this threshold, the function trims on character boundaries and appends an ellipsis with a truncation notice, ensuring deterministic report sizes regardless of system configuration.

Markdown Section Formatting

The section() helper (lines 54-56) standardizes the visual presentation of each diagnostic block. It accepts the accumulating report string, a section title, and the body content, then appends a markdown header, wraps the body in triple backticks, and adds trailing newlines. This creates consistent fenced code blocks that developers can parse programmatically when users paste reports into GitHub issues.

Platform-Specific Hardware Detection

Linux DRM and PCI Analysis

On Linux systems, the sysfs_drm_summary() function (lines 58-100) walks /sys/class/drm/card* directories to extract vendor, device, driver, and VRAM fields from sysfs entries. This provides kernel-level GPU metadata regardless of whether vendor-specific tools like nvidia-smi are installed. The function additionally filters lspci output to capture only display-controller lines, offering a complete picture of graphics hardware without excessive verbosity.

macOS System Profiler Integration

For macOS hosts, the aggregation logic executes system_profiler SPDisplaysDataType to retrieve GPU specifications through Apple's native diagnostic interface. This output is captured via the standard capture() pipeline and formatted into a dedicated section, ensuring Mac users provide the same hardware context as Linux users despite differing underlying tools.

Windows PowerShell and Registry Queries

Windows diagnostics leverage PowerShell cmdlets (Win32_VideoController) and registry-based VRAM queries to enumerate graphics adapters. These platform-specific invocations are conditionally compiled alongside the Linux and macOS pathways, allowing collect_diagnostics() to present unified output regardless of the host operating system.

Cross-Platform Fallback Mechanisms

When GPU-specific vendor tools are unavailable, the doctor command falls back to cross-platform utilities. It executes vulkaninfo --summary to gather graphics API capabilities and npu-smi info for neural processing unit detection. These fallback commands ensure the report contains hardware acceleration evidence even on systems without proprietary driver packages installed.

LLMFit Specifications and Provider Verification

Beyond raw system tools, the aggregation pipeline incorporates LLMFit-detected specifications via SystemSpecs::detect() (defined in llmfit-core/src/hardware.rs). The doctor command formats these structured specifications with pretty-print debugging ({specs:#?}) into a dedicated section, allowing comparison between LLMFit's internal detection and the raw OS-reported values.

The report concludes with provider installation evidence by calling helper functions from llmfit-core/src/providers.rs: lmstudio_app_installed(), docker_desktop_installed(), and command_exists("ollama"). These checks document which LLM provider binaries are present on the system, completing the diagnostic picture for support troubleshooting.

Report Assembly and CLI Integration

The collect_diagnostics(version) function (starting at line 103) initializes a String buffer and sequentially appends:

1. A report header with OS, architecture, and llmfit version
2. Pretty-printed SystemSpecs output
3. Platform-specific hardware tool results
4. Cross-platform fallback summaries
5. Provider installation status

After all sections are aggregated, the complete markdown string returns to the CLI entry point in llmfit-tui/src/main.rs, which prints the output directly to stdout. Users can then copy the entire report—complete with fenced code blocks and truncation notices—and paste it into GitHub issues without manual formatting.

Summary

• The capture() function in doctor.rs executes external tools while safely handling missing binaries and merging stdout/stderr streams.
• MAX_SECTION_BYTES (16 KB) limits prevent individual diagnostic sections from exceeding reasonable size constraints via the truncate() utility.
• Platform-specific pathways handle Linux sysfs DRM, macOS system_profiler, and Windows PowerShell queries to maximize hardware detection coverage.
• Fallback commands like vulkaninfo ensure the report contains graphics information even without vendor-specific utilities installed.
• Provider installation checks from providers.rs document the presence of LM Studio, Docker Desktop, and Ollama binaries alongside hardware specifications.

Frequently Asked Questions

How does the doctor command handle missing GPU utilities like nvidia-smi?

When capture() cannot spawn a requested binary, it returns a friendly explanatory note rather than an error, allowing the report to continue accumulation. The truncation logic ensures that even if a tool returns unexpected verbose output, the section caps at 16 KB to maintain readability.

What is the maximum size for individual diagnostic sections?

Each section is limited to 16 KB (16,384 bytes) by the MAX_SECTION_BYTES constant enforced through the truncate() function. When content exceeds this limit, the output is trimmed and marked with "… (truncated)" to indicate incomplete data.

Where does the doctor command fit into the llmfit architecture?

The core aggregation logic lives in llmfit-core/src/doctor.rs, while the CLI entry point resides in llmfit-tui/src/main.rs. The TUI binary calls llmfit_core::doctor::collect_diagnostics(version) and prints the returned markdown string, separating the diagnostic engine from the interface layer.

Why does the doctor command use fenced code blocks in the output?

The section() function wraps all tool output in triple backticks to create valid markdown fenced code blocks. This formatting allows developers to copy-paste user reports directly into GitHub issues while maintaining structured data that automated parsers can extract for regression testing or hardware compatibility analysis.

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