m-vis: Memory Debugging Made Simple 🧠

Welcome to m-vis. Memory debugging for developers who just want answers. Simple. Fast. Works everywhere.

Existing tools are either platform specific (Valgrind, WinDbg) or too complex for quick diagnostics. m-vis gives you deep memory insights with a single command across any platform.

Our design philosophy is built around simplicity and accessibility because we believe memory debugging should be accessible, not a PhD requirement.

"One command. All platforms. No configuration hell."

---

🏗 System Architecture

m-vis is built in Rust to provide native, blazing fast performance without overhead. It abstracts away the complex OS level memory APIs into a unified, cross platform scanning engine.

graph TD
    subgraph UI [User Interfaces]
        CLI[Command Line Interface]
        TUI[Terminal User Interface]
    end

    subgraph Core [m-vis Core Engine]
        Scan[Memory Scanner]
        Leak[Leak Detector]
        Stack[Stack Tracer]
    end

    subgraph OS [Operating System APIs]
        Win[Windows API / VirtualQueryEx]
        Lin[Linux / procfs / ptrace]
        Mac[macOS / Mach VM API]
    end

    UI --> Core
    Core --> OS

Loading

---

🚀 Quick Start

1. Installation

The fastest way to get started is downloading a pre built binary from the Releases page. If you have Rust installed, you can build from source:

git clone https://github.com/SickleFire/m-vis
cd mvis
cargo build --release
# Your binary is at target/release/mvis

2. Enter the TUI

Experience the interactive memory dashboard immediately:

mvis tui

3. Basic CLI Commands

# Find a target process
mvis list

# Scan process memory maps (replace 'notepad' with your target)
mvis scan notepad -a

# Monitor a process for memory leaks (10 second interval)
mvis leak notepad 10

---

🎨 Features & Capabilities

• Process Scanning: Inspect memory allocations, mapped regions, and permissions of active processes.
• Heap Level Analysis: Dive deeply into heap structures and allocations for detailed debugging.
• DLL Tracking: Monitor and list all dynamic libraries (DLLs/SOs/Dylibs) loaded by a target.
• Real time Memory Leak Detection: Identify and monitor processes with growing, unreleased memory allocations.
• Leak Delta Chart: m-vis includes a real time leak delta chart that visualizes memory allocation trends over time directly in the TUI.
• Universal OS Support: 100% native support for Windows, Linux, and macOS.

---

🔄 Core Workflows: How Leak Detection Works

The leak detector doesn't just watch total RAM usage; it takes deep topological snapshots of the process heap and computes exact block level deltas to find silent unreleased memory.

sequenceDiagram
    participant User
    participant mvis as m-vis Engine
    participant OS as Target Process OS API
    
    User->>mvis: Run `mvis leak <pid> 10`
    
    loop Every 10 Seconds
        mvis->>OS: Capture Deep Memory Snapshot
        OS-->>mvis: Memory Regions & Heap Blocks
        mvis->>mvis: Compute Delta (Diff with previous snapshot)
        
        alt New allocations found
            mvis-->>User: Report Exact Growth & Block Count
        else Stable Memory
            mvis-->>User: Report "No Leaks Detected"
        end
    end

Loading

---

🔐 macOS Security & Code Signing

On macOS, mvis requires the com.apple.security.cs.debugger entitlement to inspect other processes due to Hardened Runtime restrictions. Even with sudo, inspecting third party apps requires this entitlement.

To build and run mvis on macOS:

# We provide a Makefile that automatically builds and signs the binary ad-hoc
make build

# To run a scan using the Makefile helper:
make run-scan PROCESS=language_server_macos_arm MODE=-a

Note: Apple platform apps (Safari, Finder) and some Hardened Runtime apps (WhatsApp) will remain protected by System Integrity Protection (SIP) even with this entitlement.

---

💻 Detailed Usage & Examples

Available Commands

# visualize memory map
mvis scan notepad.exe -a

# heap stats
mvis scan notepad.exe -h

# detect leaks
mvis leak notepad.exe 10

# multi sample leak detection
mvis leak-m notepad.exe 10 3

# list processes
mvis list

# open mvis tui
mvis tui

Visual Examples

Detecting Leaks:

mvis leak leaking_app.exe 10

Output:

Scanning Process Maps:

mvis scan myapp.exe -a

Output:

---

🛠 Developer Commands & Testing

The project includes comprehensive unit and integration tests to ensure reliability across platforms.

Run all tests

cargo test

Run only integration tests

cargo test --test integration_tests

Run integration tests with elevated privileges

# On Linux with sudo
sudo cargo test --test integration_tests -- --include-ignored

# On Windows (run terminal as Administrator)
cargo test --test integration_tests -- --include-ignored

---

📅 Status & Roadmap

Early but highly functional. Core scanning and leak detection work on all supported platforms. See the Roadmap for what's coming next.

📄 License

MIT — see LICENSE