Time Travel Debug for C/C++

The Time Travel Debug for C/C++ extension from Undo allows you to fix your bugs faster, by accelerating their identification and discovery of their root cause.

The extension adds support for reverse debugging C/C++ applications running on Linux with UDB, Undo's time-travel debugger.

Requires an existing copy of UDB 7.0 or later, or a free trial version (which the extension can download and install automatically). The new experimental undo debug type requires UDB 10.0 or later.

Animation

Time-travel through your code’s execution flow with full visibility and code-level observability into the state of your code at each step leading up to an error. Live debug and conduct effective root cause analysis without needing to predict ahead of time what to log, and avoiding disruptive redeployments.

With UDB you can:

View and analyze actual code execution behaviour.
Go back to any point in the debugger’s execution history.
Step backward and forward using individual instructions, source lines, function calls etc.
Regenerate the complete state of the program being debugged at any point in its execution; including information that is normally destroyed during execution.

Watch how to get started with Time Travel Debug for C/C++ with this YouTube video. Or follow the instructions below.

Features

Time Travel / Reverse debugging.
Launch, Attach, or Replay an Undo recording made by UDB or LiveRecorder.
Continue and Reverse Continue, stopping at Breakpoints/Conditional Breakpoints/Watchpoints.
Step In/Out/Over, and Reverse Step In/Out/Over.
Undo last navigation.
Visually navigate and zoom through the execution flow in the Timeline.
Jump to a Bookmark at any point in your program’s execution history.
Jump to any point in your program’s execution history where it printed a timestamp to a log.
Jump to the last or next point in your program’s execution history where the value of an expression changed.
Inspect global and local variable values at any point in your program’s execution history.
Evaluate expressions and call functions in the Debug Console at any point in your program’s execution history.
Query UDB recordings directly from VS Code’s Copilot chat panel using Undo AI via MCP.

Debug types

The extension provides two debug types:

cppdbg (default)

Debugs your program via the Microsoft C/C++ extension, which drives UDB using the GDB/MI protocol. This has been the extension's architecture since it was first released. All standard cppdbg configuration properties are supported in addition to the UDB-specific properties listed in the property reference.
undo (experimental, new in extension version 3.0.0)

Drives UDB directly using the Debug Adapter Protocol (DAP), without using the Microsoft C/C++ extension. Requires UDB 10.0 or later.

The undo debug type is experimental. It is not yet the default, but we encourage you to try it and let us know what you think by contacting Undo Support. It brings several improvements over cppdbg:
- The Pause button in the debug toolbar works correctly during both forward and reverse execution.
- Breakpoints set in the UDB command-line terminal appear in the VS Code breakpoints pane.
- If UDB fails to start, the debugger errors and output are captured and presented rather than failing silently.
- Improved stability during time-travel operations, addressing previously unfixable edge-cases.
To convert an existing cppdbg launch configuration to undo, run UDB: Migrate legacy UDB "cppdbg" launch configurations to use the experimental "undo" debug type from the Command Palette (Ctrl-Shift-P), or see the migration guide.

Getting started

Open your project workspace.

If you’re debugging remotely via the Remote - Containers, Remote - SSH or Remote - WSL extensions, install this extension in the Visual Studio Code window that is attached to the remote system.

From the main menu choose Run → Add Configuration and pick one of the extension's configuration templates:

C++ (UDB) creates a default set of cppdbg launch configurations.
Undo creates a undo launch configuration, using the experimental DAP-based debug type.

You can also add a single configuration to an existing set by picking C/C++: (UDB) Launch, C/C++: (UDB) Attach, or C/C++: (UDB) Replay an Undo recording for the cppdbg debug type. There are corresponding C/C++: (Undo) … entries for the undo debug type.

In either case, VS Code opens the launch.json file in the editor.

Specify the path to the executable that you’d like to debug as the program.
If UDB is not present on your path (i.e. the directory containing the udb executable is not listed in the $PATH environment variable) specify the path to the udb executable as miDebuggerPath (for the cppdbg debug type) or debuggerPath (for the undo debug type). If you don’t have UDB you can download a free trial.

See the property reference below for the full set of options.

Operation

To start debugging:

Select the Run icon in the Activity Bar on the side of VS Code.
Choose the launch configuration from the menu at the top left if it isn’t already active.
From the main menu choose Run → Start debugging.

Once you’ve started a time-travel debugging session you can use the buttons in the debugging control panel to navigate forwards and backwards through your program’s execution history:

Toolbar

Blue navigation buttons

The familiar Continue, Step Over, Step Into and Step Out buttons behave as you would expect, and you also have available Reverse Continue, Reverse Step Over, Reverse Step Into and Reverse Step Out buttons that perform the corresponding operations in reverse.
Green “Go To” buttons

Use the Go To Start and Go To End buttons to go to the start or end of your program’s execution history. Use the Go To Bookmark button to go a previously placed bookmark. Use the Go To Time button to go to a time in execution history, or a wall-clock time, for example a timestamp copied from a log file. Use the Last Changed button to go to the last time the value of an expression was modified.
Green “Undo” and “Redo” buttons

