MacForge

A suite of 14 Bash scripts that turn macOS system APIs into a hands-free maintenance layer for developer machines. No third-party dependencies -- every script talks directly to the Darwin kernel and macOS frameworks through their native CLI interfaces.

Philosophy

macOS ships with powerful low-level tools that most developers never touch directly: ioreg for the I/O Registry, pmset for power management, memory_pressure for Mach VM statistics, powermetrics for hardware telemetry, launchctl for service management. MacForge wraps these into opinionated, composable scripts that a developer can run once or wire into launchd for full automation.

Design principles:

• Zero dependencies. No Homebrew, no Python packages, no npm install. Bash 3.2 + the tools Apple ships.
• No sudo by default. Every script works at user level. The two that can use admin (thermal sensor reads, network interface reordering) degrade gracefully without it.
• Dry-run everything. Destructive operations preview first. Nothing deletes, moves, or kills without explicit opt-in.
• Environment-variable config. No dotfiles, no YAML, no JSON configs. Override any threshold inline: MACPULSE_RAM_CRIT=8 ./macpulse.sh.

Quick Start

git clone https://github.com/Tuhin-SnapD/macforge.git
cd macforge

# Make all scripts executable
chmod +x *.sh

# System health dashboard (battery + RAM + disk + CPU)
./macpulse.sh

# Preview a full cleanup without touching anything
./tidymac.sh --dry-run

The Toolkit

System Health & Monitoring

Script	Tagline	What it does
macpulse.sh	"One heartbeat for your whole Mac."	Aggregates battery SoC + cycle health (ioreg AppleSmartBattery), RAM pressure (memory_pressure / vm_stat), disk usage (df), and CPU thermal load (sysctl vm.loadavg + pmset -g therm) into a single dashboard. Fires osascript Notification Centre alerts on warn/crit. --json for machine-readable output.
ramguardian.sh	"Because Chrome will eat all your RAM if you let it."	Reads the Mach memory_pressure subsystem for free-page percentage. At critical levels, invokes purge (Darwin unified buffer cache flush) and optionally sends SIGTERM to the largest Chrome renderer by RSS. Skips aggressive actions on battery via pmset -g batt detection.
thermalsentry.sh	"Don't let your Mac cook itself."	Two modes: with sudo, samples powermetrics -s thermal for real CPU/SOC die temperature from the SMC; without sudo, uses 1-minute load average (sysctl vm.loadavg) as a thermal proxy against hw.ncpu. Can launch Macs Fan Control or SIGSTOP a single whitelisted process.
cpuguard.sh	"Tame the runaway processes before your fans scream."	On battery, scans ps -Ao pcpu,pid,args for heavy processes matching a configurable regex (node, Docker, Gradle, mdworker, etc.). Throttles via renice +N or falls back to taskpolicy -b (Darwin background QoS class). Persists original nice values to a state file and restores on AC.

Battery & Power Management

Script	Tagline	What it does
powertune.sh	"Your battery's personal dietician."	Reads power source from pmset -g batt and switches user-level settings between AC (performance) and battery (endurance) profiles: display brightness via brightness CLI, Bluetooth power state, App Nap policy (defaults write), sleep timers. Optional launchd agent for auto-sync on plug/unplug.
chargeguard.sh	"Nag you before your battery regrets it."	Polls pmset -g batt for SoC percentage and ioreg -c AppleSmartBattery for ExternalConnected / CycleCount / DesignCapacity. Nudges to unplug above a ceiling (default 83%) and replug below a floor (default 38%). State-file cooldown prevents notification spam. Overnight window detection for trickle-charge awareness.

Cleanup & Storage Intelligence

