# BugStalker: A Rust-Native Debugger for Linux x86-64

> BugStalker is a Rust-focused debugger for Linux x86-64 programs. It combines native execution control, Rust data inspection, Tokio support, a terminal UI, and DAP integration within a deliberately narrow platform scope.

**godzie44/BugStalker** — Rust debugger for Linux x86-64

- Repository: https://github.com/godzie44/BugStalker
- Stars: 1,423 · Forks: 33
- Language: Rust
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/godzie44-bugstalker

## BugStalker's Rust and Linux Scope

BugStalker addresses developers who need to inspect running Rust programs rather than treat them as undifferentiated native executables. Its documented target is Linux x86-64, a restriction stated in the README and repository description. The project is not presented as a cross-platform debugger with interchangeable operating-system or processor backends. Platform fit therefore comes before feature comparisons.

The tool focuses on development-time program inspection. Its core features include breakpoints, step-by-step execution, signal handling, and watchpoints. Around those controls, it adds multithreaded application support, data query expressions, and deeper inspection of Rust values. The README specifically names collections, smart pointers, and thread locals as supported areas of the Rust type system. It also says variables use the `core::fmt::Debug` trait for rendering.

That scope makes BugStalker relevant to developers investigating execution flow, application state, native library behavior, panics, and asynchronous Rust programs. The README does not position it as a profiler, fuzzer, vulnerability scanner, production observability system, or automated root-cause analysis service. The intended setting is interactive debugging through a console, terminal UI, or editor using DAP.

Rust developers working on Linux x86-64 are the clearest audience. Developers who need another operating system or CPU architecture should choose a debugger that explicitly supports that environment. A project built for Linux x86-64 can still be rejected if its team requires a GUI debugger without an editor integration, or if its debugging workflow depends on features absent from BugStalker's documentation.

## Execution Control and Rust Data Inspection

BugStalker combines ordinary execution control with runtime-aware data inspection. Breakpoints stop execution at selected locations, while step commands provide more deliberate traversal. Watchpoints allow developers to react when a value changes, and signal handling is exposed as part of the documented feature set. These facilities cover the basic control loop expected from a debugger.

The Rust-specific layer appears in how the debugger presents application state. The README says BugStalker supports collections, smart pointers, and thread locals, and that these structures can be queried and interacted with rather than only printed. Data query expressions provide a way to navigate or select runtime data, while `core::fmt::Debug` integration controls variable rendering. This is relevant when useful information is held in compound Rust values rather than plain machine words.

Thread support is documented as covering multithreaded applications. The repository includes `examples/mt/` for multithreading, along with `examples/signals/`, `examples/panic/`, `examples/shlib/`, and `examples/recursion/`. Those example programs are concrete targets for evaluating behavior involving threads, signals, panics, shared libraries, and recursive calls. The README does not claim that thread scheduling can be reproduced deterministically, so developers should verify timing-sensitive cases themselves.

The package dependencies also indicate a native implementation. `Cargo.toml` includes `nix` with `process`, `signal`, `uio`, `personality`, and `ptrace` features. It also lists `gimli`, `object`, `memmap2`, `rustc-demangle`, and `capstone`. These dependencies are consistent with process access, executable metadata, memory mapping, Rust symbol naming, and disassembly. Exact internal control flow is not described in the README, so this is an implementation signal rather than a complete architecture account.

## Tokio Inspection Through Oracle Extensions

Async Rust support is handled through BugStalker's Oracle extension mechanism. The built-in Tokio oracle is described as similar to `tokio_console`, with one important stated difference: it requires no code modifications to the inspected application. That removes the need to add instrumentation calls before using the documented Tokio inspection facility.

The Oracle mechanism indicates that runtime-specific inspection is designed as an extension point rather than a feature limited permanently to Tokio. The repository contains a dedicated `extension/` directory, and `Cargo.toml` describes BugStalker as extensible. The README does not document the extension author interface, packaging process, or compatibility guarantees. A developer should not infer that arbitrary Rust async frameworks can be supported without checking the extension documentation.

The Makefile builds example fixtures for Tokio versions 1.40 through 1.44. These paths include `tokio_tcp/tokio_1_40/` through `tokio_tcp/tokio_1_44/`, and corresponding `tokio_vars/` directories. The repository layout shows deliberate coverage across several versions. It does not prove support for every current or future Tokio release, so an application using another version needs separate verification.

For Tokio users, the relevant question is whether the target application's runtime representation matches the versions covered by the project. For projects that do not use Tokio, this subsystem adds little direct value. For developers considering a custom Oracle extension, the extension contract, release process, and maintenance burden need investigation because the README leaves those details unspecified.

