WinDbg Integration

A Visual Studio Code extension that provides a WinDbg like debugging experience. You can debug multiple targets simultaneously, such as dump files (*.dmp), Time Travel Debugging (TTD) traces (*.run), live user-mode processes, and kernel debugging sessions. The extension also integrates with GitHub Copilot to let AI investigate various debugging scenarios on your behalf.

⚠️ Important This is an unofficial project and is not affiliated with, endorsed by, or supported by Microsoft. "WinDbg", "Hyper-V", and other product names are trademarks of their respective owners. It is built purely for personal experimentation: it started as a WinDbg-like debugger but has grown into a grab-bag of loosely related tools (Hyper-V VM management, LLVM/LLDB-based Linux core dump analysis, and more). Because it is developed to scratch the author's own curiosity and whatever happens to be needed at the time, features may be added, changed, or removed inconsistently and without notice. Preserving UI design, features, or backward compatibility is not a goal. Use this extension at your own risk.

Release history is available in CHANGELOG.md, generated from the versioned release notes and included in the VSIX for offline inspection.

Getting Started

1. Install the extension from the Visual Studio Marketplace.
2. Open the Run and Debug view (Ctrl+Shift+D).
3. On the Debug Sessions view, there are buttons to start a new session of various debug target types (dump, trace, live user-mode, kernel-mode session). Click the button for the type of session you want to start.
4. You can also attach to a running process from the Processes view.

ℹ️ Note When the extension is first activated, the extension will prompt to download and install the WinDbg engine, Time Travel Debugging (TTD) command-line utility, and Sysinternals ProcDump. These components are required for full functionality.

Features

