Skip to content

# docs(readme): revamp structure, add Quick Start, and include Mermaid diagrams #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SickleFire merged 4 commits into from
Jun 16, 2026
+121 −50
Merged

# docs(readme): revamp structure, add Quick Start, and include Mermaid diagrams #60

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a686c2c
docs: Add Quick Start section to README
Samanyu-dev Jun 15, 2026
e38ea68
docs: revamp README with Mermaid diagrams and improved structure
Samanyu-dev Jun 15, 2026
f0bfc7f
docs: standardize hyphenation by removing unnecessary hyphens from RE…
Samanyu-dev Jun 15, 2026
525b98b
Merge branch 'SickleFire:master' into master
Samanyu-dev Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
171 changes: 121 additions & 50 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,42 +1,121 @@
# mvis
# m-vis: Memory Debugging Made Simple 🧠

[![Tests](https://github.com/SickleFire/m-vis/actions/workflows/tests.yml/badge.svg)](https://github.com/SickleFire/m-vis/actions/workflows/tests.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## Why mvis?
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.

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

Our design philosophy is built around simplicity and accessibility because **We believe memory debugging should be accessible, not a PhD requirement.**
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."**

## Status
Early but functional. Core scanning and leak detection work on both platforms. See the roadmap below for what's coming.
---

## 🏗 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.

```mermaid
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

### New TUI
UI --> Core
Core --> OS
```

---

## 🚀 Quick Start

### 1. Installation
The fastest way to get started is downloading a pre built binary from the [Releases](https://github.com/SickleFire/m-vis/releases) page.
If you have Rust installed, you can build from source:
```bash
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:
```bash
mvis tui
```
<img width="1919" height="986" alt="Screenshot 2026-06-05 173344" src="https://github.com/user-attachments/assets/31d98a81-a951-486c-a51e-9abc7b198406" />

<img width="1919" height="980" alt="Screenshot 2026-06-05 173607" src="https://github.com/user-attachments/assets/fea2c2f9-8f5d-48fb-b13f-21b6b30656e3" />
### 3. Basic CLI Commands
```bash
# 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
- **Process Scanning**: Inspect memory allocations of active processes.
- **Heap-Level Analysis**: Dive into heap structures for detailed debugging.
- **DLL Tracking**: Monitor and list all DLLs loaded by a target.
- **Memory Leak Detection**: Identify and monitor processes with growing, unreleased allocations.
- **Leak Delta Chart**: mvis includes a real-time leak delta chart that visualizes memory allocation trends over time directly in the TUI.
- **Supported OS**: Windows, Linux, macOS
## 🎨 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.

---

## macOS Code Signing
## 🔄 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.

```mermaid
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
```

---

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.
## 🔐 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:
```bash
Expand All @@ -48,7 +127,11 @@ 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.*

## Usage
---

## 💻 Detailed Usage & Examples

### Available Commands
```powershell
# visualize memory map
mvis scan notepad.exe -a
Expand All @@ -59,51 +142,37 @@ mvis scan notepad.exe -h
# detect leaks
mvis leak notepad.exe 10

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

# list processes
mvis list

#open mvis tui
# open mvis tui
mvis tui
```
### Examples

### Visual Examples

**Detecting Leaks:**
```powershell
mvis leak leaking_app.exe 10
```
Output: <br>
<img width="570" height="77" alt="Screenshot 2026-05-01 181525" src="https://github.com/user-attachments/assets/fbef4565-45b3-4388-8c6a-85f8d0df89f5" /> <br>

**Scanning Process Maps:**
```powershell
mvis scan myapp.exe -a
```
<br>
Output: <br>
<img width="579" height="133" alt="Screenshot 2026-05-01 182001" src="https://github.com/user-attachments/assets/f9bd515e-9cc7-49f8-8cf5-9d2e79ab8f22" />
. <br>
. <br>
. <br>
<br>
<img width="1091" height="267" alt="Screenshot 2026-05-01 181929" src="https://github.com/user-attachments/assets/52563bf0-7b6b-4875-8eb1-ed692622aed5" />

---

## Installation

### From GitHub Releases (Recommended)
Download pre-built binaries from [Releases](https://github.com/SickleFire/m-vis/releases):
- **Windows:** `mvis-windows-x86_64.exe`
- **Linux:** `mvis-linux-x86_64`


### From source
```bash
git clone https://github.com/SickleFire/m-vis
cd mvis
cargo build --release
```

## Testing
## 🛠 Developer Commands & Testing

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

Expand All @@ -117,18 +186,20 @@ cargo test
cargo test --test integration_tests
```

### Run integration tests with admin privileges (advanced)
### Run integration tests with elevated privileges
```bash
# 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
```

---
### Roadmap
See [Roadmap](https://github.com/SickleFire/m-vis/issues/24)

## License
## 📅 Status & Roadmap
Early but highly functional. Core scanning and leak detection work on all supported platforms.
See the [Roadmap](https://github.com/SickleFire/m-vis/issues/24) for what's coming next.

## 📄 License
MIT — see [LICENSE](LICENSE.md)
Loading