`README.md`

61 lines
# RAM Sniper

A standalone, single-file cross-platform RAM/CPU watchdog with a GUI. Built to hand
to someone as one file that runs on a stock Python install — no `pip install` required.

## What it does

- **Navbar** with live **RAM %** and **CPU %**, plus an **ON/OFF** toggle button.
- **Process list** (Treeview) of the biggest RAM hogs — PID / Process / RAM MB / RAM % —
  sorted largest-first, refreshing every 2s.
- **🔫 Kill Selected** — terminates the highlighted process (with a confirm dialog).
- **Auto-Snipe** (OFF by default) — when enabled (and confirmed), auto-kills any process
  whose RAM usage crosses a threshold (default **15%**).

## Run it

```sh
python3 RAMSniper.py
```

That's it. Tkinter ships with the standard Python installer on **macOS** and **Windows**,
so the GUI works out of the box — genuinely one-file-and-run.

Headless self-test (no window, prints the stats it reads):

```sh
python3 RAMSniper.py --test
```

## How the stats are read (psutil-preferred, stdlib fallback)

The tool prefers [`psutil`](https://pypi.org/project/psutil/) when it's installed
(faster, cleaner numbers), and **falls back to platform stdlib tools** when it isn't —
so it still works on a bare Python:

| Platform | Fallback source |
|----------|-----------------|
| macOS    | `sysctl`, `vm_stat`, `ps` |
| Windows  | `ctypes` `GlobalMemoryStatusEx`, `wmic`/`tasklist`/`taskkill` |
| Linux    | `/proc/meminfo`, `/proc/stat`, `/proc/<pid>` |

**Optional speed-up:** for tighter/faster readings, install psutil once —

```sh
pip install psutil
```

— but it is *not* required. The whole point of the tool is that it runs without it.

## Safety

- `kill_pid()` refuses PID 0 and refuses to kill the Sniper's own process.
- Kill and Auto-Snipe-enable both prompt for confirmation before acting.
- Auto-Snipe is **OFF** on every launch; it never persists an armed state.

## Tunables (top of `RAMSniper.py`)

- `REFRESH_MS = 2000` — refresh cadence in milliseconds.
- `TOP_N = 20` — how many processes to list.
- Auto-Snipe threshold default — `15` (% RAM).