Reference

peekaboo daemon

Home GitHub Edit page

peekaboo daemon

Manage the on-demand headless daemon that keeps Peekaboo state warm, tracks windows live, and serves bridge requests.

The default listener is ~/Library/Application Support/Peekaboo/daemon.sock, separate from Peekaboo.app's bridge.sock.

After upgrading from a version that used bridge.sock for the daemon, default status, start, and stop commands detect that legacy daemon by its daemon status. Peekaboo.app is never treated as a daemon.

Normal automation commands migrate legacy auto or manual daemons that advertise atomic conditional stop. The daemon keeps its prior lifecycle mode, poll interval, and auto idle timeout, so a manually started daemon remains manual after migration. MCP sessions remain process-owned and are never migrated. When bridge.sock belongs to a healthy Peekaboo.app GUI host instead, normal commands keep using that app-held TCC context and start the reusable daemon only if the app host is unavailable or lacks the required capability. Automatic migration defers while operational requests are active and keeps using the legacy daemon for that invocation. Older daemons without conditional stop remain on bridge.sock until they exit or are explicitly stopped. Explicit daemon start asks the user to stop those older daemons first, and asks for a retry when supported daemons are busy. If an incompatible daemon already owns daemon.sock, automation uses a build-scoped fallback. Default status reports the compatible fallback and warns about the additional daemon; start promotes an idle, safely stoppable fallback from auto to persistent manual mode on the same socket.

#Commands

#Start

peekaboo daemon start

Options:

  • --bridge-socket <path> override the default daemon socket path.
  • --poll-interval-ms <ms> window tracker poll interval (default 1000ms).
  • --wait-seconds <sec> how long to wait for startup (default 3s).

#Status

peekaboo daemon status

Shows:

  • running state + PID
  • bridge socket + host kind
  • activity state (active requests, last activity, idle timeout/deadline)
  • permissions (screen recording / accessibility / automation)
  • snapshot cache summary
  • window tracker stats (tracked windows, last event, polling)
  • browser MCP state (connected, tool count, detected Chrome count)

#Stop

peekaboo daemon stop

Options:

  • --bridge-socket <path> override the default daemon socket path.
  • --wait-seconds <sec> how long to wait for shutdown (default 12s, above the Bridge request deadline).

#Notes

  • Normal automation commands auto-start the daemon in auto mode when the default daemon socket is unavailable.
  • Auto-started daemons exit after an idle timeout (default 300 seconds), while explicit peekaboo daemon start remains manual and stays up until stopped.
  • The daemon uses an in-memory snapshot store for speed.
  • Set PEEKABOO_DAEMON_IDLE_TIMEOUT_SECONDS to tune the auto-start idle timeout.
  • Set PEEKABOO_DAEMON_SOCKET to override the auto-start daemon socket for testing.
  • For local development with unsigned binaries, set PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1.