Implement RAM usage reporting

[heath-toby]

Summary

• Implements the previously empty ramUsage() function (Ctrl+Shift+2)
• Reports physical memory usage using hs.host.vmStat(), calculating used memory as total minus reclaimable pages (free, inactive, speculative, purgeable)
• Reports swap usage via sysctl vm.swapusage when swap is active; shows "0 bytes used" otherwise

Example output

• No swap: "Physical: 9.86GB of 16.0GB used (61.6%). Swap: 0 bytes used."
• With swap: "Physical: 14.2GB of 16.0GB used (88.75%). Swap: 1.5GB of 4.0GB used."

Approach and limitations

macOS does not expose the exact memory accounting used by Activity Monitor through public APIs. Activity Monitor uses private per-process APIs (task_info / phys_footprint) which capture IOKit/GPU memory allocations and per-process compressed memory attribution that aren't visible through vm_stat page categories.

This implementation uses hs.host.vmStat() (which wraps the kernel's vm_stat data) and defines "used memory" as total physical memory minus pages the system can instantly reclaim (free + inactive + speculative + purgeable). In testing, this tracks within ~1 GB of Activity Monitor's "Memory Used" figure on a 16 GB system.

Several alternative approaches were evaluated:

• Summing active + wired + compressor pages: Under-counts by missing GPU/IOKit allocations
• Parsing top -l 1 PhysMem output: Over-counts by including cached files as "used"
• Current approach (total minus reclaimable): Best balance of accuracy and simplicity using only public APIs

Test plan

• Reload Hammerspoon config and press Ctrl+Shift+2
• Verify physical memory usage is announced and is reasonably close to Activity Monitor
• Verify swap reports "0 bytes used" when no swap is active
• Test on systems with active swap usage if possible

🤖 Generated with Claude Code

[trypsynth]

Oh hey there, long time no chat, old friend. I'll give this a review soon, I'll pull out my mac and test it. Thanks for stepping up to this challenge, my solution was going to be to write some objective-c to do it like psutil

[heath-toby]

Hello,No problem at all.I am afraid I do not have a whole load of programming knowhow, so this was helped by Claude Code. I tried to get it as best as I could but it seems that there are some values we just can't get, as you found. I figured it might be at least helpful to get an approximate value rather than nothing at all.Many thanks,Toby.PS, when you say Long Time No Chat, where might I know you from?Sent from my iPhoneOn 3 Mar 2026, at 17:10, Quin Gillespie ***@***.***> wrote:trypsynth left a comment (trypsynth/recmon#6) Oh hey there, long time no chat, old friend. I'll give this a review soon, I'll pull out my mac and test it. Thanks for stepping up to this challenge, my solution was going to be to write some objective-c to do it like psutil —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you authored the thread.Message ID: ***@***.***>