Add macOS launchd template, bringing automation parity to macOS
Ship a launchd user agent plist alongside the existing systemd and
cron templates so macOS users can schedule mempalace-session without
falling back to cron. launchd is the macOS-native equivalent of a
systemd user timer: same scheduling model, same log conventions, same
single-instance guarantees.
- contrib/launchd/se.jordbo.mempalace-session.plist:
- Label uses reverse-DNS from the jordbo.se domain for consistency
with other user-installed launchd jobs; fork the prefix if reusing
this template in a different org.
- ProgramArguments points at /Users/USER/.local/bin/mempalace-session
(USER is substituted at install time, same pattern as
contrib/cron/).
- EnvironmentVariables.PATH covers ~/.local/bin, Apple Silicon
Homebrew, Intel Homebrew, and system defaults — launchd agents
get a minimal PATH by default and the wrapper needs to find
mempalace + python3.
- StartCalendarInterval matches systemd unit's schedule: Monday
03:00 local.
- RunAtLoad=false — load shouldn't trigger a run; schedule does.
- ProcessType=Background + LowPriorityIO=true + Nice=10 mirror
the systemd unit's Nice=10 + IOSchedulingClass=idle. macOS's
automatic App Nap and resource throttling for Background jobs
yields to interactive work cleanly.
- ExitTimeOut=7200 matches systemd's TimeoutStartSec=7200.
- StandardOut/ErrorPath under ~/Library/Logs/ so Console.app
surfaces them.
- contrib/README.md gains a full launchd section:
- Caveat table comparing to systemd (Persistent=true isn't quite
matched; RandomizedDelaySec has no equivalent; overlap prevention
is automatic).
- Install recipe using launchctl bootstrap (modern) with a fallback
note for legacy launchctl load -w on older macOS.
- Verify section shows launchctl list, launchctl print, log tails,
and launchctl kickstart for manual testing.
- Uninstall via launchctl bootout.
- Chooser table updated: macOS now explicitly points at launchd,
not cron.
- ARCHITECTURE.md §5, SKILL.md Quick automation pitch, and README.md
Keeping it fresh section all updated to mention the three scheduler
options and give per-platform quick-starts.
Plist XML validated with plistlib.
This commit is contained in:
Joakim Persson
+76
-5
@@ -66,6 +66,76 @@ systemctl --user daemon-reload
|
||||
|
||||
---
|
||||
|
||||
## launchd user agent (macOS)
|
||||
|
||||
**Why:** the macOS-native equivalent of a systemd user timer. Runs without a Terminal window open, logs to `~/Library/Logs/`, single-instance guarantees baked in, background-priority scheduling via `ProcessType=Background`. No Homebrew or third-party scheduler required.
|
||||
|
||||
**Caveats vs. systemd:**
|
||||
|
||||
| Systemd feature | launchd equivalent | Notes |
|
||||
|---|---|---|
|
||||
| `Persistent=true` catches missed runs | Partial — `StartCalendarInterval` fires on next system-awake time | If the Mac is fully off at scheduled time, the run is skipped. Sleep-at-schedule → fires on wake. |
|
||||
| `RandomizedDelaySec=30m` | None native | Single-user machines rarely need jitter; add a `sleep $((RANDOM % 1800))` wrapper if you do. |
|
||||
| `ConditionPathExists` | None native | `mempalace-session` exits cleanly when the opencode DB is missing, so no guard is strictly needed. |
|
||||
| Lock file for overlap prevention | Automatic | launchd refuses to start a second instance of the same `Label` while one is running. |
|
||||
|
||||
**Install:**
|
||||
|
||||
```bash
|
||||
# Substitute your username into the template
|
||||
sed "s|USER|$USER|g" contrib/launchd/se.jordbo.mempalace-session.plist \
|
||||
> ~/Library/LaunchAgents/se.jordbo.mempalace-session.plist
|
||||
|
||||
# Ensure the log directory exists
|
||||
mkdir -p ~/Library/Logs
|
||||
|
||||
# Modern load (macOS 10.11+). "gui/$(id -u)" targets your login session.
|
||||
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/se.jordbo.mempalace-session.plist
|
||||
launchctl enable "gui/$(id -u)/se.jordbo.mempalace-session"
|
||||
```
|
||||
|
||||
> On older macOS or if you hit permissions errors with `bootstrap`, fall back to the legacy form:
|
||||
> `launchctl load -w ~/Library/LaunchAgents/se.jordbo.mempalace-session.plist`
|
||||
|
||||
**Verify:**
|
||||
|
||||
```bash
|
||||
# Quick check — is the job registered?
|
||||
launchctl list | grep mempalace-session
|
||||
|
||||
# Detailed state (next run time, last exit code, throttling)
|
||||
launchctl print "gui/$(id -u)/se.jordbo.mempalace-session"
|
||||
|
||||
# Run log tail
|
||||
tail -f ~/Library/Logs/mempalace-session.log
|
||||
tail -f ~/Library/Logs/mempalace-session.err.log
|
||||
|
||||
# Force a run right now (outside the schedule), for testing
|
||||
launchctl kickstart -p "gui/$(id -u)/se.jordbo.mempalace-session"
|
||||
```
|
||||
|
||||
**Uninstall:**
|
||||
|
||||
```bash
|
||||
launchctl bootout "gui/$(id -u)" ~/Library/LaunchAgents/se.jordbo.mempalace-session.plist
|
||||
rm ~/Library/LaunchAgents/se.jordbo.mempalace-session.plist
|
||||
# Optional — keep the old logs for post-mortem, or delete them:
|
||||
# rm ~/Library/Logs/mempalace-session{,.err}.log
|
||||
```
|
||||
|
||||
### What the plist does
|
||||
|
||||
- `Label=se.jordbo.mempalace-session` — reverse-DNS label; shows up in `launchctl list` and Console.app. Change the prefix if you're forking this for a different org.
|
||||
- `ProgramArguments` — absolute path to `mempalace-session`. Template uses `/Users/USER/.local/bin/mempalace-session`; the install `sed` substitutes your actual username.
|
||||
- `EnvironmentVariables.PATH` — covers `~/.local/bin`, Apple Silicon Homebrew (`/opt/homebrew/bin`), Intel Homebrew (`/usr/local/bin`), and system defaults. launchd agents get a minimal PATH by default, and `mempalace-session` needs to find `mempalace` + `python3`.
|
||||
- `StartCalendarInterval` — `Weekday=1, Hour=3, Minute=0` = Monday 03:00. Omit any key to match "any" (e.g. drop `Weekday` for daily).
|
||||
- `RunAtLoad=false` — don't run on load/reboot, only on schedule. Flip to `true` if you want a run at every boot.
|
||||
- `ProcessType=Background` + `LowPriorityIO=true` + `Nice=10` — macOS throttles this job's CPU and I/O so it yields to interactive work.
|
||||
- `ExitTimeOut=7200` — 2h ceiling, matches the systemd unit.
|
||||
- `StandardOut/ErrorPath` — `~/Library/Logs/` is the macOS convention; Console.app picks these up automatically.
|
||||
|
||||
---
|
||||
|
||||
## cron
|
||||
|
||||
**Why:** simpler, ubiquitous, works on any UNIX. No `loginctl enable-linger` dance, no user-units awareness required.
|
||||
@@ -114,13 +184,14 @@ crontab -e # remove the mempalace-session line by hand
|
||||
|
||||
| Situation | Pick |
|
||||
|---|---|
|
||||
| Desktop / laptop, modern systemd-based distro | systemd user timer |
|
||||
| Long-running devbox or server, wants "Persistent=true" catch-up | systemd user timer |
|
||||
| macOS, BSD, or distro without systemd | cron |
|
||||
| Desktop / laptop, modern systemd-based Linux distro | systemd user timer |
|
||||
| macOS (any recent version) | launchd user agent |
|
||||
| Long-running Linux devbox or server, wants "Persistent=true" catch-up | systemd user timer |
|
||||
| BSD, Alpine, or Linux distro without systemd | cron |
|
||||
| You already have a cron-based job scheduler on the box | cron |
|
||||
| You want logs in `journalctl` rather than a file | systemd user timer |
|
||||
| You want logs in `journalctl` (Linux) or Console.app (macOS) rather than a file | systemd user timer / launchd |
|
||||
|
||||
If you're not sure, pick systemd. `Persistent=true` alone is worth it on any box that ever sleeps or reboots.
|
||||
If you're not sure: **systemd on Linux, launchd on macOS, cron only when neither is available**. All three wrap the same `mempalace-session` command — the difference is purely in *how* the box remembers to run it.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
|
||||
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<!--
|
||||
se.jordbo.mempalace-session.plist — macOS launchd user agent
|
||||
that mines opencode session history into MemPalace weekly.
|
||||
|
||||
Template: replace USER with your macOS short username before installing.
|
||||
The install recipe in contrib/README.md does this for you via `sed`.
|
||||
|
||||
Parity with contrib/systemd/mempalace-session.{service,timer}:
|
||||
- Weekly Mon 03:00 local time → StartCalendarInterval below.
|
||||
- Low-priority background I/O → ProcessType=Background + LowPriorityIO.
|
||||
- "Fire on next wake if missed" → launchd fires StartCalendarInterval
|
||||
jobs as soon as the system is running past the scheduled time.
|
||||
(Close to systemd's Persistent=true, not identical: if the Mac is
|
||||
fully off at the scheduled time, the missed run is simply skipped.
|
||||
systemd with Persistent=true would catch up at next boot.)
|
||||
- Single-instance guard → launchd refuses to start a second copy of
|
||||
the same Label while one is running (equivalent to the systemd
|
||||
lock-file dance).
|
||||
- "Skip if opencode has never been used" → no native equivalent.
|
||||
mempalace-session exits cleanly (zero drawers filed, fast) when
|
||||
the DB is absent, so no guard is strictly needed. If you want a
|
||||
hard pre-check, wrap ProgramArguments in a shell that tests for
|
||||
~/Library/Application Support/opencode/opencode.db first.
|
||||
-->
|
||||
|
||||
<key>Label</key>
|
||||
<string>se.jordbo.mempalace-session</string>
|
||||
|
||||
<!-- Absolute path. Install.sh symlinks the wrapper here via cli_utils
|
||||
convention. If you installed mempalace-toolkit somewhere else,
|
||||
update this path accordingly. -->
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/Users/USER/.local/bin/mempalace-session</string>
|
||||
</array>
|
||||
|
||||
<!-- launchd gives agents a minimal PATH. Set one that includes the
|
||||
usual macOS locations for brew (Apple Silicon + Intel) plus the
|
||||
user's local bin. mempalace-session invokes `mempalace` and
|
||||
`python3`, both must resolve. -->
|
||||
<key>EnvironmentVariables</key>
|
||||
<dict>
|
||||
<key>PATH</key>
|
||||
<string>/Users/USER/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
|
||||
<key>HOME</key>
|
||||
<string>/Users/USER</string>
|
||||
</dict>
|
||||
|
||||
<!-- Weekly, Monday 03:00 local time. Edit to taste:
|
||||
Hour: 0-23 (24-hour)
|
||||
Minute: 0-59
|
||||
Weekday: 0 or 7 = Sunday, 1 = Monday, …, 6 = Saturday
|
||||
Omit a key to match "any". For example: daily 03:00 would use
|
||||
only Hour=3 + Minute=0, no Weekday key. -->
|
||||
<key>StartCalendarInterval</key>
|
||||
<dict>
|
||||
<key>Weekday</key>
|
||||
<integer>1</integer>
|
||||
<key>Hour</key>
|
||||
<integer>3</integer>
|
||||
<key>Minute</key>
|
||||
<integer>0</integer>
|
||||
</dict>
|
||||
|
||||
<!-- Don't run the job just because the plist was loaded. Wait for
|
||||
the StartCalendarInterval trigger. -->
|
||||
<key>RunAtLoad</key>
|
||||
<false/>
|
||||
|
||||
<!-- Background-priority scheduling (CPU + I/O). macOS App Nap and
|
||||
the resource-throttling machinery kick in for ProcessType=Background,
|
||||
so this job yields to interactive work automatically. -->
|
||||
<key>ProcessType</key>
|
||||
<string>Background</string>
|
||||
<key>LowPriorityIO</key>
|
||||
<true/>
|
||||
<key>Nice</key>
|
||||
<integer>10</integer>
|
||||
|
||||
<!-- Runaway guard. Reference 60-session mine takes ~21 min; give 2h.
|
||||
If the process exceeds this, launchd kills it with SIGTERM then
|
||||
SIGKILL. Rare — only matters on pathologically large corpora. -->
|
||||
<key>ExitTimeOut</key>
|
||||
<integer>7200</integer>
|
||||
|
||||
<!-- Logs. Tail with:
|
||||
tail -f ~/Library/Logs/mempalace-session.log
|
||||
Or view in Console.app under "Log Reports". -->
|
||||
<key>StandardOutPath</key>
|
||||
<string>/Users/USER/Library/Logs/mempalace-session.log</string>
|
||||
<key>StandardErrorPath</key>
|
||||
<string>/Users/USER/Library/Logs/mempalace-session.err.log</string>
|
||||
</dict>
|
||||
</plist>
|
||||
Reference in New Issue
Block a user