Wispterm Diagnostics

WispTerm Diagnostics

Overview

Generate a safe, copyable Markdown diagnostic report for users filing WispTerm issues. On Windows, installed WispTerm release packages include this plugin, so the preferred user-facing path is to ask the user to invoke $wispterm-diagnostics from WispTerm's AI Chat or Copilot and include their symptoms/reproduction steps. The skill then uses the bundled PowerShell script to collect WispTerm, Windows, OpenSSH, WebView2, bundled ConPTY, GPU, logs, and config details. Do not ask Windows users to find a source checkout first.

On macOS, there is no equivalent script yet — use the manual bash workflow in the macOS section below.

Windows Workflow

1. If a user needs instructions, tell them to open a WispTerm AI Chat tab or Copilot sidebar and send a request like:

$wispterm-diagnostics
Problem type: ssh-disconnect
Symptom: SSH Profile disconnects after 5-10 minutes idle with "Connection reset".
Repro steps: connect to the saved SSH profile, leave it idle, then run ls.
What I already tried: external ssh.exe with ServerAliveInterval works.

2. Infer -ProblemType from the user's text. If it is unclear, use other and keep the user's symptom/repro text in the generated issue draft.
3. Run the script from this skill directory as the implementation detail:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\collect_wispterm_diagnostics.ps1 -ProblemType "other"

Use pwsh instead of powershell only if Windows PowerShell is unavailable.

Recommended labels: startup/crash, rendering/DPI, high-cpu, keyboard/input, selection/copy/scrolling, SSH/SCP, ssh-image-preview, html-preview, ssh-disconnect, file explorer, WebView2/browser panel, updater, remote console, other.

4. For rendering/DPI/multi-monitor glitch reports, first check whether render-diagnostic.log is already present. If not, ask the user to add wispterm-debug-render = true to their config (press Ctrl+, to open it), restart WispTerm, reproduce the glitch, then run the script. The log is written to %APPDATA%\wispterm\render-diagnostic.log.

   For high-cpu reports, run the script while WispTerm is exhibiting the high-CPU behavior so the 3-second CPU sample captures the real usage.

5. For startup/crash reports, run the automated startup probe. It enables WISPTERM_RENDER_DIAGNOSTICS=1 only for the probe process, starts WispTerm with auto-update disabled, waits briefly, then closes/kills the process if it did not crash:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\collect_wispterm_diagnostics.ps1 -ProblemType "startup/crash" -StartupProbe

6. If the user is willing to reproduce a crash and can share a dump privately, enable Windows Error Reporting local dumps before the startup probe:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\collect_wispterm_diagnostics.ps1 -ProblemType "startup/crash" -StartupProbe -EnableCrashDumps

This writes HKCU-only WER settings for wispterm.exe and reports the dump folder. Do not ask the user to attach .dmp files publicly; dumps may contain terminal text, environment fragments, tokens, paths, or other process memory.

7. Return a GitHub-ready Markdown issue body. Include the user's symptom, reproduction steps, expected behavior, diagnostic report, and issue-specific next steps. Ask them to review it before posting publicly and remove secrets.

If WispTerm cannot start or the AI Agent is unavailable, use the script command above from the installed/extracted WispTerm folder that contains plugins\skills\wispterm-diagnostics. That is a fallback, not the normal FAQ path.

High-Signal Issue Workflows

Use these on top of the Windows report. The script intentionally avoids logging into remote hosts; ask the user to run the remote commands manually and paste only non-secret output.

SSH image preview fails, Markdown preview works

1. Use the skill with this context:

$wispterm-diagnostics
Problem type: ssh-image-preview
Symptom: SSH image preview fails, but Markdown/text preview works.
Repro steps: ...

2. Ask the user to confirm the SSH tab was opened from WispTerm's built-in SSH profile launcher. Remote previews require WispTerm SSH metadata; a tab where the user typed ssh user@host inside a local shell is treated as local and cannot use remote preview helpers.
3. Ask for the file extension, approximate size, path shape (absolute, relative, contains spaces/CJK), and whether both Ctrl-click and File Explorer double-click fail.
4. Ask them to Ctrl+Shift-click the same remote image to download it. If download also fails, investigate SSH/SCP/path metadata. If download works but preview fails, investigate image decode/rendering.

HTML preview fails

1. Use the skill with this context:

$wispterm-diagnostics
Problem type: html-preview
Symptom: HTML preview or browser panel fails.
Repro steps: ...

2. Identify the environment: local Windows, WSL, or SSH. For SSH, confirm it is a WispTerm SSH profile session, not a manually typed SSH tab.
3. HTML preview serves the file's directory over HTTP so relative CSS/JS/images work. Ask the user to run this in the target environment:

command -v python3 python node npx
python3 --version 2>/dev/null || true
python --version 2>/dev/null || true
node --version 2>/dev/null || true
npx --version 2>/dev/null || true

4. Ask for the visible toast/error text, especially HTML server not reachable or HTML SSH tunnel failed. For SSH HTML, also ask whether normal loopback URLs printed by the remote host open through WispTerm.