MCU-Debug: The Next-Generation Embedded Debugger for VS Code

There is no release version yet; every build published so far is a pre-release. Expect rough edges, expect things to change, and please report what breaks — that feedback is the reason for shipping this early.

To install: in VS Code, use the dropdown arrow beside the Install button and choose Install Pre-Release Version. Plain Install assumes a release version exists, so it tells you there is none before offering you the pre-release. Nothing is wrong when that happens — the message is about the release channel, not a broken listing — but the dropdown skips it.

Odd minor versions are pre-release (0.1.x), even ones are release (0.2.x).

mcu-debug — Cortex-Debug, rethought for modern embedded by the same author

If you’ve been using Cortex-Debug, this will feel familiar — but it’s not just an update. mcu-debug is a ground-up rebuild to support how embedded development actually works today. MCU-Debug bridges the gap between your local hardware probes and your modern development environments.

👉 View a 3-Minute Interactive Intro & Architecture Deck

👉 Full documentation for MCU Debug Family

• Truly vendor-neutral Built to be use whatever MCU (not just ARM), probe, GDB server, or silicon you want. GDB Server is the only requirement

• Works where others break Native support for WSL, containers, and remote setups—no more fragile hacks just to get a debugger running.

• The only VSCode debugger that makes WSL, containers, and local debugging behave the same One config. works everywhere your code and hardware live. All it takes is "hostconfig": true in your launch.json and specify where your gdb-server (OpenOCD, etc.) lives if not in your $PATH. The gdb-server is the boundary, everything else is handled.

• Your launch.json is now scriptable Run the same debug configuration in VS Code or the command line. Automate it. Put it in CI. Reproduce it anywhere.

• Finally automation-friendly Enables hardware-in-the-loop testing, regression runs, and repeatable debug sessions—things that were painful or impractical before.

• Built with AI in mind A consistent, machine-readable debug surface that lets tools (and AI) actually understand and assist with your sessions.

Cortex-Debug isn’t going anywhere—it’s stable and proven. But it is feature frozen and if you’ve ever hit limits with:

• Remote development
• Lack of automation, AI, CLI, CI friendly

then this is the upgrade path. mcu-debug isn’t just easier—it unlocks workflows that weren’t really possible before.

For full installation guides, advanced configurations, and architecture details, visit the official documentation at mcu-debug.github.io/mcu-debug/.

If you are currently using cortex-debug, you're already ready to use MCU-Debug. It maintains full backward compatibility with all your existing launch.json configurations under the "cortex-debug" type, while introducing game-changing features for modern development. Integration with AI agents and remote development was the special focus

• Standard Embedded Debug Features: All the common features you would expect for of an embedded C/C++ development environment. With support for Rust data structures as well.
• Remote Development: First class support for remote development with WSL2, Docker, and ssh. Suppoert for Apple Container coming
• Zero-Friction Remote Debugging: Develop inside WSL2, Dev Containers, or remote SSH servers while keeping your debug probe physically connected to your local machine.
• Standalone CLI & TUI Mode: Mux your debug console, serial port, and RTT logs into a single Rust-powered terminal dashboard (mcu-debug debug), or run headless for CI/CD and AI agent integrations. See CLI Exampe
• MCU-Debug in VSCode Panel CLI mode:: Launch CLI debug session inside VSCode
• Workspace-Scoped UARTs: Keep serial ports open during board resets and IDE restarts, capturing early boot logs in a local ring buffer.
• Dual-Mode RTT: Bypasses sluggish server-level TCP polling with target memory direct reads at up to 40 Hz.
• Real-time Telemetry: Subscribe to named variables and get streaming updates pushed directly to the UI, enabling live telemetry without manual polling loops.
• Beautiful UI: A modern, VS Code integrated UI with RTT, SWO, and serial (UART) log visualization.
• Performace: Much faster startup times, thanks to Rust doing the heavy lifting
• Rust Friendly: Support for defmt-print RTT and understanding Rust data structures in the debugger

In modern development, your compiler and workspace often live inside WSL, a Dev Container, or a remote lab server, while your hardware probe is plugged into your laptop. MCU-Debug solves this with a lightweight Probe Agent (mdbg) running locally that multiplexes GDB RSP, RTT, SWO, and serial ports over a single, secure SSH or local TCP tunnel. No complex usbipd setup or firewall configuration needed.

