Debugging

Debugging agate

Restarting the daemon

The quickest way to restart agate is the menu-bar indicator: click the space number in the menu bar and choose Restart agate. The daemon exits immediately and launchd starts a fresh copy.

If the menu bar is unresponsive you can restart from the terminal:

launchctl kickstart -k gui/$(id -u)/org.nix-community.home.agate

The sudo that appears in some examples is not required when restarting your own user-domain service.

To stop agate without restarting:

agate stop

---

Reading the logs

agate writes to two log files managed by launchd:

File	Contents
~/Library/Logs/agate.log	Standard output — startup messages, rule matches, space switches
~/Library/Logs/agate.error.log	Standard error — warnings and errors

Tail both in real time while reproducing a problem:

tail -f ~/Library/Logs/agate.log ~/Library/Logs/agate.error.log

Or watch only errors:

tail -f ~/Library/Logs/agate.error.log

---

Checking daemon status

agate status          # prints "running (pid N)" or "not running"
launchctl list org.nix-community.home.agate

---

Inspecting the live window tree

agate list-windows           # aligned table: id, pid, app, bundle-id, title, ws, mon, layout
agate list-windows --json    # same data as JSON (pipe to jq for filtering)
agate list-workspaces
agate list-monitors

Example — find all windows on workspace 2:

agate list-windows --json | jq '.[] | select(.workspace == 2)'

---

Common issues

Windows not tiling after restart

agate re-applies rules at startup but can only tile windows on Spaces it has already "visited" (SkyLight only exposes AX elements for on-screen Spaces). Switch to each Space once after a restart to let agate catch up.

Rule not matching

1. Run agate list-windows and confirm the APP and TITLE columns show what you expect — the rule regex must match those exact strings.
2. Rules use POSIX extended regex. Test your pattern:

   echo "Zen Browser (Beta)" | grep -E "^Zen"

3. Check the log for [rule] lines to see which rules fired at startup.

Menu-bar indicator missing

The indicator is controlled by space_indicator in your config (default true). If it disappeared after an update, add:

agate.config({ space_indicator = true })

Accessibility permission prompt keeps appearing

Grant agate permission once in System Settings → Privacy & Security → Accessibility, then restart. If the prompt reappears after an OS update, remove and re-add the entry.