A tiny macOS service that monitors free disk space on the root volume. Every minute it writes a sample to ~/.config/storage-service-log.jsonl, and when free space drops below 10 GB it asks the notification-service to pop a modal alert. It also exposes a small HTTP API on http://127.0.0.1:11271 for querying the current and recent free space. Pure Swift + AppKit, no third-party dependencies.

Build

swift build -c release      # or: just build

Quick test

With the service running (just install or just run):

just status                 # current free space + last 10 samples
just check                  # force one sample now

Run (foreground)

.build/release/StorageService run      # or: just run

Installs a per-user LaunchAgent so the service starts at login and stays alive:

.build/release/StorageService install   # or: just install

Binary → ~/Library/Application Support/StorageService/storage-service
LaunchAgent → ~/Library/LaunchAgents/com.hattergit.storage-service.plist
Logs → /tmp/storage-service.log, /tmp/storage-service.err
Samples → ~/.config/storage-service-log.jsonl
Listens → http://127.0.0.1:11271

Remove it with:

.build/release/StorageService uninstall   # or: just uninstall

API

`GET /api/v1/status`

Returns the current free space and the last 10 logged samples.

curl http://127.0.0.1:11271/api/v1/status

Response:

{
  "current" : { "free" : "12.34GB", "freeBytes" : 13245124321, "freeGB" : 12.34, "low" : false },
  "history" : [
    { "time" : "2026-07-11T09:30:00Z", "free" : 12.34 },
    ...
  ]
}

`POST /api/v1/check`

Take a sample immediately (writes a log line and, if below 10 GB, fires a reminder). Returns the freshly-sampled value:

curl -X POST http://127.0.0.1:11271/api/v1/check

{ "status": "checked", "free": "12.34GB", "low": false }

Other paths/methods return 404 / 405.

Reminders

When a sample is below 10 GB, the service POSTs to the notification-service:

curl -X POST http://127.0.0.1:11270/api/v1/show \
  -H 'Content-Type: application/json' \
  -d '{"title":"Storage Service","content":"9.50GB"}'

content is the free space in a.aaGB form (two decimals). The notification-service must be running (and installed) for the alert to appear.

Log

~/.config/storage-service-log.jsonl — one JSON object per line, appended each minute:

{"time":"2026-07-11T09:30:00Z","free":12.34}

free is GB (1024³-byte units), rounded to two decimals.

Notes

Bound only to the loopback interface — not reachable from the network.
Runs as a background (accessory) app: no Dock icon, no menu bar entry.

README.md

storage-service