Step out of the IDE entirely. With the mcu-debug command-line interface:

• Launch debug sessions from your terminal with a rich ratatui-based TUI, using your existing launch.json configurations.
• Use your existing launch.json to launch CLI tools
• Attach to ongoing debug sessions from external scripts via a socket
• Run in headless mode to expose clean, tagged multiplexed streams to CI/CD pipelines or AI assistants.
• Autonomous Debugging: AI agents can use the CLI to debug MCU targets using familiar gdb commands and monitoring serial/RTT channels. With or without a human in the loop to deal with the physical world
• Use the CLI in a terminal or inside a VS Code panel
• Following is a TUI example - non TUI (Terminal UI) and VSCOde panels have similar views

• Standard Mode: Connects to standard TCP ports exposed by your GDB server.
• Direct Memory Mode: Reads the RTT control block directly from MCU target memory via GDB at high speed. Supports up to 16 bidirectional channels and custom pre-decoders (e.g. defmt-print for Rust developers).

No more missing early boot diagnostic prints:

• UART logs are workspace-scoped and survive debug session resets.
• A built-in ring buffer captures firmware output before your console tab is even opened.
• Tunnel remote serial ports from your lab server to your local machine using the Funnel Protocol.

Subscribe to named variables and get streaming updates pushed directly to the UI, enabling live telemetry and graphing without manual polling loops. (Real-time graphing is coming soon).

Support for debugging multiple cores on the same target. It can also support debugging multiple targets at the same time. You can control the startup sequence and decide how cores are started in an event based manner. They are done using a chaining launch/attach configurations in a tree like fashion.

To keep the core debugger lightweight and modular, we have factored out several key visualization components into standalone companion extensions. Because they leverage standard Debug Adapter Protocol (DAP) memory and variable APIs, they are fully decoupled and can be used with any DAP-compatible debugger (such as cppdbg or cspy), as well as with MCU-Debug:

• Peripheral Viewer: An interactive SVD (System View Description) viewer to inspect microcontroller peripheral registers during a debug session.
• RTOS Views: A popular, community-driven real-time monitor for RTOS tasks, queues, semaphores, and kernel states. Backed by a active contributor base (including ARM), this extension features a framework supporting a wide variety of RTOSes.
• MemoryView: A high-performance memory inspector for raw hex dumps and direct memory reads/writes.

MCU-Debug is vendor-agnostic and includes built-in configurations for:

• Segger J-Link
• OpenOCD
• probe-rs Experimental
• pyOCD
• ST-Link & ST-Util
• PE Micro
• Black Magic Probe (BMP)
• QEMU (Emulation)
• External/Custom GDB Servers

Install MCU-Debug from the VS Code Marketplace or Open VSX.

Use your existing cortex-debug configurations. For example:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug STM32 (MCU-Debug)",
      "type": "mcu-debug", // Or "cortex-debug" for drop-in compatibility
      "request": "launch",
      "servertype": "openocd",
      "executable": "./build/firmware.elf",
      "device": "STM32F103C8",
      "serialConfig": {   // New in "mcu-debug", ignored by "cortex-debug"
        "enabled": true,
        "ports": [
            {
                "match": "stlink",    // Match a serial port with 'stlink' in the description
                "baud_rate": 115200
            }
        ]        
      },
      "configFiles": [
        "interface/stlink.cfg",
        "target/stm32f1x.cfg"
      ]
    }
  ]
}

To use remote debugging, simply define a hostConfig inside your launch configuration:

"hostConfig": true // Automatically resolves WSL or Dev Container namespaces

THe above is equivalent to the following

"hostConfig": {
  "enabled": true,
  "type": "auto" // Automatically resolves WSL or Dev Container namespaces
}

• Documentation: mcu-debug.github.io/mcu-debug/
• Source Code: github.com/mcu-debug/mcu-debug
• Bug Reports & Feature Requests: github.com/mcu-debug/mcu-debug/issues

Developed and maintained by Haneef Mohammed. Licensed under MIT and Apache-2.0.