Summary
Expand meshd doctor with more actionable health checks beyond basic connectivity.
Motivation
The current doctor command checks if Syncthing is reachable and the folder is registered. There are several common failure modes that silently degrade the experience that we can detect and explain.
Proposed Checks
Linux / Arch specific
✔ inotify limit: 524288 (recommended ≥ 131072)
✘ inotify limit: 8192 — too low, Syncthing may miss file changes
Fix: echo fs.inotify.max_user_watches=524288 | sudo tee /etc/sysctl.d/40-meshd.conf && sudo sysctl -p
Stale / ghost devices
⚠ MacBook-Old: not seen in 47 days — consider removing (meshd peer rm <id>)
Conflict pile
⚠ 12 unresolved conflicts — run `meshd conflicts --fix` to resolve
Versioning disk usage
⚠ .stversions is 4.2 GB — consider pruning old versions
Oldest version: notes.md (143 days ago)
Folder out of sync
✘ ~/meshd not fully synced to Phone: 73% (23 files remaining)
API key validity
✔ Syncthing API key: valid
✘ Syncthing API key: expired or changed — re-run meshd to auto-detect
CLI Output Format
meshd doctor # human-readable, colored pass/warn/fail
meshd doctor --json # machine-readable for scripts / MCP tool
Implementation Notes
- inotify limit: read
/proc/sys/fs/inotify/max_user_watches on Linux only, skip silently on macOS
- Stale devices: compare
lastSeen from /rest/stats/device against a 30-day threshold
- Conflict pile: walk
~/meshd for files matching .sync-conflict-*
- Versioning size:
du on ~/meshd/.stversions
- All checks should be non-fatal —
doctor always exits 0 unless --strict flag is passed
Summary
Expand
meshd doctorwith more actionable health checks beyond basic connectivity.Motivation
The current
doctorcommand checks if Syncthing is reachable and the folder is registered. There are several common failure modes that silently degrade the experience that we can detect and explain.Proposed Checks
Linux / Arch specific
Stale / ghost devices
Conflict pile
Versioning disk usage
Folder out of sync
API key validity
CLI Output Format
Implementation Notes
/proc/sys/fs/inotify/max_user_watcheson Linux only, skip silently on macOSlastSeenfrom/rest/stats/deviceagainst a 30-day threshold~/meshdfor files matching.sync-conflict-*duon~/meshd/.stversionsdoctoralways exits 0 unless--strictflag is passed