
Tool for managing RAM by tracking RAM usage by Claude sessions and Chrome tabs
Headroom shows what is using your Mac's memory when you work with many Chrome tabs and Claude Code
以下正文同步自 Hacker News 最新,版权归原站所有,已转换为易读排版。
Headroom shows what is using your Mac's memory when you work with many Chrome tabs and Claude Code sessions at once, and lets you close what you no longer need. It lists Chrome tabs, Claude Code sessions and the dev servers that sessions left running after they ended, sorted by memory footprint. You select rows and close them, and you can Undo: tabs reopen (with their history when the helper extension is installed), and sessions resume in a new tmux window.
It is a native macOS Dock app (Swift 6, AppKit, SwiftPM), a headroom CLI that agents can use too, and a small Chrome helper extension for memory per tab. It is for people who keep many Claude Code sessions open, usually in tmux, next to a busy Chrome.
Status: a personal tool, shared as it is. It runs on macOS on Apple Silicon only. You build it from source: there are no binary releases, and the app is not notarized (it is signed locally, ad-hoc or with a self-signed certificate that you make).
Design: docs/SPEC.md, and the design decisions that override it. Wire protocol: docs/protocol.md. CLI: docs/cli.md.
An Apple Silicon Mac with macOS 15 or later (build.sh builds for arm64 only).
A Swift 6.4 toolchain or later (swift-tools-version: 6.4 in Package.swift), from Xcode or the Command Line Tools. The build and the scripts also use codesign, PlistBuddy, plutil, rsync and python3, which macOS and the Command Line Tools provide.
Google Chrome in /Applications for the Chrome section, and Claude Code (~/.claude) for the sessions.
Optional:
tmux at /opt/homebrew/bin/tmux (the Homebrew path) for session locations, Jump and Undo of sessions;
Ghostty, so that Jump brings the right terminal window forward;
AeroSpace (install.sh can add a rule so the Headroom window floats);
openssl for scripts/make-signing-cert.sh (the system LibreSSL works);
Bun and Chrome for Testing, only for the end-to-end tests in Tests/e2e-chrome/.
First run
Do these steps once, in this order. install.sh asks before each step. make-signing-cert.sh and build.sh run without asking. Every script prints what it did.
Make the signing certificate (optional, but recommended):
scripts/make-signing-cert.sh
This puts a self-signed "Headroom Local Signing" identity in your login keychain. With it, macOS remembers the Chrome and Ghostty Automation grants across rebuilds. Without it, build.sh signs ad-hoc and macOS asks again after every rebuild. The first build after this may show a keychain prompt for codesign: choose Always Allow.
scripts/build.sh # -> build/Headroom.app (release, arm64, signed) scripts/build.sh --mock # also opens it with fake data and HEADROOM_DRY_RUN=1, to try it safely
Install:
scripts/install.sh # add --dock to also pin it in the Dock (the Dock is backed up first)
What Where
The app ~/Applications/Headroom.app
The CLI ~/bin/headroom → Headroom.app/Contents/Helpers/headroom
Extension folder for Load unpacked ~/Library/Application Support/Headroom/ChromeExtension/
Chrome bridge file ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/dev.adder.headroom.json
Dock backup (--dock only) ~/Library/Application Support/Headroom/dock-backup-install-<time>.plist
Floating-window rule (only if you use AeroSpace) appended to your aerospace.toml, with a backup next to it
Without --dock: open Headroom, then right-click its Dock icon ▸ Options ▸ Keep in Dock.
Load the Chrome helper extension (for memory per tab; once per Chrome profile):
Headroom's "Set up…" sheet walks through the same steps and ticks them off. The helper cannot read page content, cookies or history: it has no host permissions and no content scripts.
Grant Automation (optional; for the tab list without the extension, and for jumping to the exact Ghostty window). Headroom never asks on its own:
After an update, run scripts/build.sh && scripts/install.sh again. Then click the reload icon on the helper in chrome://extensions if the extension changed.
The Claude sessions, Leftovers, the memory strip and the Chrome section totals work with no setup and no prompts. Per-tab memory needs the extension. The tab list and closing tabs need the extension or Automation ▸ Chrome.
Keys Action
Click, ⌘-click, ⇧-click Select, toggle, select a range (as in Finder)
↑ ↓, ⇧↑ ⇧↓, ⌥↑ ⌥↓ Move, extend, first/last row
→ ←, ⌥→ Expand or collapse a group; ⌥→ expands all levels
⌘A / Esc Select all visible rows / deselect
⌫ or ⌘⌫ Close the selection. It closes at once with an Undo toast. A sheet appears only when a row needs a check (busy, leftover, pinned, last window…)
⌥⌫ Close Now: skip the sheet, except for busy sessions, leftovers and unregistered claude
⌃⌫ Sleep the tab (discard it; extension only)
⌘Z / ⇧⌘Z Undo / redo the last close batch
⌘Y Recently Closed (today's batches, with Restore)
↩ or double-click Jump to the tab or the tmux pane
Space Peek (details; follows ↑/↓)
⌘C Copy URLs, resume commands (cd '<cwd>' && claude --resume <id>) or a leftover's command
⌘⇧R / ⌘O Reveal the cwd in Finder / open the transcript
⌘F Filter, for example idle>2h !busy, >500mb, site:github.com, tmux:hub, is:leftover
⌘R Refresh now
⌘1 / ⌘2 / ⌘3 Show All / Chrome / Claude
⌘W Close Headroom's window (this quits Headroom; it never closes an item)
A fast sweep: ⌘F idle>2h !busy, then ⌘A, then ⌫. Leftovers cannot be undone, so they always ask first. Locked rows (Chrome itself, the session that launched Headroom) can be selected for Peek but are never closed.
All screenshots show the built-in mock data (--mock), in dry run.
~/bin/headroom uses the same data and safety checks as the app. Closes from the CLI go to the same log and Recently Closed list, so the app can undo them.
headroom list # table of tabs, sessions and leftovers, biggest first
headroom list --json --kind sessions
headroom suggest # rule-based close candidates + a ready-to-run close line
headroom suggest --ask # also asks claude -p for a second opinion (never closes anything)
headroom close <id> <id> … # shows the plan, then asks y/N; --yes skips the question
headroom close <id> --dry-run
headroom undo --last # reopen the tab / resume the session
Ids look like tab:812:1101007, session:41000:1790694600 or leftover:7164:1790613600. Items that would need the confirm sheet in the app are refused unless you add --force-confirm. Busy sessions also need --include-busy. Locked items are always refused. Exit codes: 0 ok, 1 error, 2 needs confirmation or refused. HEADROOM_DRY_RUN=1 makes every close a no-op that is logged only. --mock uses built-in fake data. Details: docs/cli.md.
Headroom makes no network requests. The app, the CLI and the native-messaging host have no networking code. The helper extension has no host permissions and no content scripts, and it passes on a tab's favicon only when Chrome already has it as a small data: URL.
The one exception is opt-in: headroom suggest --ask pipes the snapshot (tab titles and URLs, session folders, last prompts and git state) to claude -p, so it goes to Anthropic like any other Claude Code prompt. Incognito tab titles are replaced with (incognito tab), and incognito URLs are left out.
What Headroom writes, in ~/Library/Application Support/Headroom/:
install.sh also writes the files listed under First run. The app keeps its columns, list options and expanded rows in its macOS preferences.
scripts/uninstall.sh # removes the app, CLI link, bridge file, Dock tile, AeroSpace rule scripts/uninstall.sh --restore-dock # puts back the whole Dock from the newest install backup instead scripts/uninstall.sh --purge # also deletes ~/Library/Application Support/Headroom (logs, backups)
It removes only things that are clearly Headroom's. Remove the helper yourself at chrome://extensions. To forget the signing identity: open Keychain Access, find "Headroom Local Signing" and delete it.
Chrome says "Specified native messaging host not found": run scripts/install.sh again, or just open Headroom: at launch it repairs an existing bridge file whose path or id is wrong (not in dry run). A missing bridge file is written by scripts/install.sh.
macOS asks for Automation after every build: the build is ad-hoc signed. Run scripts/make-signing-cert.sh.
Two "Headroom Local Signing" identities: build.sh uses the first one. Pin one with SIGN_ID=<sha1> scripts/build.sh (security find-identity -p codesigning lists them).
Headroom's own cost: the footer shows the app, the host and the helper extension's memory.
Development
Layout
Target (module) Kind Depends on
HeadroomContracts library (shared types) Foundation
HeadroomCore library Contracts
HeadroomClaude library Contracts, Core
HeadroomChrome library Contracts, Core
HeadroomActions library Contracts, Core, Claude, Chrome
HeadroomApp (product HeadroomApp, bundled as Headroom) executable Contracts, Core, Chrome, Actions
HeadroomCLI (product headroom) executable Contracts, Core, Actions
headroom-host executable Contracts
Extension/ MV3 extension –
scripts/ build, install, signing –
Test fixtures: Tests/Fixtures/ (a ps capture in ps.txt and psargs.txt with ownership-overlay.json, and captured tmux output), used by the Core and Claude tests.
Script What it does
scripts/build.sh [--run|--mock] Release build, then assembles and signs build/Headroom.app. Env: SIGN_ID, SIGN_KEYCHAIN, SCRATCH (SwiftPM scratch path), OUT, BIN_DIR (package prebuilt binaries)
scripts/mkicon.swift <out.icns> Draws the gauge icon; --png <px> <out.png> for one PNG (for example extension icons)
scripts/extension-id.sh [manifest] Prints the extension id from the manifest's key
scripts/make-signing-cert.sh [--keychain <kc>] Creates the signing identity (run it once; --keychain <kc> writes to a scratch keychain instead of the login keychain)
scripts/install.sh [--dock] [--yes] [--app <path>] Installs for $HOME; see First run
scripts/uninstall.sh [--restore-dock] [--purge] [--yes] Reverses install.sh
scripts/tcc-probe.sh [--build|--reset] SPEC §10 check, run by hand: builds and opens a tiny app whose osascript child asks for Automation ▸ Ghostty, to confirm the prompt names the app
scripts/dock-tile.py, scripts/_common.sh Helpers for install/uninstall (Dock plist edits work on files only)
Bundle layout: Contents/MacOS/Headroom, Contents/Helpers/{headroom-host,headroom}, Contents/Resources/{AppIcon.icns,ChromeExtension/}, and Info.plist with HeadroomExtensionID. The helpers are signed first (identifiers dev.adder.headroom.host and .cli), then the app. There is no hardened runtime and no sandbox.
swift build HEADROOM_DRY_RUN=1 swift test HEADROOM_DRY_RUN=1 swift test --filter <Target>Tests # one target, for example HeadroomCoreTests
To run several builds at once (for example from parallel agents), give each one its own scratch path, such as --scratch-path .build/<name>, to avoid SwiftPM lock contention.
HEADROOM_DRY_RUN=1 .build/debug/headroom --mock list HEADROOM_MOCK=1 HEADROOM_DRY_RUN=1 .build/debug/HeadroomApp --dump-json scripts/build.sh --mock # assembles build/Headroom.app and opens it with fake data
Test the install scripts only in a scratch home, with a copy of the Dock plist:
defaults export com.apple.dock /tmp/dock-copy.plist # read-only copy HOME=/tmp/hr-home DOCK_PLIST=/tmp/dock-copy.plist scripts/install.sh --yes --dock HOME=/tmp/hr-home DOCK_PLIST=/tmp/dock-copy.plist scripts/uninstall.sh --yes
With a scratch HOME, the scripts write only inside it. They refuse to edit the live Dock unless HOME is your real home, and they never run killall Dock when DOCK_PLIST is set.
HEADROOM_DRY_RUN=1 in every dev and test run. Test signalling only on dummies you spawned; test Chrome behaviour only in Chrome for Testing with a scratch profile; test tmux only with HEADROOM_TMUX_SOCKET=headroom-test. See SPEC §11 and Sources/HeadroomContracts/Env.swift for all test seams.
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。