perf: startup and per-tool-call latency of the daily surface on darwin

[Castrozan]

Same exercise as #114, run on darwin. rin, M-series, macOS 26.1, WezTerm, herdr.

The headline is that the terminal stack needed nothing. #114 fixed it in home/base, so darwin inherited every one of those wins and now measures faster than the numbers that issue closed on. What was left is the agent hook layer, which #114 never looked at because it is not startup at all: it is a cost charged per tool call, all day, on every agent in the fleet.

Measured (median, fresh spawn)

target	darwin	#114 closing number	status
herdr client (herdr list)	7ms	19ms	fine
nvim startup	30ms	268ms	fine
shell login-interactive, clean env	38ms	95ms	fine
claude CLI spawn	87ms	234ms	fine
herdr pane writable	140ms	373ms	fine
wezterm new window	195ms	not measured	fine
codex CLI spawn	301ms	126ms	runtime boot, no config lever
codex MCP initialize	312ms	not measured	connects at session start
chrome-devtools MCP initialize	335ms	~300ms	matches #114's re-measurement
opencode CLI spawn	603ms (337-977)	~950ms	Bun SEA boot, no config lever
claude mcp list	2507ms	not measured	health-checks both servers serially
PreToolUse hook, per tool call	47ms	not measured	fixed, 1f8cb8a
PostToolUse hook, per Edit or Write	52-81ms	not measured	fixed, 1f8cb8a
Stop hook, per turn	56ms	not measured	mostly interpreter floor
SessionStart hook	120ms	not measured	mostly interpreter floor

The shell number needs env -i to be honest. /etc/profile and hm-session-vars.sh short-circuit on __ETC_PROFILE_SOURCED and __HM_SESS_VARS_SOURCED, so measuring from an inherited environment reads 13ms and hides the login tax that #114 item 2 is about.

What was fixed

PreToolUse is registered with a .* matcher, so every Read, Grep, Glob and Bash an agent issues starts a fresh interpreter. That interpreter was bootstrapping sys.path through pathlib, which pulls in urllib.parse, ipaddress and fnmatch for work os.path does with modules the interpreter has already loaded, and then importing all twelve handlers when the tool's matcher could select at most two.

The handler table now names its module rather than binding an imported function, and run_handlers imports one only once the surface and tool matchers select it. The bootstraps moved to os.path, including in the two matcher-less guards that genuinely do load on every call. Measured against a bare interpreter on the same machine, dispatch overhead fell from 1.11 interpreter floors to 0.45. Through the real invocation path a Read went from 47ms to 36ms, and 58 modules now load on that path.

PostToolUse was already narrowed to Skill|Edit|Write in event-to-dispatcher-map.nix, so a Read never spawns it at all. That is the largest structural saving available in this layer and it was already taken.

Two guards hold the result, both in agents/hooks/__tests__/unit/. test_dispatcher_import_budget.py reads the module set each invocation actually imports and fails on an expensive stdlib module, an unmatched handler, a third-party dependency, or a per-invocation count over budget. test_dispatcher_startup_latency.py measures wall time against the interpreter floor measured on the same machine, so its bound travels to CI hardware of any speed.

Measured and rejected

-S skips site and saves 3.7ms on a bare interpreter, which looked like the next win. Interleaved A/B on the real dispatcher put it at -0.04ms: once json and re are loaded the saving is already spent. It was measured back out rather than kept as unpaid risk, since skipping site would also have tied the hooks to staying free of site-packages forever. run-hook.sh kept only exec, which stops a bash process idling for the hook's lifetime.

Dropping re from hook_dispatch in favour of literal alternation matching was rejected for the same reason: json imports re regardless, so the matcher rewrite would have bought nothing.

Remaining work

1. The interpreter floor is now the hook budget. A Read spends 36ms end to end: roughly 10ms in the shell Claude Code spawns the command through, 5ms in the run-hook.sh wrapper, 15ms of interpreter boot, and 6ms of our own imports and work. Going below that means not starting a Python process at all: a resident daemon holding the handlers preloaded, with a small client on the hook command. That trades the cost for a supervision surface and a staleness problem, and these are security guards, so the fail-open versus fail-closed call has to be made deliberately rather than inherited.
2. claude mcp list at 2.5s suggests the two MCP servers are health-checked serially. Worth confirming whether session start pays the same shape, since perf: track startup latency of core terminal and AI apps #114 item 1 measured the servers themselves at ~0.3s each.
3. The darwin shell login tax is unmeasured beyond the 38ms total. perf: track startup latency of core terminal and AI apps #114 item 2 is a NixOS finding, and the darwin split between /etc/profile and hm-session-vars has not been decomposed.
4. There is still no darwin desktop benchmark. benchmark.nix gates benchmark_desktop.py behind pkgs.stdenv.hostPlatform.isLinux because it drives Hyprland, so window and app latency on darwin has no reproducible harness. perf: track startup latency of core terminal and AI apps #114 asked for a reusable benchmark script as a follow-up, and this is the platform where the gap is total.

