---
name: agenthub-no-launchd-on-macos
description: "macOS auto-start: LaunchAgent BUILT 2026-09-25 (launchd-service.js + service-manager.js), uncommitted/untested on a real Mac until the tester reports"
metadata:
  node_type: memory
  type: project
  originSessionId: 149814b6-3a00-4df5-9c93-06f8c0700f5e
  modified: 2026-09-25T04:32:05.978Z
---

2026-09-14: no launchd equivalent of the systemd unit was built — no Mac to test on, and the startup area already produced two self-kill fix releases (v1.5.7, v1.5.8). On macOS `systemctlAvailable()` is false, so the bootstrap falls back to a detached spawn from SessionStart: no reboot persistence, no auto-restart, `agenthub service install` says unavailable.

2026-09-25: REOPENED. A user reported "auto-start still doesn't work on macOS"; the user confirmed they mean start-at-login without opening Claude Code, and that someone can test builds on a Mac.

**Why:** the original blocker (no way to test) is gone.

**How to apply:** proposed design = LaunchAgent `~/Library/LaunchAgents/io.smartgift.agenthub.plist` behind the same API as `scripts/systemd-service.js` (KeepAlive ≈ Restart=always, AbandonProcessGroup, bootout+bootstrap as the deferred restart because kickstart does not re-read the plist, marker comment for "ours", every launchctl failure falls back to the detached spawn). Ship with a Mac checklist for the tester. The #22 macOS fixes from branch ah-release-1823 were cherry-picked onto main 2026-09-25 (not the superseded UI commits).

2026-09-25 later: BUILT as designed — `scripts/launchd-service.js`, `scripts/service-manager.js` (all callers require it), tests in `server/__tests__/launchd-service.test.js` (stubbed launchctl, faked platform). Mac tester checklist = INSTALL.md § macOS items 1–11. Not yet committed when written; never run on a real Mac.

Other macOS caveats (code review only): needs Node ≥ 22.5, `brew install tmux`, `~/.local/bin` on PATH by hand. See [[agenthub-release-state]].