d574f5dda3
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>
71 lines
3.0 KiB
Markdown
71 lines
3.0 KiB
Markdown
# 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
|
|
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.
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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
|
|
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.
|