How to re-measure

Wall-clock medians of env -i bash -l -i -c exit for the shell, --startuptime for nvim, spawn-to-version for the CLIs, a JSON-RPC initialize round trip for the MCP servers, and for the hooks a payload piped into run-hook.sh exactly as settings.json invokes it. The two dispatcher tests above are the parts that now run without being asked.

[Castrozan]

Second pass: the rest of the hook surface

The first pass fixed PreToolUse for a Read and stopped there. Measuring the whole surface the way an agent actually drives it showed the Read was the cheapest thing on it.

invocation	before	after	what it costs per
PreToolUse Read	57 modules	57	every tool call
PreToolUse Bash	80	68	every shell command
PreToolUse Edit	74	61	every edit
PostToolUse Edit	107	63	every edit
PostToolUse Skill	67	53	every skill load
UserPromptSubmit	75	61	every prompt
Stop	106	95	every turn

Module counts are measured under the CI interpreter, so they are the reproducible half. Wall clock on rin, median of 25 through run-hook.sh against a 16ms interpreter floor: a Bash call fell from 42ms to 32ms, and a PostToolUse Edit from 66ms to 48ms on Python, 91ms to 59ms on Nix, 47ms to 36ms on a file nothing formats.

What was costing it

pathlib, still, on every path but the two already fixed. The Bash-matched guards, both Edit-matched routers, all four Stop handlers, the prompt-submit reminder and the shared marker and reminder-state modules each bootstrapped sys.path through it. It bills urllib.parse, ipaddress, fnmatch and math to answer what os.path answers with modules the interpreter already loaded. file_path_components now covers the one thing os.path has no equivalent for, PurePath.parts.

The formatter probed for its own binary before running it. auto_format_handler ran <formatter> --version to decide whether the formatter existed, so every formatted file paid two process spawns instead of one. subprocess.run raises FileNotFoundError for exactly that condition, so the loop now tries each candidate and moves on when it is missing. subprocess itself moved into the call, because a markdown or plain-text edit matches no formatter and was importing it, with selectors, threading and signal behind it, to run nothing.

tempfile.gettempdir for three environment variables. Both session ledgers reached for it and got shutil and fnmatch with it. They were also byte-identical apart from their file name, so they now share session_scoped_path_ledger and keep only their own vocabulary.

One module answering two questions. nix_rebuild_obligation held both "is this a nix file in the dotfiles repo", which the recorder asks on every Edit, and "is a rebuild still owed", which only the Stop handler asks and which shells out to git. Splitting nix_file_location off took subprocess off the Edit path.

What holds it

dispatcher_import_measurement.py now budgets seven invocations rather than five, each at its measured count plus four, replacing the twenty-odd slots of slack Stop, Skill and prompt-submit were carrying. test_dispatcher_import_hygiene.py fails if subprocess or tempfile returns to an edit that formats nothing, and if pathlib returns to a Read or a Bash.

Item 2, answered

Session start does not pay the serial shape claude mcp list does. Watching process spawns during a headless run, both MCP servers appear in the same sampling window, and connecting them by hand takes 359ms in parallel against 924ms serially. claude mcp list still costs 1.5-2.5s, but it is a diagnostic, not on any daily path.

Still open

Items 1, 3 and 4 stand. The interpreter floor is now most of what a hook costs, going below it means a resident daemon and a deliberate fail-open call; the darwin shell login tax is still undecomposed; and there is still no darwin desktop benchmark.

[Castrozan]

Third pass: Hammerspoon and the Cmd+Tab switcher

Item 4 asked for a darwin desktop benchmark because window and app latency here had never been measured. Measuring it
found the window manager charging 142ms for a workspace switch and 64ms for a Cmd+Tab commit, against a Swift switcher
daemon that was already fast. One cause explains almost all of it, and it is the same shape as the two the hook layer
had: an expensive call standing in for a cheap question.

Measured (median, in-process, rin)

target	before	after	pays per
switchToWorkspace	142ms (114-163)	46ms	every workspace hotkey
focusWindowById	64ms (37-121)	19ms	every Cmd+Tab commit
manageableWindows	37ms	3ms	2x per switch, 1x per second
occupiedWorkspaceNumbers	42ms	2ms	every menu-bar render
windowDescriptorsByWorkspace	44ms	6ms	every window menu open
currentWorkspaceWindowList	38ms	4.5ms	the switcher bridge's 1Hz tick
workspace state save	20ms	6.6ms	every switch, create, destroy, commit
Hammerspoon idle	3.25% of one core	1.10%	always