• WinDbg-like debugging UX and same command set — a familiar debugging experience by leveraging the DbgX package and the underlying WinDbg engine.
• Debug sessions view — a session-centric list to start and manage debug sessions (activate, interrupt, resume, hide, terminate).
• Linux .NET core dump analysis (experimental) — open a Linux ELF core dump produced by .NET's createdump (WinDbg: Open Linux Core Dump) and analyze it either natively (WinDbg engine) or with full managed state via an lldb + SOS command window running in Docker, which GitHub Copilot can also drive. Extensionless files that look like a Windows minidump or a Linux ELF core are auto-detected on open and offered to WinDbg. See Linux .NET core dump analysis for details.
• Wait for Process and Debug — arm a launch trap for an executable that is not running yet and either start a debug session (via an IFEO launch broker) or record a TTD trace the moment it starts. Live launch/attach flows can keep or skip the debugger's initial break.
• launch.json support — start a live user-mode debug session (or a Time Travel Debugging recording) straight from the Run and Debug view (F5).
• Processes view — list running processes (filter by name; Current user / Attached / Recording toggles; flat List or parent/child Tree). The context menu offers normal and Advanced attach/TTD recording flows; Advanced attach controls child debugging and the initial break, while Advanced TTD recording selects the trace path, optionally records children, and shows a copyable ttd.exe command. Advanced dump capture can open a newly captured dump directly for debugging.
• Hyper-V Explorer — an activity-bar view with lightweight create/manage support for local Hyper-V VMs (start/stop, checkpoints, ISO media, and Start Kernel Debugging over KDNET or a serial pipe) for kernel-debugging workflows, plus AI tools that let Copilot drive and manage those VMs. See Hyper-V VM management and Copilot integration for details.
• GitHub Copilot integration — Language Model Tools and the Agentic Troubleshooter (WinDbg) chat agent let AI investigate various debugging scenarios on your behalf (see below).
• Module view — a list of loaded modules for the active session with various information. You can load symbols for a module, view its source repository by resolving its Source Link / srcsrv data.
• Memory window — hex + text dump of virtual memory (WinDbg: Show Memory command, or the command window's Window shortcuts menu). Select a byte range and enter a struct/class name in the Type field to preview that type at the selection start address (similar to dt Type addr), or leave it blank to inspect the managed .NET object at that address.
• Changed-value highlighting — after each execution step (t, g, t-, g-, !tt, etc.), the Registers view and Memory windows highlight the values that changed since the previous break in a distinct color, mirroring WinDbg's red change indicator. Memory windows track only the region currently in view (plus a few pages of scroll margin). Toggle with the windbg.highlightChangedValues setting.
• GC Heap view — an educational visualization of the managed .NET heap for the active session (WinDbg: Show GC Heap command), including multiple layout modes (Composition, Generations, and physical Segment/Region views) to help explain GC behavior and memory layout.
• Timeline view (TTD sessions only) — a visual timeline of execution history for Time Travel Debugging traces, with exceptions, function calls, memory accesses, and GCs annotated. Click an event to jump to that point in time.
• TTD register scan — search a Time Travel Debugging trace (*.run) for the points in execution history where a CPU register matched a condition (for example fpcw <> 0x27F). Because a Time Travel trace keeps the whole history, this finds a control/flags register (fpcw, mxcsr, fpcr, eflags, …) that was transiently changed and later restored — a value a single crash dump cannot show. Exposed to GitHub Copilot as the read-only windbg_ttd_scan_register tool.

GitHub Copilot integration

The extension registers Language Model Tools so GitHub Copilot can drive analysis of an open session or start a new one.

Copilot can start a session in several ways: opening a .dmp dump or .run trace by path, attaching to a running process by PID, or launching a new process from the full path to its executable. To find a PID from a process name it can also list the machine's running processes (with details such as user, architecture, and command line) without opening a session first. Because attaching to or launching a live process runs/suspends real code, those tools ask for confirmation and are blocked unless windbg.ai.allowLiveCommandExecution is enabled (the same opt-in that guards live command execution).

The run-command tools are split by command risk (read-only vs side-effecting) × target category (postmortem / live user-mode / live kernel-mode), so you can grant VS Code's per-tool auto-approval to exactly the combinations you trust (for example, auto-approve read-only commands on dumps while still reviewing side-effecting or live commands). Each command is re-checked by the extension (not trusted from the model) and a mismatched call is rejected with the name of the correct tool to use. For safety, the live run-command tools block live attach/launch sessions by default — enable windbg.ai.allowLiveCommandExecution to allow AI-issued commands against live targets.

Copilot can also observe and operate a local Hyper-V VM's console directly (no Remote Desktop or VMConnect session): it can list your VMs, capture the guest screen as an image, and — for VMs you have explicitly allowed — move/click the mouse, type text, create or manage the VM, and run a hands-off unattended install using a password you have saved (never revealed to Copilot). By default every VM is read-only to Copilot; you grant access per VM from the Hyper-V Explorer. See Hyper-V VM management and Copilot integration for the full behavior and safeguards.

The command risk classification is driven by customizable rules: the bundled defaults ship as JSONC (.jsonc) in the extension's rules/ folder and cover the general WinDbg command set and the SOS extension. You can override the risk of any command — or add rules for new commands (for example, your own debugger extension's commands) — by dropping .jsonc (or .json) files into a command-rules/ directory — globally (in the extension's local folder, %LOCALAPPDATA%\vscode-windbg\command-rules, alongside the WinDbg/TTD binaries the extension manages) or per workspace (<workspace>/.windbg/command-rules/, which takes precedence). Each rule maps a command pattern (an exact name, a trailing-* prefix, or * for the catch-all) to either a single risk (readonly / sideeffect / prohibit, applied to every target) or a per-category object, for example:

{
  "rules": {
    "!myext.scan": "readonly",
    "bp": { "postmortem": "readonly", "liveUser": "sideeffect", "liveKernel": "sideeffect" }
  }
}

Three risk levels are supported: readonly (safe to auto-approve), sideeffect (runs behind confirmation), and prohibit (never run — every run-command tool refuses it without executing anything). .shell is prohibited by default because it runs arbitrary OS commands; override it to sideeffect in a command-rules/ file to re-enable it behind confirmation. The default risk for any command not matched by a rule is the catch-all *, which the bundled default.jsonc sets to sideeffect; set "*" in an override file to change that default (for example to prohibit to block everything unknown, or readonly to auto-approve it).

Agentic Troubleshooter (WinDbg) chat agent

Open Copilot Chat, pick the Agentic Troubleshooter (WinDbg) agent from the agents picker, and describe what you want investigated. Instead of running a fixed list of commands, the agent hands the language model a rigorous investigation methodology and the windbg_* tools, and lets it branch and decide as a human analyst would across the common scenarios:

By default the agent works on the focused session; you can also point it at a specific dump/trace like "analyze the hang in C:\path\to\dump.dmp". Every investigation follows a disciplined, evidence-based methodology — facts vs. inference are labeled, each step is logged as command → why → output → conclusion, competing hypotheses are tested, read-only commands are preferred, and every run ends with a structured Conclusion / Evidence / Next actions summary.

Requirements

• Windows 11 version 23H2 and later
• Internet access for downloading the extension-local WinDbg engine, TTD recorder, and Sysinternals ProcDump. Also required for symbol resolution and source retrieval when debugging.

Privacy / Data Collection

• This extension does not collect usage analytics or telemetry on its own.
• It does not automatically upload dump or trace contents.
• If you use GitHub Copilot features with this extension, prompts and tool inputs/outputs are handled by VS Code and GitHub Copilot under their own privacy policies.

Logging

Extension and debugging-host logs are written to the WinDbg Output channel. Host file logs are also persisted under the debugger home logs directory (for example, %LOCALAPPDATA%\vscode-windbg\windbg-home\logs).

License

WinDbg Integration is distributed in binary form under the terms in LICENSE. Reverse engineering, modification, and redistribution require explicit permission from the author. Third-party components remain subject to their own license terms; the packaged LICENSE appends those terms, and the same generated list is available in THIRD_PARTY_NOTICES.txt.

Third-Party Notices

This extension uses third-party software in two distinct ways: some dependencies are bundled with the extension, while others are installed separately at runtime.

If you notice an omission or error in this list, please open an issue so that it can be corrected.

Bundled dependencies

The extension includes software obtained from the following NuGet packages:

• Microsoft.Debugging.Platform.DbgX
• Microsoft.Debugging.Platform.SymSrv

For the complete, automatically generated list of every bundled package (including the .NET runtime) and its license, see THIRD_PARTY_NOTICES.txt.

Installed separately at runtime

This extension depends on the following software, which is not bundled in the VSIX package. The extension assists users in downloading and installing these components when required. Each component remains subject to its own license terms.

• WinDbg: for full WinDbg engine support
• Time Travel Debugging - TTD.exe command line utility: for recording Time Travel Debugging traces
• ProcDump: for capturing crash dumps of live processes
• LLDB (part of the LLVM Project, Apache-2.0 with LLVM exceptions) together with the dotnet-sos diagnostics plugin: for managed (.NET) analysis of Linux ELF core dumps. These are not bundled in the VSIX; they are installed by Docker into an on-demand image built from the Microsoft .NET SDK image (which requires Docker, provided by you). Each remains subject to its own license terms.