How to Use `llmfit doctor` for Hardware Detection Reports in LLMFit

The llmfit doctor command generates a comprehensive, Markdown-formatted hardware detection report by running system tools, detecting GPUs via vendor-specific utilities, and gathering runtime information—all ready to paste into GitHub issues.

If you're troubleshooting GPU detection or runtime compatibility in the AlexsJones/llmfit project, llmfit doctor is your first diagnostic step. This built-in sub-command produces a reproducible dump of your system's hardware configuration and every external tool used during detection, formatted specifically for bug reports.

---

What llmfit doctor Does

Running llmfit doctor executes a six-stage diagnostic pipeline defined in [llmfit-core/src/doctor.rs](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/doctor.rs). Here's exactly what happens:

1. Version & OS Collection – Captures the binary version, operating system, and architecture.
2. System Specs Detection – Invokes SystemSpecs::detect() from [llmfit-core/src/hardware.rs](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/hardware.rs) to gather RAM, CPU, and GPU details.
3. External Tool Execution – Shells out to vendor-specific utilities including nvidia-smi, rocm-smi, lspci, system_profiler (macOS), PowerShell WMI queries, vulkaninfo, and npu-smi.
4. Sysfs/Registry Reading – Accesses /sys/class/drm/* on Linux or Windows registry keys for VRAM information.
5. Runtime Detection – Checks for LM Studio, Docker Desktop, and whether ollama is available on PATH.
6. Markdown Assembly – Each section is wrapped with ## Section Name headers and fenced code blocks via the section() helper at line 54.

The capture() helper (lines 15-38) manages each external call, capturing both stdout and stderr while safely truncating output to 16 KB per section to prevent oversized reports.

---

Running llmfit doctor from the Command Line

Basic Terminal Output

View the report directly in your terminal:

llmfit doctor

You'll see output structured like this:

# llmfit doctor report

...

## Detected by llmfit

[Structured hardware information]

## nvidia-smi

[Raw command output]

Save to File for Bug Reports

Redirect the output to a file for later inspection or GitHub issues:

llmfit doctor > llmfit-doctor.md

The resulting file is ready to paste into the bug report template's diagnostic field.

---

Using llmfit doctor Programmatically

You can invoke the same diagnostic collection from Rust code. The CLI entry point in [llmfit-tui/src/main.rs](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs) uses this exact pattern at line 2817:

use llmfit_core::doctor::collect_diagnostics;

fn main() {
    let report = collect_diagnostics(env!("CARGO_PKG_VERSION"));
    println!("{}", report);
}

The env!("CARGO_PKG_VERSION") macro automatically propagates your binary's version into the report header, ensuring reproducibility across different builds.

---

Submitting Reports to GitHub Issues

The .github/ISSUE_TEMPLATE/bug-report.yml file in the repository includes a dedicated field for diagnostic output. After running llmfit doctor > llmfit-doctor.md:

1. Open the generated file
2. Copy the entire contents
3. Paste into the "Diagnostic report (llmfit doctor)" field

This gives maintainers complete visibility into:

• Which detection tools succeeded or failed
• Raw GPU driver output
• Runtime environment state

---

Key Source Files Reference

File	Purpose
llmfit-core/src/doctor.rs	Core implementation of report generation and external tool orchestration
llmfit-core/src/hardware.rs	SystemSpecs::detect() implementation for RAM/CPU/GPU detection
llmfit-tui/src/main.rs	CLI routing at line 2817 that forwards to collect_diagnostics
docs/cli.md	Official CLI documentation including llmfit doctor usage
.github/ISSUE_TEMPLATE/bug-report.yml	Bug report template with diagnostic field

---

Summary

• llmfit doctor is the canonical command for hardware detection reports in LLMFit
• Reports are Markdown-native and structured for immediate GitHub issue inclusion
• The command runs 8+ external detection tools across NVIDIA, AMD, Intel, and Apple Silicon platforms
• Output is automatically truncated to 16 KB per section for manageable report sizes
• Use collect_diagnostics() directly in Rust programs for custom integrations

---

Frequently Asked Questions

What hardware detection tools does llmfit doctor run?

The command executes platform-specific utilities: nvidia-smi and npu-smi for NVIDIA devices, rocm-smi for AMD, vulkaninfo for Vulkan-compatible GPUs, lspci on Linux, system_profiler on macOS, and PowerShell WMI queries on Windows. Each tool's raw output appears in its own report section.

Why is my llmfit doctor output truncated?

The capture() helper in doctor.rs enforces a 16 KB limit per section to prevent massive reports from overwhelming issue trackers. This threshold covers typical tool output while filtering runaway logs. If you need complete unfiltered output, run the individual detection commands manually.

Can I run llmfit doctor without installing the full TUI?

Yes—llmfit doctor is a standalone function in llmfit-core. Any Rust program can import llmfit_core::doctor::collect_diagnostics and generate reports without the terminal interface, as shown in the programmatic example above.

Where do I submit my llmfit doctor report?

Paste the complete output into the .github/ISSUE_TEMPLATE/bug-report.yml template when filing issues on the AlexsJones/llmfit repository. The template includes a specific field labeled "Diagnostic report (llmfit doctor)" designed for this purpose.

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