mac-memory-guard

KO | EN

gitlite — search

#artificial-intelligence #csharp #pdf #docker #deep-learning #claude #devops #list #rust #chatbot

mac-memory-guard

(★ 9)

Proactive macOS memory-pressure watchdog: warns before your Mac freezes and lets you quit the biggest memory-hog apps. Pure bash + launchd, zero dependencies.

File Explorer

ZIP Download

.gitignore
com.memoryguard.agent.plist.template
install.sh
LICENSE
memory-guard.sh
README.md
uninstall.sh

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> A tiny macOS watchdog that warns you **before** your Mac freezes from memory pressure — names the apps eating your RAM, and lets you quit them one at a time.

![platform](https://img.shields.io/badge/platform-macOS-blue)
![shell](https://img.shields.io/badge/built%20with-bash-green)
![dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)
![license](https://img.shields.io/badge/license-MIT-lightgrey)

Memory Guard runs quietly in the background as a `launchd` agent. It stays
invisible until your system gets close to thrashing — then it pops a single
alert listing the biggest memory hogs and lets you close them gracefully,
**one at a time**. No menu bar clutter, no dependencies, no telemetry.

```
⚠️ Memory is getting tight.

Free memory: 11%    Swap: 2310 MB

Pick ONE app to quit (it'll be asked to save first).
You can quit another after, or click Done.

🧹  Free inactive memory (purge caches)
  Google Chrome  —  5.8 GB
  Slack          —  3.1 GB
  Superhuman     —  2.4 GB
  Code           —  1.9 GB

[ Done ]   [ Quit it ]
```

## Why not just use Activity Monitor or a "memory cleaner"?

On a modern Mac, **free RAM is supposed to be near zero** — macOS uses spare
memory for caching and reclaims it on demand. The real freeze signal is
**memory pressure** (the kernel compressing and swapping memory) plus **growing
swap usage**. Memory Guard watches exactly that — the same signal behind
Activity Monitor's "Memory Pressure" graph.

App Store "memory cleaner" apps that brag about freeing X GB of RAM are mostly
measuring the wrong thing. Memory Guard doesn't try to "clean" memory; it tells
you *which app is the problem* and helps you act before the spinning beachball.

## Features

- 🚦 **Proactive** — alerts you *before* the freeze, not after.
- 🎯 **Names the culprits** — top apps by real memory use, with helper processes aggregated per app (so Chrome's 30 processes show as one line).
- 🔪 **Quit individually** — close one app at a time; never a blanket kill.
- 🤝 **Graceful** — apps are asked to quit so unsaved-work prompts still appear.
- 🧹 **Optional cleanup** — free inactive memory via `purge` (opt-in).
- 🪶 **Zero dependencies** — pure `bash` + AppleScript. No Homebrew, no Python, no kernel extensions.
- 🔇 **Silent by default** — does nothing until pressure crosses a threshold, with a cooldown so it never nags.

## Requirements

- macOS (uses the built-in `memory_pressure`, `sysctl`, `osascript`, and `launchd`)
- `bash` (the system `/bin/bash` 3.2 is fine)

## Install

```bash
git clone https://github.com/TomGranot/mac-memory-guard.git
cd mac-memory-guard
./install.sh
```

That copies the script to `~/.local/share/memory-guard/`, installs a
LaunchAgent, and starts it. To verify it works right away:

```bash
~/.local/share/memory-guard/memory-guard.sh --status   # current pressure + top apps
~/.local/share/memory-guard/memory-guard.sh --test     # force the alert dialog
```

The first time the alert tries to control an app, macOS may ask for
**Automation** permission — allow it so Memory Guard can quit apps for you.

## Usage

Once installed, there's nothing to do — it runs every 30 seconds and only
speaks up when memory gets tight. When the alert appears:

1. Pick **one** app and click **Quit it** — only that app closes.
2. The alert re-appears with the remaining apps and refreshed memory numbers.
3. Quit another, or click **Done** to stop.

Manual commands (handy for testing or a quick check):

| Command | What it does |
|---------|--------------|
| `memory-guard.sh` | One check (what `launchd` runs) |
| `memory-guard.sh --status` | Print current pressure, swap, and top apps |
| `memory-guard.sh --test` | Force the alert now, ignoring thresholds |

## Configuration

Edit the config block at the top of `memory-guard.sh`, then re-run
`./install.sh` to reload:

| Setting | Default | Meaning |
|---------|---------|---------|
| `PRESSURE_LEVEL_WARN` | `2` | Alert at this macOS pressure level or above: `2` = warning (yellow), `4` = critical (red) only |
| `FREE_PCT_FLOOR` | `8` | Backstop for old macOS without the pressure sysctl: alert if free memory ≤ this % |
| `TOP_N` | `4` | How many hog apps to list |
| `COOLDOWN_SECS` | `120` | Minimum seconds between alerts (anti-nag) |
| `ENABLE_PURGE` | `1` | Offer "free inactive memory" in the alert |

Too eager (fires while things still feel fine)? Set `PRESSURE_LEVEL_WARN=4` to
alert only at critical/red pressure. Free RAM % and swap are intentionally **not**
triggers — on Apple Silicon both look alarming during perfectly healthy use.

## Optional: enable the "Free inactive memory" action

macOS's `purge` command needs root. To let Memory Guard run it without a
password prompt, add a one-time sudoers rule:

```bash
echo "$(whoami) ALL=(root) NOPASSWD: /usr/sbin/purge" | sudo tee /etc/sudoers.d/memoryguard-purge
sudo chmod 440 /etc/sudoers.d/memoryguard-purge
```

Without this, choosing the purge option just shows a note and skips it —
quitting the hog apps is the real win anyway.

## How it works

1. A `launchd` agent (`com.memoryguard.agent`) runs the script every 30 s.
2. The script reads macOS's **memory-pressure level** from
   `sysctl kern.memorystatus_vm_pressure_level` (the same green/yellow/red signal
   as Activity Monitor). At normal/green it exits silently. Free RAM % and swap
   are read for display only — never as triggers.
3. When pressure reaches warning/critical (and the cooldown has elapsed), it builds the
   top-app list by summing each process's RSS per `.app` bundle, restricted to
   user-facing apps under `/Applications` and `/Users`.
4. It shows a single-selection AppleScript dialog. You quit apps one at a time;
   each app is asked to quit gracefully (force-kill is only a fallback).
5. A single-instance lock prevents overlapping dialogs, and a cooldown prevents
   repeated nagging.

## Troubleshooting

- **No dialog ever appears.** Check the agent is loaded:
  `launchctl list | grep memoryguard` (column 2 is the last exit code; `0` is healthy).
  Force one with `--test`.
- **"Quit it" doesn't close the app.** Grant Automation permission in
  *System Settings → Privacy & Security → Automation*.
- **It fires too often.** Set `PRESSURE_LEVEL_WARN=4` (critical only) and/or raise `COOLDOWN_SECS`.
- **Check the log:** `~/.local/share/memory-guard/memory-guard.log` (empty during healthy silent runs).

## Uninstall

```bash
./uninstall.sh
```

Removes the agent, the LaunchAgent plist, and the installed files. (If you added
the purge sudoers rule, the script reminds you how to remove it.)

## Contributing

Issues and pull requests are welcome. This is intentionally a small,
single-file tool — contributions that keep it dependency-free and easy to read
are the most likely to be merged. Good first additions:

- Surfacing non-app memory hogs (VMs, containers) as informational entries
- A configurable list of apps to never offer for quitting
- Localization of the alert text

Please test changes with `./install.sh && memory-guard.sh --test` before
opening a PR.

## License

[MIT](LICENSE)

mac-memory-guard

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

mac-memory-guard

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README