## Terminal Interfaces and Editor Integration

BugStalker allows users to switch between console and TUI modes at any time, according to the README. This provides two terminal interaction styles without requiring the user to choose permanently when installing the debugger. The package dependencies include `rustyline`, `crossterm`, `tuirealm`, `tui-realm-stdlib`, and `tui-realm-treeview`, corresponding to command-line editing and terminal interface components.

The project also supports the Debug Adapter Protocol. The README lists extensions for VSCode and Zed, and identifies stdio and TCP modes. The embedded stdio model is intended for local editor integration. TCP mode is described as remote operation. The README directs readers to `doc/DAP.md` for configuration details, so port numbers, launch settings, and adapter invocation commands should come from that document.

DAP support lets editors request debugging operations through a protocol instead of requiring direct interaction with BugStalker's terminal commands. It does not turn the project into a language server. The repository does not document completion, formatting, diagnostics, or code navigation as part of the editor integration.

TCP mode may fit an editor and target environment that are not running on the same machine. The README does not describe authentication, access controls, or transport security for that mode. Those details must be verified before exposing a TCP adapter beyond a trusted local arrangement.

## Building BugStalker and Preparing a First Debug Session

The README sends users to the installation page instead of giving installation commands on its main page. It does not document prerequisites, distribution packages, a release download procedure, or a first debug session there. Those steps should be taken from the linked installation documentation. The README links `https://godzie44.github.io/BugStalker/docs/installation` as the installation source.

For building from the repository, the Makefile defines this debug build command. It builds the `bs` binary declared in `Cargo.toml`.

```bash
cargo build
```

The package metadata requires Rust `1.89.0` and uses edition `2024`. The repository also contains `rust-toolchain.toml`, but its contents are not shown in the documented repository entries. A developer should inspect that file and use a compatible Rust toolchain before building.

For a release build, the Makefile defines:

```bash
cargo build --release
```

The repository contains `examples/hello_world/`, `examples/calc/`, and other executable examples. The README does not give a command for launching one under BugStalker, and the package metadata does not document a target-loading flag in the shown configuration. A new user should follow the installation page for the exact launch syntax rather than guessing. Once the program is loaded, the documented first actions are breakpoint, step, and watchpoint inspection.

The root `requirements.txt` contains `pexpect`, `psutil`, and `requests`. The Makefile uses Python's unittest discovery for integration tests, but the README does not state that these packages are required to run the compiled debugger interactively. Their role should be checked in the installation guide before installing them.

## Alternative Debuggers and Upgrade Boundaries

BugStalker is the wrong choice when the required target is not Linux x86-64. It may also be unsuitable for teams requiring a documented GUI-first debugging workflow, although VSCode and Zed extensions may provide an editor route. The README does not document source-level support for other languages, production-safe monitoring, performance profiling, or automated debugging services.

The package declares the MIT License. The README states that BugStalker is distributed under the MIT License. That license is permissive, but redistribution still requires attention to its notice and disclaimer conditions. This is not legal advice. The repository also has a `CHANGELOG.md`, while the README does not specify an upgrade policy or compatibility window. Projects with strict version requirements should record the selected BugStalker release, Rust toolchain, Tokio version, and editor extension together.

## Conclusion

Rust developers debugging Linux x86-64 programs who value Rust-specific inspection and DAP integration should evaluate BugStalker first. Developers requiring another operating system or processor architecture should choose another debugger. Before adoption, verify the installation requirements, debugger launch workflow, target binary, and relevant VSCode or Zed DAP configuration.

## FAQ

### What operating systems and CPU architectures does BugStalker support?

The repository description and README identify BugStalker as a debugger for Linux x86-64. The README does not document support for other operating systems or CPU architectures.

### Does BugStalker support Rust async programs and Tokio inspection?

Yes. The README lists async Rust support and a built-in Tokio oracle that requires no code modifications. The Makefile builds Tokio example fixtures for versions 1.40 through 1.44.

### Can BugStalker be used with VSCode or Zed?

The README lists extensions for both VSCode and Zed through Debug Adapter Protocol support. It documents embedded stdio and remote TCP modes, with configuration details in `doc/DAP.md`.

## Sources

- [godzie44/BugStalker on GitHub](https://github.com/godzie44/BugStalker)
- [Issues](https://github.com/godzie44/BugStalker/issues)
- [License: MIT](https://github.com/godzie44/BugStalker/blob/master/LICENSE)
- [README](https://github.com/godzie44/BugStalker/blob/master/README.md)
- [Releases](https://github.com/godzie44/BugStalker/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/godzie44-bugstalker