The primitives behind those numbers, measured on the same machine:

call	cost
hs.window.allWindows()	27-40ms, spikes to 96ms
hs.window.get(id)	33-41ms
hs.window.list(false)	1.4ms
hs.window.filter.default:getWindows()	1.8ms

The Swift daemon was already fast

Nothing on that side needed changing, so here are the numbers that close it. Across the 1342 activations its own
profiler had already logged, command to overlay visible ran 19.9ms median and 42ms at p90; across 20 fresh ones it ran
14.4ms. The file IPC to Hammerspoon costs 0.3ms of that and the MRU sort 0.01ms, so the remaining 12.5ms is building
the NSPanel and its cards. Sending the datagram costs 5 microseconds, the daemon has the activation flag on disk 4.5ms
later, and Hammerspoon's hs.pathwatcher fires 0.81ms after an external process writes the focus request. The switcher
half of a Cmd+Tab was never the problem: Hammerspoon's focus step alone cost more than the daemon's entire activation.

What was costing it

hs.window.allWindows() on every path that needed to know a window still exists. It queries every running
application over the accessibility API each time it is called, which its own documentation says, along with the
suggestion to use hs.window.filter instead. The grid called it twice per workspace switch, once for the switch loop
and once again for the menu-bar occupancy render, once a second from the switcher bridge's refresh timer, once per
window-destroy event, and every two seconds from the minimize blocker. hs.window.get(id) is built on it, so resolving
a window id that the switcher had just handed back cost another 33ms.

hs.window.list(false) answers the same question from CGWindowListCreate without touching accessibility at all.
Sampled once a second for 75 seconds, no window allWindows() reported was ever absent from it, the window parked
off-screen at x=-1000000 stays in it, and it rejects every stale entry the window filter carries. Window ids now
resolve through the filter's cached list rather than hs.window.get, which is also the correct set: every id the
switcher or the menu can name came from that list to begin with.

A shell fork to create a directory that already existed. Every workspace-grid save ran os.execute("mkdir -p ...")
before opening the state file. That is a shell plus an mkdir on every switch, window create, window destroy and Cmd+Tab
commit, for a directory that exists on all but the first save after a fresh home. The save now opens the file and only
walks the directory chain with hs.fs.mkdir when that open fails.

A 38ms sweep every two seconds to ask whether anything was minimized. The minimize blocker re-enumerated every
application to find minimized windows, whether or not anything had changed. A window cannot become minimized without
leaving the window server's on-screen list, measured over five minimize and restore cycles sampled at 50, 200, 600 and
1200ms each. Reading that list costs 1.5ms, so the timer diffs it and only pays for the accessibility sweep once an id
it saw before is gone. Sampled every two seconds for 88 seconds of ordinary use, no tick lost an id. The
windowMinimized subscription is untouched and still does the real work.

A bug the measurement turned up

The switcher offered itself as a switch target. The daemon builds a fresh NSPanel per activation, Hammerspoon's window
filter treats that panel as an ordinary window, and the grid adopted it onto the current workspace and wrote it into
the very JSON the daemon reads back. Reproduced live: with the overlay up, the workspace window list carried
id=9879 app=workspace-window-switcher-daemon title=, and it dropped out again once the overlay closed. A Cmd+Tab
inside that window showed a titleless card for the switcher.

The window-server entry the grid already reads carries the owning process name, so the overlay is excluded there at no
extra cost, which also keeps it out of the window menu and out of the workspace assignments. The window server
truncates kCGWindowOwnerName to 31 characters, so the daemon reports as workspace-window-switcher-daemo. That quirk
lives in window_server_truncated_owner_name.lua rather than as an unexplained constant.

What holds it

Four guards, all in home/darwin/desktop/hammerspoon/__tests__/, all plain Lua that CI already discovers and runs.

workspace_grid_window_enumeration_cost_test.lua counts calls to hs.window.allWindows, hs.window.get,
hs.window.find and hs.window.windowForID while driving a switch, a move, a focus, a reveal, a gather and every
window event, and fails on any of them. It also fails if one workspace switch enumerates the window server more than
twice. workspace_grid_persistence_write_cost_test.lua fails if a save spawns a process on either the warm or the cold
path, and still checks that a cold save writes a state file the loader reads back.
prevent_window_minimize_sweep_cost_test.lua fails if a quiet tick enumerates accessibility again, and checks that a
window leaving the screen is still swept and unminimized. workspace_grid_switcher_overlay_exclusion_test.lua fails if
the overlay returns as a card, a manageable window, a focus target or a window-menu entry. Each was checked by
reverting the fix under it and confirming it goes red.

Measured and rejected

hs.window._orderedwinids() is 1.5ms and looked like the cheapest liveness source, but it is private and undocumented,
and hs.window.list is the documented CoreGraphics reader at the same cost, so the private call bought nothing.

