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

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, 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. 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 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, 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. 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:

# 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:

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: Generates and manages the per-user systemd unit file, handling ExecStart configuration and environment variable injection.

• 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: Contains the runPGPushWatch function that serves as the daemon entry point, coordinating configuration loading and watcher initialization.

• 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: 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}