Script	Tagline	What it does
tidymac.sh	"Marie Kondo for your Mac."	Nine-pass cleanup: purge (Mach VM), browser caches (Chrome/Safari/Firefox/Edge/Arc), ~/Library/Caches/* (Spotlight, pip, Homebrew, Yarn, CocoaPods), user logs older than 7 days, Trash, developer artifacts (Xcode DerivedData, npm _cacache, Gradle/Maven caches, Cargo registry, CoreSimulator), .DS_Store files, __MACOSX folders, and dscacheutil -flushcache. Full --dry-run support.
diskbrain.sh	"X-ray vision for your storage."	find + du for files over 1 GiB, heaviest folders one level deep under key paths. Duplicate detection uses an inline Python script: groups files by size, then SHA-256 confirms matches (bounded to prevent runaway scans). Baseline system: save-baseline snapshots du sizes into a TSV; growth diffs against it to find fastest-growing directories.
filesense.sh	"Your Downloads folder called -- it wants its dignity back."	Pattern-matches Desktop screenshots (Screenshot*.png) into ~/Screenshots/YYYY-MM. Classifies flat files in ~/Downloads by extension into typed subfolders (Images, Documents, Archives, Code, Other). Normalises filenames on move. Dry-run by default -- --apply to execute.
privacysweep.sh	"Shred the breadcrumbs."	Targets browser cache directories (Safari com.apple.Safari, Chrome Google/Chrome/*/Cache), pbcopy/pbpaste clipboard via printf '' | pbcopy, Shared File Lists (com.apple.LSSharedFileList), and user-level Spotlight caches (com.apple.parsecd, com.apple.metadata).

Network Diagnostics

Script	Tagline	What it does
netpulse.sh	"Is it DNS? It's always DNS."	Flushes DNS via dscacheutil -flushcache and killall -HUP mDNSResponder (passwordless sudo if available). Latency checks via ping -c 6 -i 0.2 with configurable host (default 1.1.1.1, or gateway for auto-detected default route via route -n get default). Can reorder network service priority via networksetup -ordernetworkservices and bounce interfaces with ifconfig down/up. Cooldown-gated osascript notifications.

Startup Management & Automation

Script	Tagline	What it does
bootclean.sh	"Evict the squatters from your startup."	Enumerates GUI login items via osascript (System Events), user LaunchAgents from ~/Library/LaunchAgents, and system LaunchDaemons from /Library/LaunchDaemons (read-only listing). Validates each agent's binary path exists; flags orphans. Single-label disable via launchctl bootout. Quarantine moves stale plists to a backup directory instead of deleting.
devmode.sh	"One command to enter the zone."	on: applies AC performance profile (powertune.sh --ac), optionally starts Docker Compose (docker compose up -d), triggers Shortcuts automations for Focus/DND, runs a user start hook, opens IDE via open -a. off: reverses all tracked steps from a state file. Port cleanup via lsof -ti :PORT | xargs kill.
autosense.sh	"Set it and forget it."	Generates and bootstraps four launchd plist files under ~/Library/LaunchAgents: weekly tidymac.sh via StartCalendarInterval, periodic powertune.sh --sync via StartInterval, and weekday devmode.sh on/off on configurable hour boundaries. Manages launchctl bootstrap/bootout lifecycle. Sources an optional env.sh for PATH and project-specific exports before each job.

macOS Subsystems Used

Subsystem	CLI Tool	Used by
I/O Registry (IOKit)	ioreg	macpulse, chargeguard (battery cells, cycle count, capacity)
Power Management	pmset	macpulse, powertune, chargeguard, cpuguard, ramguardian, thermalsentry
Mach Virtual Memory	vm_stat, memory_pressure, purge	macpulse, ramguardian, tidymac
BSD Process Control	ps, renice, taskpolicy, kill	cpuguard, ramguardian, thermalsentry, devmode
Kernel Sysctl	sysctl (hw.ncpu, hw.memsize, vm.loadavg)	macpulse, thermalsentry, ramguardian
Hardware Telemetry	powermetrics	thermalsentry (optional, sudo)
Notification Centre	osascript (AppleScript bridge)	all scripts with alerts
Launch Services	launchctl, plist XML	autosense, bootclean, chargeguard, powertune
Network Stack	ping, route, networksetup, ifconfig, dscacheutil	netpulse, tidymac
Filesystem	df, du, find	macpulse, diskbrain, tidymac, filesense
System Events	osascript (System Events.app)	bootclean (login items)
Disk Cache	dscacheutil, killall mDNSResponder	netpulse, tidymac
User Defaults	defaults read/write	powertune (App Nap, Dock effects)

Usage Patterns

One-shot checks (read-only, no side effects)

./macpulse.sh              # Full health dashboard
./macpulse.sh --json       # Pipe to jq, Grafana, or a monitoring stack
./chargeguard.sh --stats   # Raw ioreg + pmset battery snapshot
./diskbrain.sh report      # Large files + heavy folders + duplicates
./bootclean.sh             # Audit startup items and LaunchAgents
./filesense.sh             # Preview Downloads tidy (dry-run default)