The Undo button undoes the operation of the last navigation or Go To button. Press this again to undo the previous operation, back to the start of your debugging session. The Redo button reverses the effect of the Undo button.
Yellow/Orange “Set Bookmark” button

The Set Bookmark button creates a bookmark at the current time in execution history. You can later return to this moment in time using the Go To Bookmark button, or by clicking on the bookmark in the Timeline. If you’re debugging an Undo recording, bookmarks are persisted across debugging sessions on the same machine.

The TIMELINE section of the Run view shows the current position in the program’s execution history and the positions of bookmarks that you’ve placed with the “Set Bookmark” button.

You can also use the timeline to navigate:

Click on “start” and “end” to go to the start or end of your program’s execution history.
Click on a bookmark to return to that moment in time.

Use the ⊕ and ⊖ buttons, Ctrl and mouse wheel, or a zoom gesture to zoom in on a particular period of execution.

Log Jump

In the TERMINAL panel, and in open log files, timestamps that you can jump to are underlined. Control-click on a timestamp to jump to the corresponding time in recorded history. To configure which files are treated as log files containing wall-clock times, update the "udb.logFilePattern" setting in your workspace or user settings. This field is a glob pattern; the default pattern is "**/*.log".

To configure which log entries are recognized as containing bbcounts, update the "udb.bbcountRegex" setting in your workspace or user settings. The setting must be a regular expression with one capturing group containing the bbcount. The default is "bbcount[=: ]+([0-9,]+)".

Undo AI with Copilot (MCP)

The extension can automatically configure VS Code's Copilot chat to use Undo's AI functionality via the Model Context Protocol (MCP), allowing Copilot to query UDB recordings directly from the chat panel. This requires VS Code 1.101.0 or later.

To enable this feature, open the Command Palette (Ctrl-Shift-P) and run UDB: Configure MCP Server Auto-Configuration, then choose Enable.

When enabled, the extension registers the best available MCP server:

udb --mcp (preferred) — requires UDB 10.0.0 or later with AI features enabled.
explain-launcher (fallback) — requires UDB 9.0.0 or later.

The extension locates either executable on your $PATH by default. If you need to use a custom path, use the UDB: Set UDB MCP Launcher Path or UDB: Set Explain Launcher Path commands in the Command Palette.

Launch configurations

Each of the two debug types provides three kinds of launch configuration:

Launch

Use one of these to start time-travel debugging your program with UDB.
Attach

Use this to attach to a running process and start time-travel debugging with UDB.
Replay an Undo recording

Use this to load and replay a recording made by UDB or LiveRecorder.

For the cppdbg debug type, the udb property selects between live debugging and replay ("live" versus "replay") and marks a configuration as UDB-driven. For the undo debug type, this is the mode property.

You can edit these configuration entries to customize UDB’s behaviour. Common configuration options are described in the property reference below.

For example, to increase the size of UDB’s event log to 2GB and set the number of snapshots, use the udbConfiguration property:

"udbConfiguration": {
    "UNDO_event_log_max": "2G",
    "UNDO_snapshots": 20
}

You can also configure UDB by exporting environment variables in a wrapper script and supplying the path to the wrapper script as miDebuggerPath (for cppdbg) or debuggerPath (for undo). For example, using a POSIX-compatible shell:

#!/bin/sh

# Increase the size of UDB's event log to 2GB - see https://docs.undo.io/EventLog.html
export UNDO_event_log_max=2G

exec udb "$@"

For csh the equivalent command is exec udb $*:q.

Property reference

The following table lists commonly used launch configuration properties for both debug types. Properties marked cppdbg only or undo only are only recognized by that debug type; values supplied to the wrong debug type are ignored. Standard debugger properties such as type, request, and name are omitted.

The cppdbg debug type also accepts every other property supported by the Microsoft C/C++ extension — for example, externalConsole, logging, sourceFileMap, symbolSearchPath, additionalSOLibSearchPath, hardwareBreakpoints, and OS-specific overrides such as linux. See the Visual Studio Code C/C++ launch reference for the complete list.

