DAEMON.md

Daemon Mode

Daemon mode pins an animated fetch at the top of the terminal and keeps looping it in the background, so the shell prompt stays usable below it — without splits or an extra terminal multiplexer.

How it works

When daemon mode is active, xfetch forks to the background: the parent writes its PID to ~/.config/xfetch/daemon.pid and exits immediately, so the shell prompt returns instantly. The child keeps rendering the animation loop pinned at the top of the terminal, reserving the top rows with a terminal scroll region (DECSTBM) and drawing each frame with absolute cursor positioning.

No extra shell configuration is required — everything activates from the JSON.

On Windows there is no fork: the parent renders the first frame and spawns a worker copy of itself that inherits the console, and xfetch --daemon-stop signals a named stop event (falling back to terminating the worker) so the terminal is restored either way. The worker also exits on its own when the shell leaves the console — the Windows equivalent of the pty hangup. Scroll region, absolute rows and cursor save/restore are the same on every platform.

Activation

From the CLI:

xfetch --daemon

Or from the config file:

{
    "daemon": true,
    "logo_animation": {
        "plugin": "animate-logo",
        "style": "frame",
        "fps": 6,
        "frames_path": "~/.config/xfetch/logos/fox.txt"
    }
}

The --daemon CLI flag overrides the daemon config value.

Stopping the daemon

xfetch --daemon-stop

This reads the PID from ~/.config/xfetch/daemon.pid, verifies it is an xfetch process, sends SIGTERM, and restores the terminal (cursor shown, scroll region reset, PID file removed).

On Windows the same command signals the worker's named stop event instead of SIGTERM; if the worker does not exit within a second it is terminated and the terminal is restored from the stop command. The PID is validated against the process image name (xfetch.exe), mirroring the /proc/<pid>/comm check on Linux.

Configuration

Field	Type	Default	Description
daemon	boolean	false	Enable daemon mode.
daemon_min_rows	number	6	Minimum number of terminal rows left free below the pinned block for command output.

Behavior details

• The animation only runs in TTY (interactive) terminals; on redirects or pipes the static logo is shown.
• Requires a logo_animation block with a plugin (e.g. animate-logo); without one, daemon mode does nothing.
• The pinned block is redrawn as a single atomic write per frame, the cursor is restored after every frame (typed input is never disturbed), and the scroll region is re-asserted every frame.
• Terminal resizes (SIGWINCH) are detected and the geometry is recomputed automatically.
• In daemon mode the animation loops indefinitely: duration_ms and loop in logo_animation are ignored. For a finite animation that stops on its own, use "daemon": false.

Terminal height

Tall figures (e.g. cat ~29 rows, matrix ~24 rows) take up almost a whole 30-row terminal and leave little room for command output. The daemon reserves the top rows for the logo and keeps command output in the remaining height below it. Medium-height figures (~13-17 rows) are recommended for standard terminals.

Notes & troubleshooting

• ~/.config/xfetch/daemon.rows stores the pinned block height, available for optional shell integration.
• If the terminal is closed while the daemon runs, the daemon exits on its own: both daemons poll their stdout for the pty hangup and shut down cleanly (terminal restored, PID files removed) instead of lingering as orphans.
• If the PID file is missing or stale, xfetch --daemon-stop reports "No daemon running" and cleans up the stale file.
• A daemon killed with SIGKILL cannot clean up after itself; xfetch --daemon-stop (or pkill xfetch) clears the leftover file.

Live Stats Daemon

The live stats daemon (daemon_live) is a sibling of the animated-logo daemon: it pins the fetch block at the top of the terminal and re-probes a lightweight subset of modules every few seconds, re-rendering the block with fresh values (cpu, memory, swap, disk, battery, uptime, datetime). Your fetch stops being a static snapshot and becomes a live panel — think "conky pinned at the top", not an interactive btop.

The existing animated daemon is untouched: the two modes are independent and share the same pinning/scroll-region machinery.

Activation

{
    "daemon_live": true,
    "daemon_live_refresh": 2
}

Activation is config-only; the terminal flags only disable/stop/force:

xfetch --no-daemon-live       # disable even if the config enables it
xfetch --daemon-live-stop     # stop the running live daemon
xfetch --daemon-live-reload   # force hot reload (same as "daemon_live_reload": true)

Configuration

Field	Type	Default	Description
daemon_live	boolean	false	Enable the live stats daemon.
daemon_live_refresh	number	per-platform	Seconds between refreshes. Defaults to the platform policy (platform/<os>/live.rs): Linux 2, macOS 3, Windows 5.
daemon_live_modules	array	per-platform	Modules shown (and refreshed). Defaults to the platform's live set: Linux/macOS cpu, memory, swap, disk, battery, uptime, datetime; Windows excludes battery (opt-in) unless you add it back.
daemon_live_reload	boolean	false	Hot reload: watch the config file (and the active theme) and re-apply changes — modules, colors, icons, layout, logo, refresh cadence — without restarting the daemon. Equivalent CLI flag: --daemon-live-reload.

Behavior details

• If logo_animation is configured, the logo keeps animating while the content refreshes live; otherwise the logo is static.
• Only the modules in daemon_live_modules are probed on each tick — heavy work (packages, public IP, plugins) is never re-run.
• The PID file is ~/.config/xfetch/daemon_live.pid, separate from the animated daemon's; --daemon-live-stop targets it.
• Resizes are handled like the animated daemon; daemon_min_rows applies to both.
• Hot reload checks file mtimes (config + theme) on a light poll; edits are picked up within ~100 ms. Re-applying also re-runs config providers (extensions) and, when the animation settings changed, re-spawns the logo plugin. To stop the daemon, still use --daemon-live-stop — setting daemon_live back to false does not stop a running daemon.