{"id":50351195,"url":"https://github.com/marcomc/pcloud-drive-watchdog","last_synced_at":"2026-05-29T21:01:38.588Z","repository":{"id":355028070,"uuid":"1222536364","full_name":"marcomc/pcloud-drive-watchdog","owner":"marcomc","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-01T13:03:07.000Z","size":18,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T15:06:15.885Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcomc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-27T13:11:48.000Z","updated_at":"2026-05-01T13:02:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/marcomc/pcloud-drive-watchdog","commit_stats":null,"previous_names":["marcomc/pcloud-drive-watchdog"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/marcomc/pcloud-drive-watchdog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fpcloud-drive-watchdog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fpcloud-drive-watchdog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fpcloud-drive-watchdog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fpcloud-drive-watchdog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcomc","download_url":"https://codeload.github.com/marcomc/pcloud-drive-watchdog/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcomc%2Fpcloud-drive-watchdog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33670211,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-29T21:01:36.794Z","updated_at":"2026-05-29T21:01:38.562Z","avatar_url":"https://github.com/marcomc.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pCloud Drive Watchdog\n\nA small macOS LaunchAgent that watches pCloud Drive and restarts it when the\nvirtual drive stops behaving like a mounted cloud drive.\n\nThis project is not affiliated with, endorsed by, or supported by pCloud AG or\nthe official pCloud Drive application. It is only a companion workaround for a\nfailure mode that should ideally disappear once the official macOS client is\nstable.\n\nCurrent version: `0.1.0`.\n\n## Table of Contents\n\n- [Problem](#problem)\n- [What It Does](#what-it-does)\n- [Requirements](#requirements)\n- [Install](#install)\n- [Reconfigure](#reconfigure)\n- [Uninstall](#uninstall)\n- [Configuration](#configuration)\n- [Script Interface](#script-interface)\n- [Logs](#logs)\n- [Troubleshooting](#troubleshooting)\n- [References](#references)\n- [License](#license)\n\n## Problem\n\nSome macOS users have seen pCloud Drive appear in Finder while the virtual drive\nis empty or not actually mounted. In that state, the folder at\n`~/pCloud Drive` may still exist, but the `pcloudfs` mount is missing or the\nofficial app process has exited. Manually quitting and reopening pCloud Drive\nusually restores the files immediately.\n\nThis watchdog was created after debugging that exact pattern on macOS 26.4.1\nwith pCloud Drive 4.0.10:\n\n- Finder showed `pCloud Drive`.\n- The local `~/pCloud Drive` folder existed.\n- No active `pcloudfs` mount was present.\n- Restarting the official pCloud Drive app restored the mount and file listing.\n\n## What It Does\n\nThe watchdog runs periodically through `launchd` and checks three conditions:\n\n- the pCloud Drive app process is running;\n- `~/pCloud Drive` is mounted as `pcloudfs`;\n- the mounted drive contains visible cloud content.\n\nIf one of those checks fails repeatedly, the script asks pCloud Drive to quit,\nwaits, stops leftover pCloud helper processes, and opens pCloud Drive again.\nThe default policy checks every 5 minutes and restarts after 2 consecutive\nfailed checks. That avoids reacting to short mount warm-up periods or transient\nnetwork hiccups.\n\nThe script includes a short warm-up guard so it does not restart pCloud while\nthe app is still mounting the drive after a fresh launch.\n\n## Requirements\n\n- macOS.\n- The official pCloud Drive app installed.\n- Apple command-line tools normally present on macOS: `launchctl`, `plutil`,\n  `open`, `osascript`, `pgrep`, `pkill`, and `scutil`.\n- `make` for the simple install and uninstall commands.\n\n## Install\n\nClone the project, then run:\n\n```sh\nmake install\n```\n\nThe installer detects `pCloud Drive.app`, asks for a check interval and a\nconsecutive failure threshold, generates a LaunchAgent for the current user, and\nstarts it immediately.\n\nThe default check interval is `300` seconds. The default restart threshold is\n`2` consecutive failed checks. To install without an interactive prompt, pass\nthe values explicitly:\n\n```sh\nINTERVAL_SECONDS=300 PCLOUD_FAILURE_THRESHOLD=2 make install\n```\n\nIf the watchdog is already installed, `make install` does not overwrite the\ncurrent LaunchAgent. Use `make configure` to change settings or use\n`FORCE=1 make install` to reinstall the files anyway.\n\n## Reconfigure\n\nTo update an existing installation:\n\n```sh\nmake configure\n```\n\n`make config` is also available as a shorter alias. The command asks for the new\ncheck interval and the number of consecutive failed checks required before a\nrestart, then reloads the LaunchAgent.\n\nFor unattended reconfiguration:\n\n```sh\nINTERVAL_SECONDS=600 PCLOUD_FAILURE_THRESHOLD=3 make configure\n```\n\nIf pCloud Drive is installed in an unusual location, pass `PCLOUD_APP_PATH`:\n\n```sh\nPCLOUD_APP_PATH=\"/Applications/pCloud Drive.app\" make install\n```\n\nTo generate the installed script and LaunchAgent without loading or restarting\nthe launchd service, pass `NO_LAUNCH=1`:\n\n```sh\nNO_LAUNCH=1 make install\n```\n\n## Uninstall\n\n```sh\nmake uninstall\n```\n\nThis unloads the LaunchAgent and removes the installed watchdog script. It keeps\nlogs by default.\n\nTo remove logs too:\n\n```sh\nREMOVE_LOGS=1 make uninstall\n```\n\n## Configuration\n\nThe installer writes:\n\n- `~/.local/bin/pcloud-drive-watchdog.sh`\n- `~/Library/LaunchAgents/com.marcomc.pcloud-drive-watchdog.plist`\n\nThe LaunchAgent stores the chosen check interval in `StartInterval`.\nIt stores the restart threshold in `PCLOUD_FAILURE_THRESHOLD`.\n\nThe runtime script also supports these environment variables:\n\n- `PCLOUD_APP_PATH`: path to `pCloud Drive.app`;\n- `PCLOUD_APP_NAME`: app name, default `pCloud Drive`;\n- `PCLOUD_APP_BUNDLE_ID`: app bundle identifier, default\n  `com.pcloud.pcloud.macos`;\n- `PCLOUD_DRIVE_PATH`: mounted drive path, default `~/pCloud Drive`;\n- `PCLOUD_WATCHDOG_LOG_FILE`: log file path.\n- `PCLOUD_FAILURE_THRESHOLD`: consecutive failed checks before restart, default\n  `2`, allowed range `1` through `999`;\n- `PCLOUD_STATE_DIR`: small state directory used to count consecutive failed\n  checks, default `~/Library/Application Support/pcloud-drive-watchdog`;\n- `PCLOUD_VERBOSE`: set to `1` to log every healthy check.\n- `PCLOUD_QUIT_EVENT_TIMEOUT_SECONDS`: seconds to wait for the AppleEvent quit\n  request before continuing with process termination, default `5`;\n- `PCLOUD_QUIT_WAIT_SECONDS`: seconds to wait after requesting quit before\n  checking for remaining pCloud processes, default `8`;\n- `PCLOUD_FORCE_KILL_WAIT_SECONDS`: seconds to wait after `SIGTERM` before\n  escalating to `SIGKILL`, default `2`.\n\nWhen these variables are passed to `make install` or `make configure`, the\ngenerated LaunchAgent persists them for scheduled watchdog runs. Most users\nshould only need `INTERVAL_SECONDS` and `PCLOUD_FAILURE_THRESHOLD`.\n\nSet `NO_LAUNCH=1` during install when you want to inspect the generated files\nbefore loading the LaunchAgent.\n\n## Script Interface\n\nThe installed watchdog script is:\n\n```text\n~/.local/bin/pcloud-drive-watchdog.sh\n```\n\nSupported command-line options:\n\n- no arguments: run one watchdog check cycle;\n- `--help` or `-h`: print the supported options;\n- `--version`: print the watchdog version;\n- `--detect-app-path`: print the detected `pCloud Drive.app` path and exit.\n\nExamples:\n\n```sh\n~/.local/bin/pcloud-drive-watchdog.sh\n~/.local/bin/pcloud-drive-watchdog.sh --help\n~/.local/bin/pcloud-drive-watchdog.sh --version\nPCLOUD_APP_PATH=\"/Applications/pCloud Drive.app\" \\\n  ~/.local/bin/pcloud-drive-watchdog.sh --detect-app-path\n```\n\nSupported runtime environment variables:\n\n- `PCLOUD_APP_PATH`: override the detected `pCloud Drive.app` path;\n- `PCLOUD_APP_NAME`: override the app display name used in path detection;\n- `PCLOUD_APP_BUNDLE_ID`: override the app bundle identifier used for\n  AppleEvent quit and `open -b`;\n- `PCLOUD_DRIVE_PATH`: override the expected mount point path;\n- `PCLOUD_WATCHDOG_LOG_FILE`: override the main watchdog log file path;\n- `PCLOUD_FAILURE_THRESHOLD`: set the number of consecutive failed checks\n  required before restart, valid range `1` through `999`;\n- `PCLOUD_STATE_DIR`: override the state directory used for the failure counter;\n- `PCLOUD_VERBOSE`: set to `1` to log healthy checks too;\n- `PCLOUD_QUIT_EVENT_TIMEOUT_SECONDS`: limit how long the script waits for the\n  AppleEvent quit request before continuing with process termination;\n- `PCLOUD_QUIT_WAIT_SECONDS`: wait after requesting quit before checking for\n  remaining pCloud processes;\n- `PCLOUD_FORCE_KILL_WAIT_SECONDS`: wait after `SIGTERM` before escalating to\n  `SIGKILL`.\n\n## Logs\n\nThe watchdog writes its own status log here:\n\n```text\n~/Library/Logs/pcloud-drive-watchdog.log\n```\n\nThe LaunchAgent stdout and stderr files are:\n\n```text\n~/Library/Logs/pcloud-drive-watchdog.stdout.log\n~/Library/Logs/pcloud-drive-watchdog.stderr.log\n```\n\nUseful status commands:\n\n```sh\nlaunchctl print \"gui/$(id -u)/com.marcomc.pcloud-drive-watchdog\"\ntail -f ~/Library/Logs/pcloud-drive-watchdog.log\n```\n\n## Troubleshooting\n\nCheck whether pCloud Drive is mounted:\n\n```sh\nmount | grep pcloudfs\n```\n\nCheck whether the official app is running:\n\n```sh\npgrep -afil \"pCloud Drive\"\n```\n\nRun the watchdog manually:\n\n```sh\n~/.local/bin/pcloud-drive-watchdog.sh\n```\n\nIf the app is installed somewhere unusual, reinstall with `PCLOUD_APP_PATH`.\n\n## References\n\n- [pCloud Drive for macOS release notes](https://www.pcloud.com/release-notes/mac-os.html)\n- [Reddit: pCloud Drive 4.0.10 broken on macOS 26.4.1](https://www.reddit.com/r/pcloud/comments/1spld1e/pcloud_drive_4010_broken_on_macos_2641_kext_fails/)\n- [Reddit: downgrade to macOS pCloud version 4.0.6 solved our problems](https://www.reddit.com/r/pcloud/comments/1s9irxt/downgrade_to_macos_pcloud_version_406_solved_our/)\n\n## License\n\nMIT. See [LICENSE.md](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcomc%2Fpcloud-drive-watchdog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcomc%2Fpcloud-drive-watchdog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcomc%2Fpcloud-drive-watchdog/lists"}