boost

A macOS RAM, CPU, process, and disk tune-up orchestrator

A professional, dependency-light Mac cleanup CLI with a clean ASCII interface.

---

Why boost?

Over time macOS accumulates leaked background processes, bloated dev-caches (uv, bun, npm, Xcode) and idle memory. Off-the-shelf cleaners miss most of it. boost:

• Hunts leaked processes by age, with parent/process revalidation before termination.
• Reclaims RAM smartly - only purges when memory pressure is high.
• Runs deep and safe dev-cache cleanup, delegating optional heavy lifting to mole.
• Presents status with a clean ASCII menu, gauges, and live watch mode.
• Runs itself daily via launchd.
• Has near-zero dependencies - pure bash 3.2, works out of the box.

Philosophy: boost doesn't reinvent the wheel. It rides on top of mole and adds the process/RAM/CPU work that mole doesn't do.

---

Installation

Homebrew

The Homebrew core formula name boost is already used by the C++ Boost libraries, so this project is distributed as boost-cleaner while installing the boost command.

brew install alierkn/tap/boost-cleaner

Or tap first if you prefer short formula names:

brew tap alierkn/tap
brew install boost-cleaner

Upgrade later with:

boost update
# or: brew upgrade boost-cleaner

Git checkout

git clone https://github.com/alierkn/boost.git
cd boost
./install.sh

install.sh sets up:

• bin/boost -> ~/.local/bin/boost (on your PATH)
• zsh tab-completion + a b alias (~/.zshrc)
• a daily launchd agent (~/Library/LaunchAgents/)
• a default config (~/.config/boost/config)

Or via Make:

make install      # install
make lint         # shellcheck + syntax
make test         # smoke tests
make uninstall    # remove

Recommended (optional) dependencies

Tool	For	Install
gum	Optional interactive confirms	brew install gum
mole	Deep disk/cache cleanup	brew install mole

Without either, boost still works fully with its pure-bash ASCII UI and built-in cache cleanup.

---

Usage

boost            # scan & report (deletes nothing)
boost plan       # preview the cleanup plan (deletes nothing)
boost ui         # interactive ASCII menu
boost watch      # live auto-refreshing status
boost all        # full clean (with confirmation)
boost all -y     # full clean (unattended)
boost history    # past runs + total reclaimed
boost doctor     # install and environment checks
boost update     # update via Homebrew or the recorded git checkout

Commands

Command	Description
boost / boost scan	Dashboard + system report + leak scan (read-only)
boost ui	Interactive ASCII menu
boost gui	Alias for the same ASCII menu
boost watch [--every N]	Live auto-refreshing status (default 2s)
boost plan	Preview the full cleanup plan (read-only)
boost all	Processes + RAM + deep disk cleanup + mole
boost ram	Smart RAM purge + leaked process cleanup
boost procs	Clean leaked processes only
boost disk	Deep dev-cache cleanup + mole
boost cpu	Report top CPU/RAM consumers
boost history	Past runs and total reclaimed
boost doctor	Check install, PATH, config, launchd, and optional tools
boost update	Update boost via Homebrew or the recorded git checkout

Flags

Flag	Effect
-y, --yes	Don't ask for confirmation
-n, --dry-run	Don't delete; just show what would happen
--auto	Non-interactive mode (for launchd/cron)
--force-purge	Purge RAM regardless of pressure
--max-age <h>	Treat processes older than <h> hours as leaks (default 24)
--no-mole	Don't invoke mole
--every <s>	watch refresh interval
-v, --version	Print version

Environment

Variable	Effect
NO_COLOR=1	Disable colors and terminal control escapes for plain ASCII output
TERM=dumb	Use plain ASCII output without cursor control
NO_UPDATE_CHECK=1	Disable the daily GitHub release update check

---

How it works

flowchart TD
    A([boost]) --> B{command}
    B -->|scan, ui, watch| V[ASCII visualization layer<br/>gauge, bar, menu]
    B -->|all| C[Orchestrator]

    C --> P[Process cleanup]
    C --> R[Smart RAM purge]
    C --> D[Deep disk cleanup]

    P --> P1[find children of all<br/>claude-mem daemons]
    P1 --> P2{age over threshold?}
    P2 -->|yes| P3[revalidate parent, age,<br/>and protected list]
    P3 --> P5[TERM, then KILL<br/>only if still running]
    P2 -->|no| P4[keep]

    R --> R1{free RAM below threshold?}
    R1 -->|yes| R2[sudo purge]
    R1 -->|no| R3[skip]

    D --> D1[uv, bun, npm, pnpm<br/>pip, brew, cargo]
    D --> D2[Xcode, CocoaPods<br/>logs, .DS_Store, QuickLook]
    D --> D3[delegate to mole:<br/>mo clean and mo optimize]

    C --> L[(history.log)]
    L --> H[boost history]

Loading

Architecture layers

flowchart LR
    subgraph CLI["boost (pure bash 3.2)"]
        UI["ASCII UI layer: gauge, bar, menu, watch"]
        ORCH["Orchestrator: scan, all, ram, disk"]
        CFG["Config: ~/.config/boost/config"]
    end
    subgraph EXT["Optional"]
        GUM["gum: optional confirms"]
        MOLE["mole: deep disk cleanup"]
    end
    subgraph OS["macOS"]
        LD["launchd: daily automation"]
        PS["ps, vm_stat, top, purge"]
    end
    UI -.uses.-> GUM
    ORCH -.delegates.-> MOLE
    ORCH --> PS
    LD --> ORCH
    CFG --> ORCH

Loading

Safety by design

• Read-only default: plain boost deletes nothing.
• Run lock: destructive commands use an atomic lock under ~/.cache/boost so scheduled and manual runs do not overlap.
• Scoped process hunt: only children of claude-mem daemons are targeted, then revalidated before termination.
• Protected list: WindowServer, Finder, kernel_task, etc. are never killed.
• Canonical path shield: $HOME, /, /Users and friends are guarded against deletion.
• Safe caches only: only re-downloadable caches are cleaned, preferring official <tool> cache clean commands.
• Cleanup preview: boost all shows a plan before work starts; boost plan shows the same plan without changing anything.
• Update awareness: interactive entry points check GitHub releases at most once per day and suggest boost update when a newer version is available.

See SECURITY.md for the full threat model.

---

Configuration

~/.config/boost/config (created automatically on first run):

MAX_AGE_HOURS=24            # observers older than this = leaked
PURGE_WHEN_FREE_BELOW=35    # purge only when free RAM % is below this
LOG_RETENTION_DAYS=7        # delete user logs older than this
CLEAN_DSSTORE=1             # sweep stray .DS_Store files
ENABLE_DOCKER=0            # run 'docker system prune -f'
NOTIFY=1                   # macOS notification when a full run finishes

---

Automation

install.sh registers a daily (09:00) launchd agent: boost all --auto --no-mole.

# status
launchctl list | grep boost
# trigger manually
launchctl start com.user.boost.daily
# remove
launchctl unload ~/Library/LaunchAgents/com.user.boost.daily.plist

In automated runs the RAM purge is skipped (it needs sudo); process and cache cleanup run fully.

---

Uninstall

./uninstall.sh   # or: make uninstall

---

Contributing

PRs welcome! See CONTRIBUTING.md. All shell changes go through shellcheck in CI. By participating you agree to the Code of Conduct.

License

MIT © Ali Erkan Ocaklı (@alierkn)

_{Keep your Mac clean and fast with boost.}