Skip to content
tedswinyarPublic

About

Proactive system-pressure sentinel for macOS — Rust core + menu bar app + MCP.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

62 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Banshee

A system-pressure sentinel for macOS, built to be driven by AI agents. It watches the machine continuously and reports how bad things are, which pressure source is winning, who is responsible, and what to do. Your agent gets every one of those answers with the same authority the menu bar has.

The menu bar popover: the verdict, the dimensions out of band, and the best action

Why another system monitor?

A Mac already has many ways to show you a CPU graph. None of them was built for a machine whose biggest consumers are agents: a dozen coding sessions, hundreds of MCP helper processes, some of them orphaned when the session that started them died. The agent is also the party best placed to fix this, and it cannot ask Activity Monitor anything. Existing monitors are a GUI first, with scripting added later if at all.

Banshee is built the other way round. Every operation you have, your agent has: the verdict, the census of running processes, the alert history, what changed since an alert opened, and the reap actions. All of it is on the CLI and over MCP, byte for byte what the app renders. headroom goes one step further and turns the verdict into the decision an agent needs: wait or go, how many more workers, and when to ask again.

$ banshee headroom
WAIT  Shrieking: Swap in use is red — 35.6 GB in use, climbing 74 MB/min (held 1h0m). Wait; retry in 300s.

  recommended parallelism  0
  retry after              5m

Agent-first. One local Rust daemon owns the database. The menu bar app, the banshee CLI and the MCP server are peer clients of it, and the same nine reads exist on all three: pressure, headroom, census, alerts, deltas, samples, rollups, stats and health. By default the MCP server is read-only and safe to hand to any agent; it can preview a cleanup but not perform one. If you want your agent to reap stale sessions and orphaned helpers on your behalf, you enable the execute tools explicitly. Everything stays on the machine: a Unix socket in your own data directory, key-file auth, and no network traffic except an update check you can turn off (SECURITY.md).

It knows about agents. Beyond load, memory, swap, thrash, thermal and disk, it measures two things a general-purpose monitor does not: agent sprawl (stale interactive sessions, IDE-spawned helpers, orphaned helpers) and managed agents (the always-on monitoring software on a managed machine). Every finding names who is responsible, by program, with counts and sizes, and the reap actions work against exactly that list.

It warns you before the crisis, not after. Banshee runs all the time as a background service and notifies you when a condition has been red for long enough to matter. It can do that because it measures trends, not snapshots: swap climbing at 74 MB a minute is a warning an hour before swap is full, and no tool you open after the machine is already slow can see it.

What you see

The Verdict tab: findings, best action first, each naming who is responsible The History tab: five-minute rollups of load with the bucket maximum drawn over the average

The Census tab: stale agent sessions, tmux, orphaned helpers, the biggest apps and the managed agents The Alerts tab: alert episodes with their peak, who was responsible and how long each ran

Every name and number in these screenshots comes from the shared test fixtures, served to the real app by scripts/fixture-server.py. None of it is from a real machine.

The menu bar glyph encodes the level and, from Restless up, the source that is winning:

🫧  Checking      not enough data yet; NOT a claim that anything is fine
😴  Quiet         nothing over threshold
🫥  Stirring      one dimension uneasy
😧  Restless      several uneasy, or a red spike
😱  Wailing       a red sustained past its grace period
💀  Shrieking     two dimensions in sustained crisis

🔥 CPU · 🌡️ thermal · 🧠 memory · 💽 disk · 🕸️ agent sprawl · 🏢 managed agents

Install

Download the DMG from the GitHub Releases page, drag Banshee.app to /Applications, and launch it. The first launch offers to install the daemon, a launchd LaunchAgent built from helpers inside the app bundle. Accept, and the glyph appears once the first samples are in. On that first launch from /Applications the app also adds itself to your Login Items so the glyph returns after a restart; macOS tells you, and Settings › "Open at login" turns it off. The daemon starts at login regardless, because it is a background service the app only reads from. Updates arrive through "Check for Updates…" in the popover (Sparkle, signed appcast); a scheduled check that finds one badges the menu bar glyph. An app update does not touch the daemon — the popover says when the two are different releases and offers to update it.

Requirements. macOS 14 or newer on Apple silicon. The release build is arm64-only. The DMG carries the app, the daemon, the CLI and the MCP server, and needs no developer tools on the machine.

Point an agent at it

The MCP server is Banshee.app/Contents/Helpers/banshee-mcp, a stdio server any MCP host can run. For Claude Code, add it to a project or user .mcp.json:

{
  "mcpServers": {
    "banshee": { "command": "/Applications/Banshee.app/Contents/Helpers/banshee-mcp" }
  }
}

The server talks to the daemon over the local socket and never opens the database itself, so Banshee.app must be installed and the daemon running. Each tool's description states the mistakes agents make with it: checking is not headroom, the recommended parallelism is to be used as given, and a delta across an observation gap is arithmetic on a hole. headroom is advice, not enforcement. The daemon informs, and you decide (ADR-0010).

Ask it

$ banshee status
💀🧠  Banshee: Shrieking, memory

  !! CPU utilization  98% busy, rising 25%/min; 9.5× per core  (held 1h0m)
  !! Swap in use      35.6 GB in use, climbing 74 MB/min  (held 1h0m)
  !  Uptime           12.4 days  (held 1d)

