windbg-tool

windbg-tool is a Windows-first command-line tool and MCP server for WinDbg-oriented automation. It is centered on Time Travel Debugging (TTD) replay, but it also covers broader WinDbg workflows such as daemon-backed CLI automation, symbol and source diagnostics, disassembly and memory inspection helpers, DbgEng process-server support, remote debugging command generation, and WinDbg install/update/launch.

windbg-tool is the product name. You will still see windbg-ttd in MCP server configuration and ttd_* tool names because the replay/MCP surface grew out of the original TTD-focused implementation.

What you can do

• Run a stdio MCP server for TTD replay workflows.
• Keep long-lived replay sessions in a local daemon and drive them from the CLI.
• Open traces, create cursors, seek positions, inspect threads/modules/registers/memory, and replay to watchpoints.
• Use higher-level helpers such as discover, recipes, context snapshot, symbols diagnose, disasm, stack backtrace, and memory chase.
• Start a DbgEng process server and install, update, or launch WinDbg.

Repository layout

Build from source

For a local build with the native replay pieces available:

cargo xtask doctor
cargo xtask deps
cargo xtask native-build
cargo build -p windbg-tool

The built executable is:

target\debug\windbg-tool.exe

Release ZIP artifacts are built by the Windows packaging workflow. The local equivalent uses cargo xtask deps --arch <amd64|arm64>, cargo xtask native-build --arch <amd64|arm64> --static-crt, a release build for the matching MSVC Rust target, and cargo xtask package --profile release.

For deeper setup, test commands, runtime details, and workspace notes, see the development guide.

CLI quick start

Some commands work without loading a trace or starting the daemon:

target\debug\windbg-tool.exe discover
target\debug\windbg-tool.exe recipes
target\debug\windbg-tool.exe tools

For trace-driven work, the common flow is:

target\debug\windbg-tool.exe daemon ensure
target\debug\windbg-tool.exe open C:\path\to\trace.run --binary-path C:\path\to\binary.exe
target\debug\windbg-tool.exe sessions
target\debug\windbg-tool.exe context snapshot --session 1 --cursor 1
target\debug\windbg-tool.exe disasm --session 1 --cursor 1

open is the best starting command for the CLI because it loads the trace, creates a cursor, and returns both session_id and cursor_id. Most replay commands then use --session and --cursor (or the short forms -s and -c).

Representative command areas:

• Discovery: discover, recipes, tools, schema
• Session and replay: open, load, sessions, info, position set, step, replay to
• Analysis: symbols diagnose, disasm, memory dump, memory strings, memory chase, stack recover, stack backtrace
• Platform helpers: remote explain, dbgeng server, live launch, dump create, dump inspect, windbg status

For a fuller CLI walkthrough, output-shaping flags, and command map, see the CLI guide.

MCP quick start

Run the MCP server over stdio:

target\debug\windbg-tool.exe mcp

Example MCP client configuration:

{
  "servers": {
    "windbg-ttd": {
      "command": "D:\\dev\\windbg-tool\\target\\debug\\windbg-tool.exe",
      "args": ["mcp"]
    }
  }
}

The usual MCP flow is:

1. ttd_load_trace
2. ttd_cursor_create
3. ttd_trace_info, ttd_registers, ttd_read_memory, ttd_memory_watchpoint, or related tools

Helpful starting prompt:

Use the windbg-ttd server to load C:\path\to\trace.run with the matching binary path, create a cursor, summarize the trace, and show the current compact register state.

For configuration details, session/cursor concepts, symbol settings, and example tool calls/prompts, see the MCP guide.

More docs

• CLI guide - daemon model, CLI workflows, and command groups
• MCP guide - MCP configuration, core tool flow, and example prompts
• Development guide - build, native dependencies, symbols, tests, and repository hygiene
• Architecture notes - architecture and layering details

Trace privacy

TTD traces can contain process memory, file paths, registry data, and other sensitive machine state. Treat .run, .idx, and related replay artifacts as sensitive local files.