Reusing one NSPanel across activations instead of building a new one would cut the 12.5ms overlay render, but the whole
activation is 14.4ms and the panel lifecycle carries more risk than the saving is worth. It stays as measured.

Gating the minimize sweep looked unsafe at first: one probe read a minimized window as still present in the on-screen
list, and the list's own size drifts between 22 and 24 entries as menu-bar extras come and go. Five clean trials at
four sample points each settled the first, and diffing the list every two seconds for 88 seconds settled the second
with zero ticks losing an id, so the gate went in on evidence rather than on the first reading.

Left as measured

The switcher bridge still rewrites its JSON once a second whether or not anything changed, and that tick is now the
largest resident cost at 0.80% of one core, with 0.30% for everything else Hammerspoon does while idle. Measured by
stopping each timer in turn and sampling CPU over 30 seconds. Making it event-driven means giving up fresh window
titles, since no event fires when a title changes, so it wants a deliberate call rather than a quiet swap.

The re-assert timer in karabiner_application_focus_variables.lua spawns karabiner_cli every five seconds behind an
hs.application.watcher that already fires on every focus change. The spawn cost lands on karabiner_cli rather than
on Hammerspoon, so it does not show in the idle number above and was not measured further.

One behaviour change to record: the window server excludes a minimized window from its on-screen list, so a window that
is minimized at the moment of a workspace switch is not parked with the others. Minimizing is blocked globally on this
machine and the windowMinimized subscription undoes it within milliseconds, so the exposure is a few frames, but it
is a real difference from what allWindows() reported.

Still open

Items 1 and 3 stand. The hook interpreter floor still needs a resident daemon and a deliberate fail-open call, and the
darwin shell login tax is still undecomposed. Item 4 is answered for the window manager and the switcher, and the
guards above are the reproducible harness it asked for, though benchmark_desktop.py is still Linux-only.

Commits: 6a8e390, eb088e8, bc5d280, 5beff5c.

How to re-measure

hs -c against a 13ms round-trip floor for anything crossing the IPC boundary, and hs.timer.absoluteTime() inside
Hammerspoon for anything that should not carry it. Hammerspoon's idle cost is a ps CPU-time delta over 30 seconds
with the machine untouched, decomposed by stopping one timer at a time. The switcher decomposes itself: its
ActivationPerformanceProfiler already writes phase timings to /tmp/workspace-switcher-perf.log on every activation,
so driving next and cancel at the socket and reading the new lines gives the split between IPC, sort and render
without instrumenting anything.

[Castrozan]

The switcher bridge is event-driven now, and it cost nothing to keep titles fresh

The previous comment left the 1Hz JSON rewrite as an open trade, on the reading that going event-driven meant giving up fresh window titles because no event fires when a title changes. That reading was wrong. hs.window.filter publishes windowTitleChanged alongside windowCreated, windowDestroyed and windowFocused, so subscribing to all four keeps the list as fresh as the poll did and in fact fresher: a title now reaches the file within the coalescing delay rather than up to a second later.

Measured on rin, Hammerspoon at rest went from 1.10% of a core to 0.32%, which lands on the 0.30% residual the previous comment predicted for everything else. Verified live after the rebuild: the file's mtime does not move across four idle seconds, and moves within a second of an event.

Shape

Window events arrive in bursts, so each one arms a single 150ms one-shot timer rather than writing directly, and a burst collapses into one write.

A workspace switch fires no window event when the target workspace is empty, and would otherwise leave the previous workspace's windows sitting in the file for Cmd+Tab to offer. workspace_grid now publishes its layout changes and the bridge subscribes. The save-to-disk call that every mutation point already made is exactly that signal, so it became onWorkspaceLayoutChanged: persist, then notify. No new call sites, no new bookkeeping.

What holds it

home/darwin/desktop/hammerspoon/__tests__/switcher_bridge_write_scheduling_test.lua, red against the old bridge on five counts: it arms a repeating timer, it writes while idle, it does not collapse a burst, and it misses both the title event and the workspace switch.

Commit 3ea101f1.

Where that leaves the daily surface

Every measured surface on this issue is now either fixed or closed with numbers. Remaining work is items 1, 3 and 4 from the opening comment: the resident hook daemon, which is a deliberate fail-open decision rather than an optimization; the darwin shell login tax, undecomposed beyond its 38ms total; and a darwin desktop benchmark, since benchmark_desktop.py drives Hyprland and is gated behind Linux.

One measured leftover from the Hammerspoon pass also stands: karabiner_application_focus_variables spawns karabiner_cli every 5 seconds behind a watcher that already fires on focus change. The cost lands on karabiner_cli rather than Hammerspoon, so it does not show in the idle number above and was not chased.