# How the Doctor Command Aggregates System Diagnostics in llmfit > Learn how the llmfit doctor command aggregates system diagnostics in llmfit-core/src/doctor.rs. It compiles a markdown report with truncated output from external tools. - Repository: [Alex Jones/llmfit](https://github.com/AlexsJones/llmfit) - Tags: internals - Published: 2026-09-12 --- **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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/doctor.rs), while the CLI entry point resides in [`llmfit-tui/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/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.