saravanakumardb1 d574f5dda3 feat(agent-queue): macOS LaunchAgent boot-persistence (auto-start + KeepAlive)

Adds agent-queue-boot.sh (PATH repair + ~/.agent-queue.env overrides + caffeinate
wrap) and launchd/ (install.sh + README) so the run loop auto-starts on login and
survives reboot/crash — the persistence layer tmux+caffeinate alone cannot give.
No secrets tracked (host config lives in untracked ~/.agent-queue.env).

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

2026-06-01 00:25:16 -07:00

3.0 KiB

Raw Blame History

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.

3.0 KiB Raw Blame History