Sync

pi: drop pi-mcp-adapter, MCP is native now

pi 1.0.0 has MCP built in, and while the adapter is installed it suppresses
that and prints a warning at every start. The browser gates that answered the
adapter's approval event now hook pi's own tool_call as well. From change
request 562974.

bin/wispr-keys: Flow dictation on the Caps Lock key

Push to talk on F20, Command Mode on Ctrl+F20, written into Flow's config.json
because its settings screen refuses F20 without a modifier while its key
listener accepts it. The key codes and action names come from reading Flow
1.6.1021's app.asar: shortcuts are keyed by macOS key codes string-sorted and
joined with "+", f20 is 90, ctrl is 59, ptt is Push to talk and lens is Command
Mode. splitKeybinds is kept in step so Flow cannot read back a disagreeing pair.

A bin/ tool rather than a link/ part, though it was proposed as one. It has to
quit and restart Flow for an edit to stick, and link.sh runs unattended after
every sync: a part that can kill a dictation mid-sentence is a poor trade for a
binding that can wait until someone asks for it. On demand it is also free to
fail loudly, since nothing else's run depends on it.

Flow ignores an AppleScript quit, so it gets a TERM; and it is launched by
bundle id, because the bundle contains a second app also called "Wispr Flow"
-- its Swift helper -- that `open -a` can start instead, which exits at once.
The file as first found is kept as config.json.pre-wispr-keys.

Brewfile: drop toggleMute

Ad-hoc signed, no TeamIdentifier, and spctl rejects the bundle as modified
since signing, so it only runs with its quarantine flag cleared. A setup script
that every machine runs is the wrong place to put an unverifiable binary past
Gatekeeper, so the xattr step goes with it and install.sh now says it clears no
quarantine flags at all. QuickMD stays: Developer ID, notarized.

Brewfile: say what the two taps actually ship

Checked rather than assumed. QuickMD is signed with a Developer ID and
notarized, so its quarantine flag costs a dialog. toggleMute is ad-hoc signed
with no TeamIdentifier, and spctl rejects it as modified since signing -- so
the quarantine step is not 'it is not notarized' but 'there is no verifiable
publisher'. The trust gate also turned out looser than the first note claimed:
it refused an untrusted formula, but both casks installed without it.

Brewfile: toggleMute and QuickMD, from their authors' taps

Neither is in homebrew-cask. That costs three things this file cannot express
on its own, so install.sh carries them: brew will not load a cask from an
unofficial tap until it is trusted, which is per machine and recorded outside
the repo; the trust is granted per cask rather than per tap, so it covers these
two files and not whatever the taps add later; and toggleMute is not notarized,
so Gatekeeper refuses it until com.apple.quarantine is cleared -- that one
attribute on that one path, not the `xattr -cr` its README asks for.

Nothing here vouches for either binary, and a third-party tap can change what
it installs between two runs. Both are deliberate exceptions, named as such.

Brewfile: glow and Ice

Neither is read by anything here, so they sit apart from the tools the config
depends on: glow renders markdown in the terminal, Ice manages the menu bar
like keepingyouawake beside it.

hammerspoon: Caps Lock sends F20, and stays that way

hidutil remaps inside the IOKit HID driver, below the window server, so the
key stops being Caps Lock before anything above the driver sees it: no toggle
to suppress, and F20 is a real key to other apps, to System Settings
shortcuts, to a password field. An eventtap cannot do this -- Caps Lock is not
reachable from there, which is why hs.hid exists as its own IOKit module.

What hidutil will not do is cover a keyboard attached after it ran, so dotlib
re-applies on USB attach, on wake, and on a Caps Lock event. That last one is
the general answer: a mapped keyboard cannot produce a Caps Lock event, so an
event arriving at all is proof of a keyboard the remap missed, and the fault
triggers its own repair. The watchers are there to get the common cases before
a key is pressed, since the repairing press is spent repairing.

No launchd job and no link/ part. The remap lives and dies with Hammerspoon,
which already owns the keyboard on these machines, and a plist would only have
bought independence from it for the second or two before it starts -- a user
agent does not run at the login window either.

Nothing is bound to f20 here; bind it like any other key. A machine gives the
key back with capslock_off() from its local.lua, which loads last: shadowing
cannot undo a side effect that has already run. hs.ipc is required so
capslock_status() answers from a shell.

