Local IPC

The daemon exposes no TCP or public network listener. Its transport is local to the host and scoped to one user session.

Endpoint and permissions

Platform	Default endpoint
Linux	$XDG_RUNTIME_DIR/theme-agent/daemon.sock, with the per-user cache directory as a fallback.
macOS	A Unix socket under the per-user cache directory.
Windows	\\.\pipe\theme-agent-<user>.

Set THEME_AGENT_SOCK to override the endpoint on any platform. Unix socket directories use mode 0700 and sockets use mode 0600. The default Windows pipe security descriptor permits the current user and administrators.

Frame shape

Each frame is one JSON object followed by a newline. A request contains id, method, and optional params:

{"id":1,"method":"set_mode","params":{"mode":"dark"}}

The corresponding response repeats the ID and contains either a result or a structured error. A subscription leaves the connection open and streams tagged event objects.

Methods

• status
• set_mode with { "mode": "light|dark|system|sun|auto" }
• subscribe
• reload_config
• shutdown

Keep protocol and event types in theme-core; the CLI, tray, tests, and external clients depend on their serialized shapes.

Subscription events

Tag	Data
theme_changed	Effective value, previous effective value, source, mode, and timestamp.
mode_changed	Effective value, previous mode, new mode, and timestamp.
config_changed	Timestamp.
daemon_ready	Effective value and mode.

Example theme_changed event, also produced by theme-agent subscribe --json:

{"event":"theme_changed","effective":"light","previous":"dark","source":"system","mode":"auto","timestamp":"2026-06-15T22:08:29Z"}

Security boundary

IPC provides local per-user control, not remote access. The application performs no telemetry, network calls, or geolocation lookups. It runs unprivileged, and its service installations are user-level. Optional hooks run as direct argv without shell interpolation and are disabled unless configured.

Clients should treat the endpoint as a trusted user-session boundary and use the documented JSON contract instead of parsing human CLI output.