lettuce directive-worker

A headless background worker that answers > [!ai] directives on its own. It long-polls the vault (via [[Agent reference/04 Read tools|await_directives]]), and for each pending directive it retrieves context, asks the configured LLM, and flips the callout to [!ai-done] with the answer spliced in — closing the in-note mailbox loop without an interactive agent session. A [!ai] you type in the app or on your phone is picked up within FSEvents latency.

lettuce directive-worker [vault] [--worker ID] [--once]
lettuce directive-worker install [vault] [--worker ID]
lettuce directive-worker uninstall
lettuce directive-worker status

Run it in the foreground

lettuce directive-worker ~/Notes

It watches the vault (like [[CLI cookbook/01 lettuce serve|lettuce serve]]), so directives that arrive from the app or an iCloud sync wake its poll. Add --once to drain the current backlog and exit (handy for a cron job or a manual sweep). --worker ID sets a stable worker id; the default is derived from the hostname.

Install as an always-on LaunchAgent

lettuce directive-worker install ~/Notes

This writes a per-user LaunchAgent (com.lettuce.app.directive-worker, owner-only) that runs the worker now and at every login, restarting it if it exits. Logs go to ~/Library/Logs/Lettuce/directive-worker.log. Remove it with lettuce directive-worker uninstall; check it with lettuce directive-worker status.

It coexists with an always-on lettuce serve (a distinct label) and with interactive agents — directives are claim-leased to one worker at a time, so nothing is processed twice.

Requirements

An LLM provider must be configured in Settings → AI providers (stored in the Keychain) or via an ANTHROPIC_API_KEY-style environment variable. Without one the worker logs a notice and idles until a provider is set. Local models work too — point it at an Ollama/OpenAI-compatible endpoint.

Running more than one worker

Give each a distinct --worker id. Each directive is leased to whichever worker takes it (~2 minutes), and a directive held by another worker is withheld from the rest — so two machines sharing one vault won’t both act on the same [!ai]. A crashed worker’s lease frees up when the TTL lapses, and complete_directive releases it immediately.