# How the AgentsView Auto-Push Watcher Service Operates as a systemd or launchd Daemon

> Discover how the AgentsView auto-push watcher service runs as a systemd or launchd daemon. Learn how it monitors your filesystem and syncs session data to PostgreSQL automatically.

- Repository: [Kenn Software/agentsview](https://github.com/kenn-io/agentsview)
- Tags: how-to-guide
- Published: 2026-07-04

---

**The AgentsView auto-push watcher service runs as a per-user background daemon by installing a systemd unit on Linux or a launchd plist on macOS, which executes `pg push --watch` to monitor your filesystem and automatically sync session data to PostgreSQL.**

The `kenn-io/agentsview` repository implements a cross-platform auto-push watcher that continuously monitors your project directory for changes and streams updated sessions to PostgreSQL. By integrating with native service managers, the tool ensures reliable background operation without requiring manual terminal sessions. The service leverages filesystem events through `fsnotify` and manages its lifecycle through standard CLI commands.

## Service Installation and Unit Generation

When you run `agentsview pg service install`, the CLI detects your platform and generates the appropriate service definition in your user directory.

### systemd Unit Configuration (Linux)

On Linux systems, the CLI creates a per-user systemd unit file at `~/.config/systemd/user/agentsview-pg-watch.service`. According to [`cmd/agentsview/pg_service_systemd.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg_service_systemd.go), this unit configures:

- **ExecStart**: Points to the agentsview binary with arguments `pg push --watch`
- **Environment**: Sets `AGENTSVIEW_DATA_DIR` to your configured data directory
- **Logging**: Redirects stdout and stderr to a log file accessible via `agentsview pg service logs`

The CLI then enables and starts the service immediately using `systemctl --user enable --now`.

### launchd Plist Configuration (macOS)

For macOS, the installation writes a `.plist` file to `~/Library/LaunchAgents/` as implemented in [`cmd/agentsview/pg_service_launchd.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg_service_launchd.go). The plist specifies:

- **ProgramArguments**: Array containing the binary path and `pg push --watch`
- **EnvironmentVariables**: Dictionary with `AGENTSVIEW_DATA_DIR`
- **StandardOutPath/StandardErrorPath**: Paths to the log files
- **KeepAlive**: Boolean set to true to ensure automatic restart on failure

The service loads via `launchctl bootstrap gui/$UID` and starts immediately.

## Daemon Runtime Architecture

Once launched by the service manager, the daemon initializes its watching infrastructure through a specific execution flow.

### Entry Point and Configuration

The `runPGPushWatch` function in [`cmd/agentsview/pg_watch.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg_watch.go) serves as the daemon's entry point. This function performs three critical initialization steps:

1. Loads minimal configuration and creates the data directory if missing
2. Resolves PostgreSQL target connections and applies classifier configurations from `PGPushConfig`
3. Initializes the sync engine with the specified watch paths and debounce settings

### Recursive Filesystem Monitoring

The actual watching mechanism resides in [`internal/sync/watcher.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/watcher.go), which utilizes `fsnotify` for efficient filesystem event detection. The implementation includes:

- **`WatchRecursive(root)`**: Traverses the directory tree and adds watches to all non-excluded directories (skipping `.git`, `node_modules`, and other ignored patterns)
- **`watchIfDir(path)`**: Automatically adds new subdirectories to the watch list when `fsnotify` reports creation events, ensuring dynamic directory structures remain monitored without daemon restarts

### Debounced Push Operations

When the watcher detects file changes, it triggers push operations through the sync engine defined in [`internal/sync/engine.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/engine.go). To prevent excessive database traffic, the system applies a debounce timer (default approximately 500ms) configured via `cfg.Debounce`. This aggregates rapid successive changes into a single push operation, optimizing PostgreSQL write performance when batch file operations occur.

## Service Lifecycle Management

The CLI provides intuitive commands for managing the daemon's lifecycle across both platforms.

Install and start the service:

```bash

# Linux (systemd)

agentsview pg service install
agentsview pg service start

# macOS (launchd) 

agentsview pg service install --launchd
agentsview pg service start

```

Stop and remove the service:

```bash
agentsview pg service stop
agentsview pg service uninstall

```

The `stop` command executes `systemctl --user stop` on Linux or `launchctl unload` on macOS, while `uninstall` removes the unit files from their respective configuration directories.

## Key Source Files

The daemon implementation spans several source files in the repository:

- **[`cmd/agentsview/pg_service_systemd.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg_service_systemd.go)**: Generates and manages the per-user systemd unit file, handling `ExecStart` configuration and environment variable injection.

- **[`cmd/agentsview/pg_service_launchd.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg_service_launchd.go)**: Creates and manages the macOS launchd plist, including `KeepAlive` settings and log path redirection.

- **[`cmd/agentsview/pg_watch.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/pg_watch.go)**: Contains the `runPGPushWatch` function that serves as the daemon entry point, coordinating configuration loading and watcher initialization.

- **[`internal/sync/watcher.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/watcher.go)**: Implements the recursive filesystem watcher using `fsnotify`, including the `WatchRecursive` and `watchIfDir` functions for dynamic directory monitoring.

- **[`internal/sync/engine.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/engine.go)**: Manages the sync operations triggered by watcher events, coordinating PostgreSQL pushes and debouncing logic.

## Summary

- **Cross-platform service integration**: The auto-push watcher installs as a per-user systemd unit on Linux (`~/.config/systemd/user/`) or launchd plist on macOS (`~/Library/LaunchAgents/`)
- **Continuous file monitoring**: Uses `fsnotify` via [`internal/sync/watcher.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/watcher.go) to recursively watch directories and automatically include new subdirectories through `watchIfDir`
- **Efficient synchronization**: Implements debounced pushes (default ~500ms) to batch filesystem events and reduce database load
- **Native lifecycle management**: Standard CLI commands (`install`, `start`, `stop`, `uninstall`) interface directly with `systemctl` and `launchctl`
- **Persistent logging**: Both service definitions redirect output to log files accessible via `agentsview pg service logs`

## Frequently Asked Questions

### Where does AgentsView store the systemd unit file on Linux?

The CLI generates the unit file at `~/.config/systemd/user/agentsview-pg-watch.service` when you run `agentsview pg service install`. This per-user location ensures the service runs with your privileges and starts automatically when you log in, without requiring system-wide root access or modification of `/etc/systemd/system`.

### How does the watcher handle directories created after the daemon starts?

The watcher implements dynamic directory registration through the `watchIfDir` function in [`internal/sync/watcher.go`](https://github.com/kenn-io/agentsview/blob/main/internal/sync/watcher.go). When `fsnotify` reports a new directory creation event, the function automatically adds that path to the watch list, ensuring recursive monitoring extends to newly created subdirectories without requiring a daemon restart.

### Can I run the auto-push functionality without installing it as a system service?

Yes, you can execute `agentsview pg push --watch` directly from your terminal. This runs the watcher in foreground mode using the same `runPGPushWatch` function, performing initial syncs and filesystem monitoring identical to the daemonized version, though it will terminate when you close the terminal session.

### What mechanism prevents the daemon from pushing on every single file change?

The system implements debouncing through the `cfg.Debounce` parameter (defaulting to approximately 500ms) in the watcher configuration. This aggregates rapid successive filesystem events into a single push operation, preventing excessive PostgreSQL write traffic when batch file operations or IDE auto-saves occur.