Property	Type	Applies to	Description
`program`	string	both	Path to the executable to debug. Only used for live debugging (`udb: "live"` for `cppdbg`, `mode: "live"` for `undo`); use `recordingFile` for replay. Required when live-launching a program.
`args`	string array	both	Command-line arguments to pass to the debugged program.
`cwd`	string	both	Working directory for the debug session. Defaults to `${workspaceFolder}`.
`environment`	array of `{"name": ..., "value": ...}` objects	both	Environment variables to add to the debugged program's environment. These variables are applied only to the program, not to UDB itself — to configure UDB, use `udbConfiguration` or a wrapper script.
`stopAtEntry`	boolean	both	If `true`, stop at `main()` when the program starts. Only valid for live debugging (`udb: "live"` for `cppdbg`, `mode: "live"` for `undo`); ignored otherwise. Defaults to `false`.
`processId`	string	both, `attach` only	The process ID to attach to. Set to `${command:pickProcess}` to be prompted at launch time.
`recordingFile`	string	both	Path to the Undo recording file to replay. Used when `udb` (`cppdbg`) or `mode` (`undo`) is `"replay"`.
`udb`	string	`cppdbg` only	`"live"` to launch or attach with UDB, or `"replay"` to load and replay an Undo recording. This property must be present to mark the configuration as UDB-driven.
`mode`	string	`undo` only	`"live"` to launch or attach with UDB, or `"replay"` to load and replay an Undo recording.
`MIMode`	string	`cppdbg` only	Must be `"gdb"` for UDB.
`miDebuggerPath`	string	`cppdbg` only	Path to the `udb` executable. Leave as `"udb"` if it is on `$PATH`. See the `cppdbg` reference.
`miDebuggerArgs`	string	`cppdbg` only	Additional command-line arguments to pass to UDB, as a single string (e.g. `"--max-event-log-size 2G"`). See the `cppdbg` reference.
`debuggerPath`	string	`undo` only	Path to the `udb` executable. If not set, `udb` is searched for in `$PATH`.
`debuggerArgs`	string array	`undo` only	Additional command-line arguments to pass to UDB, one per array element. Flags that take values must be split into two elements — for example, `["--max-event-log-size", "2G"]`.
`setupCommands`	array of `{"text": ..., "description"?: ..., "ignoreFailures"?: ...}` objects	both	Commands to run in the debugger before the debug session starts. Entries must be MI commands for `cppdbg` (e.g. `-enable-pretty-printing`), or UDB commands for `undo` (e.g. `set print pretty on`). If `ignoreFailures` is `true`, failures do not stop the debug session from starting.
`postRemoteConnectCommands`	array of `{"text": ..., "description"?: ..., "ignoreFailures"?: ...}` objects	both	Commands to run in the debugger after connecting to a remote target. As with `setupCommands`, entries must be MI commands for `cppdbg` and UDB commands for `undo`.
`dapLogFilePath`	string	`undo` only	Path to a file for Debug Adapter Protocol log output (`set debug dap-log-file`).
`heartbeatTimeout`	number	both	Seconds UDB waits without a heartbeat from the extension before exiting. Ensures UDB exits if the VS Code session is disconnected (for example, on window close or loss of connection to a remote host). The extension sends heartbeats at four times this rate while the debugged program is not running. Defaults to 12 hours; minimum is 5 seconds.
`timezone`	string	both	Default timezone for wall-clock times in the Go To Time dialog, as an IANA timezone name (e.g. `"Asia/Tokyo"`). Overrides the `udb.timezone` workspace or user setting.
`udbConfiguration`	object mapping `UNDO_*` variable names to values	both	UDB configuration settings. Any documented environment variable starting `UNDO_` can be set here — see the Undo docs for the full list.
`udbCommandLine`	boolean	both	If `true`, open a UDB command-line terminal when a debug session starts. Defaults to `true` for `launch` and `false` for `attach`.
`udbMaxChildVariables`	number	both	Maximum number of child variables to fetch when expanding a variable in the Variables window. Defaults to `1000`.
`enableAutoQuit`	boolean	both	If `true`, UDB quits automatically after a period of inactivity (the period is determined by the license in use). Defaults to `true`.

Limitations

Multiple debug sessions

The extension doesn't support running a UDB debug session at the same time as another debug session, in the same instance of Visual Studio Code.

You can open multiple Visual Studio Code instances of the same workspace using File -> Duplicate Workspace, or by selecting Workspaces: Duplicate as Workspace in New Window in the Command Palette (Ctrl-Shift-P). You can then start a separate debug session in each window.

Instruction level reverse stepping

Instruction-level reverse stepping is not supported from the debug toolbar. Reverse step commands are always executed at source-line granularity, regardless of whether the Disassembly view is active. Use the debug terminal to issue reverse-stepi or reverse-nexti commands if required.

`undo` debug type

The integrated terminal currently does not display command output until the command completes, so long-running commands may appear to hang. A progress indicator appears in VS Code while a long-running command is executing however.

In the integrated terminal, subcommands are not autocompleted — for example, ugo time, ugo bookmark, etc. do not get autocompleted when tab-autocompleting ugo.

UDB

Refer to the Undo website for limitations on the Undo Engine and UDB.

Support

To submit a support request, please send an email to support@undo.io and include "VS Code" in the message subject.

Acknowledgements

Contains artwork derived from Visual Studio Code - Codicons, licensed under the Creative Commons Attribution 4.0 International Public License.

Time Travel Debug for C/C++

Undo

Time Travel Debug for C/C++

Features

Debug types

Getting started

Operation

Log Jump

Undo AI with Copilot (MCP)

Launch configurations

Property reference

Limitations

Multiple debug sessions

Instruction level reverse stepping

undo debug type

UDB

Support

Acknowledgements

`undo` debug type