Introduction

Bugsaur is a graphical debugger that runs on its own. It talks to debug adapters over the Debug Adapter Protocol, so it is not tied to one language, and it does not need an editor to work.

The idea in one line

The debugger owns debugging. The editor stays a source frontend.

In most setups the editor owns the debug session: it starts the adapter, holds the state, and draws the UI. Close the editor and the session dies with it. Bugsaur inverts that. Bugsaur is the only DAP client and the authoritative owner of session state. Neovim — when you use it — edits code, navigates sources and manages breakpoint UX, and nothing else.

Neovim — source frontend	Bugsaur core	Bugsaur GUI
Code editing	DAP session	Variables, Watches
Source navigation	Execution control	Threads, Call stack
Breakpoint UX	Runtime state	Evaluate, Logs

That split has practical consequences:

• The debugger starts and works with no editor at all — bugsaur gui from a terminal is a first-class way to use it.
• Breakpoints outlive the editor. They live in .bugsaur/breakpoints.json, so restarting Neovim does not lose them.
• One configuration serves both. .bugsaur/config.toml is read by the debugger, so bugsaur from a terminal and :DebugStart from Neovim see exactly the same setup.

What you need

Platform	macOS or Linux
Rust	the toolchain pinned in rust-toolchain.toml (1.92), to build from source
An adapter	at least one: codelldb, dlv, debugpy, or the built-in php
Neovim	optional — only for the source frontend

Where to go from here

1. Installation — install Bugsaur and get an adapter on PATH.
2. Quick Start — the shortest path from a project to a window.
3. Your First Debug Session — the full walk-through, ending on a breakpoint.

If you want to understand the machinery rather than use it — IPC, session lifecycle, adapter ownership — that lives in Development → Architecture, deliberately out of the way of getting started.