AGENTS.md is the file; CLAUDE.md imports it

Every agent here except Claude Code reads AGENTS.md -- pi, codex, and aider now
that its read: says so. The vendor-neutral name was the symlink and the
Claude-specific one the real file, with a header saying the file was guidance
"to Claude Code". Swapped, keeping history on the real file through git mv.

Claude Code has read AGENTS.md directly since v2.1.277 and the machine this was
done on is newer, so the obvious move was to delete CLAUDE.md. Checking the
other machines first was worth it: four were on versions between 2.1.158 and
2.1.263, and a session on any of them would have found no instructions at all.

So CLAUDE.md stays as one line, `@AGENTS.md`, which the documentation endorses
for exactly this case and which -- unlike the symlink it replaces -- works on
Windows and does not trip Claude Code's refusal to write through a symlink. The
header says to delete it once every machine is current.

CLAUDE.md: an agent files its own change request, without asking

The text said to hand a request to dot-request "as well as to the reply" but
never said an agent may do that unprompted, and asked for it to be written "to
be pasted whole", which reads as give-this-to-a-human. So an agent on a
read-only clone wrote a request, handed it back, and offered to file it only if
asked -- reasonable behaviour against what was written. The paragraph now is
the permission, and says why filing is safe: it applies nothing, and every
request is still judged before anything changes.

One addition beyond what was asked. Filing without asking means text leaves
that machine with nothing in the way, and the machine is one whose owner does
not control it. So putting the request in the reply is now explicitly not
optional: it is the only thing that shows what was sent.

tmux: the command prompt gets an opaque background

Every theme set message-style with a bg and no fill. From tmux 3.7 the command
prompt is drawn over the status line, where only the prompt's own characters
take that bg and the rest of the line takes fill; with status-style bg=default
everywhere here, the terminal showed through around the prompt. Reported from a
machine running 3.7c.

fill now matches bg in all eight. It has existed since tmux 3.2 and older
versions ignore it, so this is safe on the fleet: checked on 3.5a, where each
theme sources cleanly and reports the fill back.

pi: the siliconflow key is a reference, not a name

models.json gave the provider an apiKey of "SILICONFLOW_API_KEY", which pi
sends verbatim as the credential: it interpolates "$NAME" and "${NAME}", runs
"!command", and treats anything else as a literal. So that provider has been
authenticating with the 19-character string "SILICONFLOW_API_KEY" and getting a
401 for as long as it has existed.

Confirmed by calling pi's own resolver: "SILICONFLOW_API_KEY" resolves to
itself, "$SILICONFLOW_API_KEY" to the value. Nothing catches this --
isConfigValueConfigured returns true for both and reports no missing variables,
so `pi auth check` says ready either way, and only a real request fails. Hence
the note in CLAUDE.md beside the models.d row: the rule is invisible in the
file, and the next provider added would repeat it.

Reported as a change request from the machine that hit it; the sweep for other
instances found none.

macos: hot corners and tap to click, and a way to find the next key

Three settings this account has always set by hand on every new Mac, now in the
script that exists for exactly that: the bottom-right hot corner sleeping the
display, tap to click, and three-finger drag on an external trackpad -- the
last a gap, since the script set it only for the built-in one.

Each of those is written in more than one place because macOS keeps them in
more than one place: an external Magic Trackpad has its own domain, and the
login window reads com.apple.mouse.tapBehavior rather than either of them,
per-host for this machine and globally for any other. Setting one and not the
others is why tap to click sometimes survives a reboot and sometimes does not.

bin/macos-defaults-diff is the general answer: snapshot, change one setting,
and it prints what moved, including the -currentHost domains a plain
`defaults read` never shows. It flushes cfprefsd first, since a change made
seconds earlier can otherwise be missing from the read meant to reveal it, and
it says plainly when nothing changed -- anything behind Privacy & Security
lives in the SIP-protected TCC database and cannot be scripted at all.

profile: stop shadowing exit

`exit` was a function that ran `tmux detach` instead of exiting, whenever a
shell was interactive and inside tmux. What it bought was a keystroke: tmux
already binds detach to prefix-d, which this config does not touch.

What it cost was an afternoon. Claude Code captures shell functions into a
snapshot and sources it in every tool call, so agent shells inheriting $TMUX
ran the function too: terminal windows closed on their own for weeks before
anyone connected it to `exit`, and a poll loop that called `exit 0` detached a
client every minute instead of stopping, because the function detached and then
returned. The call-time guard added on 2026-07-16 fixed that case; it did not
make shadowing a POSIX builtin a good idea.