Safe previews (dry-run)

./tidymac.sh --dry-run         # See what would be cleaned and how much space
./privacysweep.sh --dry-run    # Preview browser cache + clipboard wipe
./cpuguard.sh apply --dry-run  # See which processes would be throttled
./thermalsentry.sh --no-sudo --dry-run

Active maintenance

./tidymac.sh               # Run all nine cleanup passes
./privacysweep.sh          # Wipe browser caches and trails
./filesense.sh --apply     # Organise Downloads for real
./netpulse.sh              # Flush DNS + latency check
./powertune.sh --sync      # Detect AC/battery and apply matching profile

Watch / continuous modes

./macpulse.sh --watch 60           # Health dashboard every 60s
./ramguardian.sh --watch 30        # RAM pressure check every 30s
./netpulse.sh --latency --watch 60 # Continuous ping monitoring
./chargeguard.sh --watch 300       # Charge advisory every 5 min
./cpuguard.sh watch 120            # Auto-throttle/restore every 2 min

Automation via launchd

./autosense.sh install --dry-run   # Preview LaunchAgent plists
./autosense.sh install             # Write plists + bootstrap into launchd
./autosense.sh status              # Check what's loaded
./autosense.sh uninstall           # Bootout + remove all autosense agents

Configuration

Every script uses environment variables with sensible defaults. No config files. Override inline:

# Custom RAM/disk thresholds
MACPULSE_RAM_CRIT=8 MACPULSE_DISK_WARN=75 ./macpulse.sh

# Tighter charge guard bands
CHARGEGUARD_MAX_SOC=80 CHARGEGUARD_RESUME_SOC=40 ./chargeguard.sh

# Terminal-only output (suppress Notification Centre)
MACPULSE_QUIET=1 ./macpulse.sh
RAMGUARDIAN_QUIET=1 ./ramguardian.sh --watch 60

# CPU guard: only target Docker and node, ignore everything else
CPUGUARD_MATCH="(Docker|node)" CPUGUARD_MIN_CPU=50 ./cpuguard.sh apply

Run any script with --help for the full environment variable reference.

Requirements

• macOS Ventura 13+ / Sonoma 14+ / Sequoia 15+ (Apple Silicon and Intel)
• Bash 3.2+ (ships with macOS at /bin/bash)
• Python 3 (ships with macOS -- used only by diskbrain.sh for SHA-256 duplicate detection)
• No Homebrew / pip / npm / cargo dependencies

Optional (enhances specific scripts)

Tool	Script	What it enables
sudo access	thermalsentry	Real CPU die temperature via powermetrics instead of load proxy
sudo access	netpulse	mDNSResponder HUP, interface bounce, service reorder
ncdu	diskbrain	Interactive disk usage explorer (diskbrain.sh ncdu)
Macs Fan Control	thermalsentry	Auto-open fan control app on critical thermal events

State & Logs

Scripts that track state use XDG Base Directory-compliant paths:

~/.local/state/
  autosense/
    logs/                  # launchd stdout/stderr per job
    env.sh                 # optional user env sourced before jobs
  chargeguard/
    last_events            # notification cooldown timestamps
  cpuguard/
    throttle.state         # PID + original nice values for restore
  devmode/
    state                  # active session tracker (on/off)
  diskbrain/
    baseline.tsv           # folder sizes for growth comparison
  netpulse/
    last_latency_notify    # latency alert cooldown

Plain text files. No databases, no SQLite, no daemons. Delete any state directory to reset that script.

How files are organized

macforge/
  autosense.sh         # launchd automation scheduler
  bootclean.sh         # startup item auditor
  chargeguard.sh       # battery charge advisor
  cpuguard.sh          # CPU process throttler
  devmode.sh           # dev session toggle
  diskbrain.sh         # storage intelligence
  filesense.sh         # file organiser
  macpulse.sh          # system health dashboard
  netpulse.sh          # network diagnostics
  powertune.sh         # power profile switcher
  privacysweep.sh      # privacy cache cleaner
  ramguardian.sh       # memory pressure guardian
  thermalsentry.sh     # thermal watchdog
  tidymac.sh           # system cleanup
  README.md
  .gitignore

License

MIT