Install path: LaunchAgent, Homebrew formula, zshrc instructions #5

closed cmc opened this on 2026-09-04 03:56 UTC · milestone v1.0.0

cmc 2026-09-04 03:56 UTC

README describes signald as a "user LaunchAgent" but nothing in the repo provides one. Today a user has to read source to run anything.

Done when:

  • A launchd plist (e.g. packaging/net.krz.signald.plist) runs signald at login with the hardware collector child, logging to ~/Library/Logs/signald/.
  • homebrew-tap has a formula that installs signald, terminal-garden, macos-collector, the plist, and signald-hooks.zsh, with brew services support.
  • README has an install section: brew install, brew services start, the one line to add to .zshrc, and how to point signald at repos to watch.
  • Default socket, db, and spool paths are documented in one place and agree between signald/src/main.rs, terminal-garden/src/main.rs, and shell-hooks/signald-hooks.zsh.

referenced in commit ff9638c614 by cmc: Add an install path: LaunchAgent, repos config, and documented defaults

2026-09-04 14:36 UTC

referenced in commit 6c80ae694b by cmc: Give signald and terminal-garden --help and --version

2026-09-04 14:43 UTC
cmc 2026-09-04 14:51 UTC

All four items done.

LaunchAgentpackaging/net.krz.signald.plist runs signald at login with the collector as its child, logging to ~/Library/Logs/signald/. Its header carries the sed and launchctl load lines for a manual install.

Formulakrz/homebrew-tap!4, pinned to v0.6.1. Installs signald, terminal-garden, macos-collector, the plist and signald-hooks.zsh, with a service block for brew services. Verified locally: brew audit --strict clean, brew install --build-from-source succeeds, brew test passes, and the generated launchd plist has RunAtLoad, KeepAlive and both log paths. The repository had to become public first — a tap formula cannot clone a private repo over HTTPS.

README — Install section with brew install, brew services start, the .zshrc line, and how to name repositories to watch.

Paths — a Paths table in the README is now the single place the socket, db and spool defaults are written down; unit tests in both binaries pin the code to it, including that the spool matches SIGNALD_SPOOL in the zsh hook.

Two things landed beyond the list, both because the install path does not work without them:

  • signald reads ~/.config/signald/repos when given no repository arguments. launchd starts an agent in /, so brew services start would otherwise collect no git signals at all.
  • signald had no --help, and any unrecognised argument became a repository path, so signald --help started the daemon watching a directory named --help. Both binaries now have --help and --version; an unknown option exits 2.

Verified end to end with the Homebrew-installed binaries: signald self-attests with all four collectors enabled and terminal-garden renders live off the socket.