bytelyst-devops-tools/agent-queue/launchd

Boot-persistence: agent-queue as a macOS LaunchAgent

Auto-start the agent-queue run loop on login and keep it alive across reboot / crash / logout — the one failure mode that tmux + caffeinate alone can't cover.

Layer	Survives terminal close	Survives sleep	Survives reboot
plain shell	no	no	no
tmux	yes	no	no
caffeinate	n/a	yes	no
LaunchAgent (this)	yes	yes (via caffeinate)	yes

Install

bash launchd/install.sh             # render plist, load, start now (RunAtLoad + KeepAlive)
tail -f ~/Library/Logs/agent-queue/agent-queue.out.log

It renders ~/Library/LaunchAgents/com.bytelyst.agent-queue.plist from the resolved repo path (works on any clone) and bootstraps it into your GUI session.

Use

The LaunchAgent runs agent-queue-boot.sh, which wraps agent-queue run in caffeinate. Just drop prompt .md files into queue/inbox/ — they get picked up automatically, now or after the next reboot.

aq add ~/jobs/phase3-overnight.md --engine codex   # or drop the file in queue/inbox/
aqs                                                 # status

Configure (no need to edit the plist)

Put overrides in ~/.agent-queue.env (untracked — also the place for tokens):

AGENT_QUEUE_ENGINE=codex   # codex (recommended: local repo) | devin | claude
AGENT_QUEUE_MAX=1          # concurrent jobs on this host (default 3)
# AGENT_QUEUE_NO_CAFFEINATE=1   # allow the Mac to idle-sleep (NOT for overnight runs)
# DEVIN_BIN=/custom/path/devin  # if a CLI isn't on the default PATH

Stop / uninstall

bash launchd/install.sh --uninstall   # bootout + remove plist (queued jobs stay put)

Notes & gotchas

• codex vs devin: for a local monorepo overnight runner, codex is the default — it runs in-repo so @bytelyst/* workspace links resolve locally and logs/token-usage parsing already work. Use devin when you want a cloud sandbox doing the heavy lifting (and ACUs/network aren't a concern).
• Power: caffeinate wraps the long-lived loop, so the Mac stays awake the whole time the LaunchAgent runs. That's intended for a dedicated runner. Set AGENT_QUEUE_NO_CAFFEINATE=1 if you'd rather let it idle-sleep when no job is active. Keep it plugged in with the lid open for true overnight runs.
• PATH: launchd starts processes with a minimal PATH. Both the plist (EnvironmentVariables) and the wrapper repair it, but if a CLI lives somewhere unusual, point at it explicitly via ~/.agent-queue.env.
• Dangerous mode: jobs run --yolo (auto-approve) by default. The safety net is the agent-queue lifecycle itself — jobs land in review/ → testing/ and shipping is always a manual human gate. Never let an unattended run touch main; push to a branch and open one PR.
• Auth: cache gh auth login / git credentials and the agent CLI's auth before relying on it overnight, or the first push will block forever.