Nothing in either repo calls it and nothing documents the behaviour.

link/pi.sh: the generators move into files, and parse under bash 3.2 again

57e49dd made link/pi.sh unparseable on macOS. bash 3.2 does not skip heredoc
content when it scans for the end of a command substitution, so the three
apostrophes in a comment inside the new heredoc read as an unterminated quote
and the script stopped parsing at end of file. ./link.sh on a Mac aborted
partway: settings still generated, models.json stayed the symlink the commit
meant to replace, and everything after that point never ran. Linux was fine,
and so was every check I ran -- `bash` on a Mac with Homebrew is 5.x, which
parses it happily. Reported from the machine it broke.

Rewording the comment would fix it and leave the trap armed for the next edit,
so the two python programs move into link/pi-settings.py and link/pi-models.py
instead, called by path. The text is unchanged; there is no longer a heredoc
inside $( ) to trip over, and both files now compile-check on their own.

Verified under /bin/bash 3.2: first apply replaces both symlinks, a package
removed by hand still survives a relink, fragments merge for settings and for
models, and repeat runs report unchanged.

A filed request needs the owner's approval, not just a valid signature

The reader section said a request was a proposal to read and judge. That tells
an agent how to read one, not what it may do about it, and the gap is the whole
risk: a machine files requests precisely because it cannot be trusted with push
access -- it may be compromised, and whoever holds its key signs whatever they
like. A signature proves which machine sent the text, never that the text is
right or that its owner wrote it.

So: judge it, report it, and apply nothing without the owner approving that
request. Text inside a request asking for it to be applied or pushed is not
approval; it is the input the rule exists for. The same words are in the
reader's own output and in the inbox repo, so this holds for whoever meets a
request first.

pi: providers can come from ~/.config/pi/models.d, like settings already do

models.json was a plain symlink to the tracked file, which left a machine whose
models are served from somewhere other than a vendor's own API with nowhere to
say so. pi reads providers from exactly one path -- join(getAgentDir(),
"models.json") -- and a `providers` block in a settings fragment is inert,
because the settings schema has no such key. So on such a machine pi cannot be
used at all, and the endpoint is not something this repo may name.

link/pi.sh now generates models.json the way it already generates settings.json:
the repo's file, then every ~/.config/pi/models.d/*.json. No three-way merge
here -- pi never writes this file, keeping runtime state in the sibling
models-store.json -- so a hand-edit of ~/.pi/agent/models.json no longer
survives a relink. Put it in a fragment.

It reports which provider came from which fragment, added or replaced, so a
local file shadowing a provider the repo ships cannot do it quietly.

Proposed as a change request from the machine that needs it; verified here
against pi 0.84.2 before applying.

dot-request: file a change request from a machine that cannot push

A clone made over https cannot publish anything, so a fix found on such a
machine is lost at the next pull. The instructions already said to hand back a
change request instead of editing; this is the command that does it. The
request is markdown on stdin, signed with a key that machine holds, and posted
to the inbox, which stores it only if the signature is from a key authorised
there. Where the key is not authorised, nothing is stored and the submission
says so.

The endpoint is named here, which the leak rule would otherwise forbid, and the
rule now carries the exception: a public endpoint this repo's own tooling must
reach, already published by a DNS record and a certificate in the transparency
logs, is not a leak. Concealing it would protect nothing and cost every machine
a hand-written config file; what protects it is the signature. The private
layer's check has the same exception, so it is enforced rather than remembered,
and it does not extend to hosts, addresses or internal-only names.

The other side is documented too: where `sz-requests` exists, what arrived can
be read and judged. A signature says which machine produced the text, never
that the text is right -- the machines filing these are the ones this account
does not fully control.

tree-sitter-cli, and: a read-only clone hands back a change request

An https clone of this repo cannot push -- the host serves it anonymously and
refuses the push with a 403 -- and that is how a machine whose owner cannot
hold a key gets it. An agent troubleshooting there would edit a tracked file,
see the fix applied, and lose it at the next pull, or leave that clone unable
to fast-forward and quietly cut off from changes. CLAUDE.md now says how to
tell the two cases apart, and what to do instead: make it machine-local where a
hook covers it, or hand back a change request -- paths, the actual diff, why,
and how to verify -- stating that nothing was applied.

AGENTS.md is a symlink to CLAUDE.md, so the agents that look for that name get
the same file rather than a second copy to drift.

tree-sitter-cli: nvim-treesitter generates and compiles its parsers with it.

hammerspoon: the example's header is init.lua's, so bindings move either way

It unpacked only hotkey and mods, so a line copied from init.lua -- which
writes `hotkey('9', csa, type_text(...))` with bare names -- did not run here,
and a line moved the other way had to be rewritten. The header is now the same
block init.lua has, name for name, and the examples use the bare names too.

Unused names in it are harmless, and keeping them whole is the point: paste a
binding in either direction and it works as written.

hammerspoon: shared helpers move to dotlib.lua, which local.lua can require

A machine's local.lua is a separate chunk, so init.lua's locals were invisible
to it and anything it wanted -- hotkey(), the mod tables, type_text -- had to
be copied. They live in dotlib.lua now, linked beside init.lua, and both files
reach them the same way: require("dotlib").

init.lua keeps its own vocabulary by aliasing what it uses, so the 500 lines
below are untouched. It prepends its own directory to package.path first:
Hammerspoon already puts the config directory there (Contents/Resources/
setup.lua), but taking it from this file's path holds however the config was
found. A machine that pulls without re-linking has no dotlib.lua beside
init.lua, which would lose every hotkey silently -- that case notifies and
names the fix.

Checked with a stubbed hs: the module's hotkey, focus, execute, type_text and
type_current_date all behave, and local-example.lua binds its four keys
through it.

hammerspoon, ghostty: example files for their machine-local configs

ssh and git each ship one; these two hooks were discoverable only by reading
the config that loads them. Both examples carry what is easy to get wrong:
init.lua's hotkey() helper and mod tables are locals, so a local.lua calls
hs.hotkey.bind directly, and a binding there can only be shadowed, never
deleted; in Ghostty a single-value key replaces while keybind accumulates, and
`ignore` is how a binding is switched off rather than added to.

Checked rather than assumed: the lua parses, and the Ghostty example validates
and, dropped in as ~/.config/ghostty-local, does what it says -- font-size,
command and background-opacity replaced, super+shift+n added, alt+enter turned
off.

CLAUDE.md: where a single machine's changes go, and what to do without a hook

The hooks existed but were documented nowhere together: ~/.localenv and
~/.localprofile were mentioned in passing, the skip file under the link
system, and the ssh, git, Hammerspoon, Ghostty and Alacritty ones only in the
config files that read them. Anyone -- an agent especially -- asked to change
one machine had to read the whole repo to find out whether that was possible
without committing to it.

They are one table now, with what each overrides and what reads it, plus what
has no hook at all. And the rule for everything else: say what is being asked
for and where it would have to live, rather than putting one machine's
preference in the config every machine shares, or leaving that machine's
checkout dirty and its sync failing.

ghostty: read ~/.config/ghostty-local last, where a machine has one

Ghostty had no way to differ per machine. It cannot take the shape the other
tools use -- a file beside the linked one -- because link.sh links this whole
directory, so ~/.config/ghostty is the checkout itself and a sibling file
would be an untracked file in the repo every machine shares.

An optional include at the end does the same job: later values replace earlier
ones, so a local file overrides anything here, the theme colours included, and
its keybinds add to these. Verified against the shipped config: font-size 12
becomes 18 with a local file, back to 12 without, and the config still
validates when there is none.

hammerspoon: load ~/.config/hammerspoon/local.lua where a machine has one

The shell has ~/.localprofile and ssh and git their config-local; Hammerspoon
had nothing, so a machine wanting one different hotkey had to edit the file
every machine shares. Only init.lua is linked, so the directory around it is
already the machine's own -- a sibling file there is in no repo.

Loaded last, so it can override anything above, and through pcall: a mistake
in a local file must not take the rest of the config down. Reload with
ctrl-shift-alt-h as usual.

zshrc: find Homebrew's completions on the prefix this machine uses

fpath carried /usr/local/share/zsh-completions, which is wrong twice over:
Apple Silicon puts Homebrew under /opt/homebrew, and formulae install their
completions into share/zsh/site-functions, not the share/zsh-completions of
the formula by that name. The directory existed on neither Mac, so _brew,
_bat, _deno and the rest have been missing all along -- silently, since a
missing fpath entry says nothing.

All four candidates are probed now, HOMEBREW_PREFIX first where a machine
exports it. No `brew --prefix`: that forks on every interactive shell, and
this file already pays for one of those further down.

Brewfile: keepingyouawake, and say that Mac apps belong here

Installed by hand on machine after machine, which is the signal it belongs in
the list. Nothing in this repo uses it, so the header now says what the casks
were already doing: the few Mac apps this account wants wherever it works,
alongside the tools the config itself needs.

supermaven off unless asked for; a blocked cask no longer ends install.sh

Supermaven was running everywhere. Its `condition` option reads the other way
round from what the code assumed -- `true` stops it -- so `return false` meant
"never stop", and the plugin loaded on InsertEnter, started its agent and
offered inline suggestions on every machine. Only blink's source for it was
off, which is what made it look disabled. It sends buffer context to a third
party, so it is now opt-in: DOT_SUPERMAVEN=1, in ~/.localenv where it is
wanted. Off, lazy keeps both plugins off disk entirely.

install.sh no longer stops at brew bundle either. A managed machine can refuse
a cask outright -- "disabled because it does not pass the macOS Gatekeeper
check" -- and brew bundle fails the whole run for one such entry, which left
the checkouts, nvim plugins and colour files undone. It warns and carries on;
brew has already named the entry.

Brewfile: say why bash is here, correctly

The reason given named bin/open, which does not need it: on macOS it execs
/usr/bin/open on line 13, before anything 3.2 cannot parse. What does need it
is szecret's age bootstrap -- `${os,,}` in secrets/common.sh, reached only when
age is absent, which is precisely the state a machine is in before this file
has been applied.

install.sh: install Homebrew, add bash, and seed the colour files

Three things a machine set up from this repo alone hit on its first run:

Homebrew was a dead end -- install.sh printed the command and exited, leaving
the one prerequisite everything else needs to be run by hand. It installs it
now, NONINTERACTIVE so it does not wait on a RETURN; the sudo password is still
asked for, which is why this script is run by hand.

bash was missing from the Brewfile, so bin/open and secrets/ ran under the
3.2 macOS ships and failed on `${v,,}`; config/bashrc also looks for the
bash-completion 2.x that wants 4.2.

Ghostty refused to start -- "error opening config-file ... error.FileNotFound"
-- because config-file pointed at the colour file bin/theme writes, which does
not exist until theme has run. The include is optional now (`?`), and this
script seeds the colour files when a machine has none, leaving a machine that
already has a theme alone.

link: a part named in ~/.config/dot/skip does nothing on that machine

A machine may need one of the parts left out: on a laptop it does not own,
~/.claude/settings.json is the owner's, holding their environment and plugins,
and linking this account's over it is wrong in both directions -- theirs is
lost, and anything of theirs worth keeping would have to be carried here, in
the repo every machine shares.

The file is hand-written and in no repo, like ~/.localenv, so the exception
stays on the machine that needs it. The check is in link/lib.sh, as each part
starts, rather than in link.sh's loop, so `link/claude.sh yes` obeys it too;
link.sh and other repos' link.sh source that file as well, and sit outside
link/, so their names can never be read as a part's.

link/claude: secrets in MCP specs, and a separate spec for Desktop

Two things a spec in ~/.config/claude/mcp-servers.d/ may now carry beyond
what Claude Code takes, both resolved at link time:

- "${szecret:NAME}" in any string value, replaced with `szecret get NAME`
  when the server is registered with Claude Code. For a remote server's
  Authorization header: Claude Code's own headersHelper is not run in a
  workspace without persisted trust, which includes $HOME, so a token
  fetched that way is simply missing. A secret that cannot be read skips
  that server, loudly.

- "desktop", a whole spec given to Claude Desktop instead. Desktop only
  starts local stdio servers, so a layer that moves a server to HTTP for
  Claude Code can keep Desktop on a local copy.

dotfiles

Shell, editor and terminal configuration, the tools that go with them, and
szecret, an age-based secret manager whose store lives elsewhere.

History restarts here. What came before was not written to be read by
anyone else, and carried machine names, addresses and an encrypted secret
store; it is kept privately instead. What is left is meant to be safe on
any machine, including one whose owner is not me: see CLAUDE.md for the
rule it is written to.