gdb-dashboard: one .gdbinit file that draws the whole debugging state

A single init file that redraws itself at every stop

The project describes itself in one line: a standalone `.gdbinit` file written using the GDB Python API that enables a modular interface showing relevant information about the program being debugged. That phrasing is accurate about the architecture, which is the first thing worth understanding. There is no daemon, no extension to build, no server to launch. The whole thing is one text file that GDB's Python interpreter reads at startup, and it registers hooks so that the panel is repainted every time the inferior program stops.

The stated goal is reducing the number of GDB commands needed to inspect the status of a program, so the developer can focus on control flow. That is a design position rather than a feature list. Plain GDB gives you `info registers`, `bt`, `info threads`, `x/16i $pc`, `list`, and each of those writes to the terminal and pushes your prompt further down the scrollback. gdb-dashboard inverts that: you get the same information continuously laid out, and the commands become something you reach for only when the panels are not enough.

The repository is as minimal as the design. The tree is three entries, `.gdbinit`, `LICENSE` and `README.md`, and the licence is MIT. There is no package manifest, no test directory and no build configuration, because there is nothing to build. The project has 12,253 stars and 818 forks, and it is not archived, with the last push on 2026-07-17.

Installing means fetching one file from the repository

The quickstart is a single command. Rather than cloning anything, the README tells you to place the `.gdbinit` file in your home directory, which the wget invocation handles directly:

wget -P ~ https://github.com/cyrus-and/gdb-dashboard/raw/master/.gdbinit

That URL is worth reading carefully, because it points at the raw file on the default branch rather than at a release tarball. The consequence is that you are installing whatever is currently at the top of master, with no version marker and no way to pin it after the fact. For a configuration file that most people install once and leave alone, that is usually fine. If you care about reproducibility across a fleet of machines, you would want to save a copy of the file alongside your dotfiles repository instead.

Syntax highlighting is the one optional piece, and it comes from an external library rather than anything bundled here:

pip install pygments

Pygments is a well known pure Python highlighter, and installing it is what turns the assembly and source panels from plain text into something with colour. Nothing else is required. After that, you debug as you normally would and the dashboard appears automatically every time the inferior program stops, which is the behaviour the README promises.

Nothing is redefined, everything sits under one command

The README is explicit on one point that matters more than any single panel: no GDB command has been redefined. Instead, all the features are available via the main `dashboard` command, and `help dashboard` is the way to see it. This is the right call for a tool that lives inside someone else's debugging session. A redefinition would silently change the meaning of a command you already type out of decades of muscle memory, and on a tool used at work that is not an acceptable trade.

The consequence is that the whole interface is namespaced under a single subcommand with its own options, which is what the repository topics are pointing at when they list subcommands, ansi, terminal, tty, ansi and console. A configuration surface that all lives under one entry point is easy to script, easy to disable and easy to hand to another developer, and the `help dashboard` output is the reference you will actually use.

The topics also include gdb-command, gdb-commands and dashboard-styles, which tells you the visual layer is data rather than hardcoded drawing. Styles are named things you select and, if you want, edit, rather than a fixed colour scheme baked into the file. For anyone who has ever squinted at a default terminal colour scheme at 2am, having the palette be a matter of configuration rather than a matter of what the author picked is a real benefit.

Panels you can enable, disable and rearrange

Modular is the word the project uses, and it means two distinct things. The first is that the display is assembled from independent panels, each of which shows one category of state: registers and assembly, the current source location, the stack, memory, threads and so on. The second is that each panel can be turned on and off individually, so the layout matches the program rather than being one fixed arrangement for every task.

This is where the design pays off. Reverse engineering a binary and fixing a deadlock in a threaded server need almost nothing in common. The register and disassembly view matters enormously for the first and is noise for the second. A layout that adapts means the same file serves both, and the source listing panel can be sized to what you are reading rather than competing with nine other regions for vertical space.

What the panel set does not do is replace interaction. gdb-dashboard is a view, not an editor. You still type the actual GDB commands to change execution, and the dashboard redraws to reflect the new state. That separation is deliberate and it is why the tool coexists with pwndbg or GEF rather than competing with them, although if you already run one of those you may find the overlap in register and stack display makes the added layer more noise than value.

Rendering is ANSI in a terminal, not a graphical window

The visual output is built from ANSI escape sequences in the terminal that GDB is already running in. The topic list is candid about the medium with ansi, tty, terminal, console and visual. There is no X11 dependency, no window to position, and nothing to install beyond the file itself, which is exactly why the tool works over an SSH connection where a native GUI debugger would not launch at all.

The tradeoff is that the layout is a grid of terminal cells. It draws inside your existing scrollback, and it inherits whatever your terminal reports about width. Resize the window and the panels rewrap on the next stop. Terminals with limited colour support will show the layout correctly but with less distinction between panels, and the syntax highlighting from Pygments degrades the same way. If you are on a minimal terminal, or connecting through something that strips escape sequences, the raw GDB output underneath is still there and still correct.

For the same reason, there is no mouse interaction to speak of and no scrollable subpanel. Everything is text that the pager and your scrollback handle, which is a genuine limitation next to a real GUI debugger but a reasonable exchange for something that survives a headless workflow.

The README ends where the wiki begins

The README is short by design and it points you onward explicitly: head to the wiki to learn how to perform the most important tasks. That single line is the biggest thing to know before evaluating the project, because the interesting material is not on the repository page. Task walkthroughs, the full module list, the style names and the configuration options live in the GitHub wiki, which is a separate repository with its own edit history and no version tied to the `.gdbinit` file you downloaded.

So the documentation split looks like this. The README gives you the premise, the one-line install, the optional Pygments dependency and the promise that nothing gets redefined. The wiki gives you how to actually use it once installed. There are no published releases to read release notes against and no separate documentation directory in the tree, so if you want to know what changed between the version you have and the version you are about to fetch, the commit history on master is where you would look.

That arrangement suits a project of this kind, where the surface area is one file and the behaviour is mostly visual. It does mean the first session after installing is a wiki session. Reading the main wiki page before you download anything will also tell you whether the panel set matches the kind of debugging you actually do.

Editorial conclusion

gdb-dashboard is at its best as a drop-in default for anyone who already knows how to drive plain GDB and finds the scrollback unfriendly. It costs one file in your home directory, adds no build step and no dependency beyond an optional syntax highlighter, and it removes nothing you already rely on. What it does not give you is a GUI: it renders ANSI in a terminal, so it works over SSH and inside tmux but will not reflow for you, and it does nothing on macOS terminals that handle colour poorly. The one thing to read before installing is the wiki, because the README explicitly leaves the task walkthroughs there and the repository itself publishes no tagged releases to track. Start with the wget line, run a program until it stops, then adjust panels one at a time with the dashboard command rather than trying to absorb the whole layout at once.

Frequently asked questions

Official sources

1. cyrus-and/gdb-dashboard on GitHub
2. Issues
3. License: MIT
4. README