Findings, best action first:
  1. 35.6 GB of swap in use.
     who: Chrome ×115 at 7.7 GB, claude ×8 at 2.1 GB
     → Quit and relaunch the biggest apps
  2. CPU is saturated: cores are 98% busy.
     who: claude ×8 at 62% of one core, managed agents ×13 at 49% of one core
     → Reap stale agent sessions
  3. Up 12 days. Long uptime with pinned swap means fragmented, unreclaimable memory.
     → Reboot

  40 samples, 3 censuses in the window
  2 open episodes, 2 active in the last hour, 3 in 24h  (banshee alerts)

--json on any read returns the same bytes the MCP tool does. The data routes are all reads; the sampler is the only writer. A few authenticated POST routes run local actions (reap preview and execute, backup) and never write data.

The severity is decided once, in banshee-core, and travels over the wire with its glyph. No client re-derives a level or a band, because that is how three surfaces come to disagree about whether the machine is on fire (ADR-0005).

Architecture

A Rust core owns the domain. An Axum API on port 18769 is the only database writer, and the CLI, the MCP server and the SwiftUI app all speak HTTP to it. The API runs as a launchd LaunchAgent, so sampling outlives a closed window, a quit app and a reboot. The app is a client of it, not its supervisor (ADR-0004).

make daemon-install    # install, or update after any change (idempotent)
make daemon-status     # what is actually running, and what is wrong with it

Rebuilding does not update the running daemon; reinstalling does. The LaunchAgent runs an installed copy, never a build artefact. See docs/daemon.md.

Tier Cadence Cost What it reads
Cheap 15s syscalls only, about 170 µs load, memory, swap, thrash rate, free space
Census 5 min 2 ps, 1 tmux, selective lsof agent sessions, orphans, app groups, managed agents

The cheap tier spawns no subprocesses. A literal port of the original script would have spawned about 28,800 processes a day, and monitoring software on a managed machine does work on every spawn, so a monitor that inflated one of its own dimensions would defeat itself (ADR-0007).

The database settles at about 8.4 MB (24 hours of raw samples plus 30 days of rollups). The daemon reports its own footprint and CPU on /stats and in banshee stats, as a lifetime average rather than a burst reading. On the development machine that is about 5 MB and a fifth of a percent of one core.

Privacy

No telemetry, no analytics, no account. Every process here talks only to the local daemon over a Unix socket. Two things can reach the network and nothing else:

  • The daemon never dials out unless you configure a Slack webhook for escalation alerts. It is off by default.
  • The app checks this repository's GitHub Releases for updates on Sparkle's schedule (signed appcast, EdDSA-verified package). This is on by default in a release build, because an update check is how a fix reaches you. Turn it off with defaults write com.tedswinyar.banshee SUEnableAutomaticChecks -bool NO and use "Check for Updates…" by hand. The check discloses the app's version to GitHub and nothing else.

The hosts contacted, the trust model and how to report a vulnerability are in SECURITY.md.

Scope

Banshee is the sentinel, not the explorer. It never walks the filesystem. Disk signals come from statfs per volume, and "what is taking the space" belongs to a disk-usage tool (ADR-0003).

Explicitly not doing

Each of these was considered and rejected for a reason, recorded so the idea is not re-derived without meeting the argument. The full list is in docs/ROADMAP.md.

  • A 0 to 100 health score. One number hides which dimension is failing and invites tuning the number instead of the machine.
  • Memory "purge", "clean" or "optimise". macOS reclaims its own caches. Forcing it trades a real signal for a cosmetic one.
  • An auto-kill mode. Every reap is preview then confirm, by you, against the set you just read. A monitor that kills on its own is the incident.
  • An LLM in the verdict loop. The severity is a deterministic replay of stored history. The MCP server is how agents ask, never how the verdict is made.
  • Widgets, multi-metric menu bars, fan speeds, SMC writes, private IOReport. The glyph is the product. The rest is a different app.
  • Network bandwidth. There is no honest capacity number on Wi-Fi to band against.
  • Disk hotspots. A disk tool's job, see Scope.
  • Mac App Store and brew services. Sandboxing forbids the first, and the second would supervise the daemon a second way.

Build & run

Building needs Rust, the Swift toolchain and jq, plus cargo-deny and gitleaks for the full verify gate (scripts/doctor.sh checks).

./scripts/verify.sh     # the gate: rust (fmt, test, clippy), swift, e2e, scripts
make build              # debug build, Rust and Swift
make install            # daemon and app to this machine, from one commit
make daemon-install     # the daemon half alone, as a LaunchAgent
./scripts/start.sh      # a throwaway dev-profile API in the foreground
./scripts/warm-dev-db.sh          # let it gather enough history to judge

Machine-local configuration, including managed-agent process names that must not enter this repository, lives in census.local.toml under the Banshee Application Support directory or .config/banshee. See docs/signal-collection.md.

Documentation

docs/README.md is the map. The usual entry points:

About

Proactive system-pressure sentinel for macOS — Rust core + menu bar app + MCP.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages