winget install --id=guzmandrade-dev.simple-dap-gui -e simple-dap-gui is a lightweight, cross-platform desktop debugger for DAP (Debug Adapter Protocol) targets such as Xdebug, Python, and Node.js.
A standalone DAP (Debug Adapter Protocol) client GUI application built with Electron, React, TypeScript, and PrismJS. Primarily designed for PHP debugging with Xdebug.
vscode-php-debug adapter${workspaceFolder}, ${userHome}, ${workspaceFolderBasename}, and ${pathSeparator} resolution in path mappings.vscode/launch.jsonClick the gutter to toggle breakpoints. The current execution line is highlighted in yellow.
The same view in light mode.
Monitor custom expressions as you step through code.
Install, uninstall, and manage DAP adapters from the built-in catalog.
dap-gui/
├── electron/ # Electron main process
│ ├── main.ts # Entry point
│ └── preload.ts # Preload script for IPC
├── src/
│ ├── dap/ # DAP protocol implementation
│ │ ├── client.ts # DAP client with protocol parser
│ │ ├── session.ts # Debug session management
│ │ └── types.ts # TypeScript type definitions
│ ├── components/ # React components
│ │ ├── Editor/ # PrismJS code viewer
│ │ ├── FileExplorer/ # Workspace file tree with lazy loading
│ │ ├── Panels/ # Side panels (stack, variables, watch, breakpoints, settings, adapters)
│ │ ├── Toolbar/ # Debug controls
│ │ └── StatusBar/ # Status bar
│ ├── styles/ # Theme CSS (dark/light) with CSS custom properties
│ ├── stores/ # Zustand state stores
│ └── utils/ # Helper utilities
└── ...
Once published, install the app through your platform's package manager:
winget install guzmandrade-dev.simple-dap-guibrew install --cask simple-dap-guiflatpak install flathub com.guzmandrade.SimpleDapGui> Note: Installers are currently not code-signed. On Windows you may see a Microsoft Defender SmartScreen prompt the first time you run the app; click More info → Run anyway to proceed.
Because the app is not currently code-signed or notarized, macOS Gatekeeper may show an error such as “simple-dap-gui is damaged and can’t be opened” after downloading a release.
The app is not actually damaged; macOS has added a quarantine flag to the downloaded file and is refusing to run unsigned software.
To run it, use one of the following methods:
Option 1 — Remove the quarantine flag (recommended)
Open Terminal and run:
xattr -rd com.apple.quarantine /Applications/simple-dap-gui.app
Then launch the app normally.
Option 2 — Open via System Settings
simple-dap-gui message.The app accepts a project folder as its first positional argument:
/Applications/simple-dap-gui.app/Contents/MacOS/simple-dap-gui /path/to/your/project
To make simple-dap-gui available as a regular shell command, create a symlink:
ln -s /Applications/simple-dap-gui.app/Contents/MacOS/simple-dap-gui /usr/local/bin/simple-dap-gui
Then you can open projects with:
simple-dap-gui /path/to/your/project
> If you install the app somewhere other than /Applications, adjust the path in the symlink accordingly.
Releases are published automatically from GitHub Releases via:
.github/workflows/winget.yml.github/workflows/homebrew-cask.ymldistrib/flathub/com.guzmandrade.SimpleDapGui.yml (submit to flathub/flathub)# Install dependencies
npm install
# For PHP debugging, install the PHP debug adapter:
# Option 1: Download from GitHub releases
# https://github.com/xdebug/vscode-php-debug/releases
# Option 2: Clone and build
git clone https://github.com/xdebug/vscode-php-debug.git
cd vscode-php-debug
npm install
npm run build
# Copy out/ folder to your project
.vscode/ folder:{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
}
}
]
}
npm run dev
Select a configuration from the dropdown in the toolbar
Click Debug (or press F5) to start debugging
Set breakpoints by clicking in the gutter area
Toggle Theme between dark and light via the Settings panel
| Shortcut | Action |
|---|---|
| F5 | Start Debugging / Continue |
| Shift + F5 | Stop Debugging |
| F10 | Step Over |
| F11 | Step Into |
| Shift + F11 | Step Out |
| Toolbar | Disconnect (detach without killing the process) |
Commands: to the winget installer manifest so the portable package exposes simple-dap-gui on PATH after installation.Ctrl+P / Ctrl+Shift+F) with fuzzy file-name search powered by fuzzysort and fast content search powered by ripgrep, with a pure-JavaScript fallback when rg is not installed.ripgrep-js dependency: Replaced the buggy wrapper with a custom execFile-based implementation.Inspect local and global variables at the current stack frame. Expand arrays and objects to view their children.
Add custom expressions (e.g., $myVariable, $_SERVER['REQUEST_URI']) to monitor their values as you step through code. Watches are re-evaluated automatically on every stop.
Navigate between stack frames to inspect variables at different levels of execution. Click any frame to jump directly to its source file and line in the editor.
View and manage all breakpoints set across the workspace. Use the Stop On section to break on PHP notices, warnings, errors, exceptions, or everything. Enable Persistent Breakpoints in Settings to save them to .vscode/dap-gui.breakpoints.json and restore them on the next session.
Install, uninstall, and manage DAP adapters. The built-in catalog currently lists the PHP Debug adapter. You can also install any adapter from a .vsix file.
Configure your preferred editor in the Settings panel:
codezedvim{file}, {line})Use "Open Workspace in Editor" to open the current workspace root directly. External editor commands are resolved against your PATH (where on Windows, which on macOS/Linux) with a fallback to common install locations.
Click the → arrow in the editor header to collapse the editor panel. This gives the file explorer and debug panels more room. When collapsed:
The app supports dark and light themes via CSS custom properties mapped to Tailwind's semantic color tokens (bg-panel, text-accent, border-danger, etc.). Themes are persisted to localStorage and switch instantly across the UI and PrismJS code viewer.
Install or uninstall DAP adapters from the Adapters panel. The manager tracks installed adapters, their paths, and supported languages.
vscode-php-debug — primary and tested adapterFuture versions may expand first-class support to:
debugpyvscode-cpptoolsIn the meantime, any DAP-compatible adapter can be installed manually via the Install from .vsix button.
# Run in development mode with hot reload
npm run dev
# Build for production
npm run build
# Preview production build
npm run preview
The application supports path mappings for remote debugging. Configure them in your launch.json:
"pathMappings": {
"/server/path": "${workspaceFolder}/local/path",
"/wordpress": "${userHome}/Git/WordPress",
"/wordpress/wp-content/plugins/${workspaceFolderBasename}": "${workspaceFolder}"
}
The following variables are resolved in both the server and local sides of each mapping:
${workspaceFolder} — current workspace root${workspaceFolderBasename} — last segment of the workspace root${userHome} — user home directory${pathSeparator} — / on macOS/Linux, \\ on WindowsMappings are applied in order, so more specific prefixes should be listed before broader ones.
In addition to per-project .vscode/launch.json files, you can define launch configurations globally in Settings:
.vscode/launch.jsonWorkspace configurations override global ones by name.
By default, breakpoints are kept in memory only. To save them across sessions:
.vscode/dap-gui.breakpoints.json in your workspaceThe code viewer always loads the latest file content from disk when you open a file. If you edit a file in an external editor while it's already open, click the Reload button in the editor toolbar to refresh the content.
${workspaceFolder}, ${userHome}, ${workspaceFolderBasename}, and ${pathSeparator} are resolved against the opened workspace and system environment.MIT