# Triggers > Declare WHEN a saved tap runs unattended — ~/.tap/triggers/ trigger.json declarations compiled idempotently into launchd plists (dev.taprun.trigger.* namespace), zero LLM tokens per fire. Foreground-gated plans (trusted:true) are refused at declaration time. Use when the user wants a tap to run on a schedule / on file change ("run this tap every day", "check back on a schedule", "schedule this tap", "put this on launchd", "tap trigger"). NOT for Claude Code routines/cron (those wake an agent and burn tokens per fire) — this is the zero-token trigger layer for already-compiled plans. - Skill: `leonting1010/triggers` (Agent Skill) - Install (CLI): `npx skillmds@latest add leonting1010/triggers` - Raw SKILL.md: https://api.skillmd.com/api/skills/leonting1010/triggers/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: LeonTing1010 (https://skillmd.com/u/leonting1010) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/leonting1010/triggers --- # triggers — the trigger layer above plans ## What this is (and the one-sentence why) A Plan answers **what** and encodes **verification**; it deliberately does not answer **when**. Cloud "routines" bundle all three but pay an agent session per fire. Tap's distillation asymmetry demands the opposite: compile once, replay free — so the trigger layer must also be zero-token. The OS already ships a world-class trigger engine (launchd); this skill owns only the **deterministic compile** from a versionable declaration to a launchd artifact. > Derivation (engineering-philosophy, 2026-07-12): trigger-in-engine is > structurally impossible — the NM host's lifetime is bound to Chrome's SW > (ADR 2026-05-30), and a scheduler that dies with the browser is not a > scheduler. Trigger-in-plan breaks the unit (a shared plan must not carry my > crontab; one plan ↔ N triggers). Hence a separate declaration, systemd > service/timer isomorphism: plan = service, trigger = timer. ## Declaration format `~/.tap/triggers//[.].trigger.json` — one file, one trigger. Slot (optional third filename segment) gives one plan several independent triggers (`visibility-recheck.am.trigger.json`, `…pm.trigger.json`). ```jsonc { "ref": "xhs/visibility-recheck", // or tap://xhs/visibility-recheck "args": { "note_url": "…", "note_id": "…" }, // optional, verbatim → tap --args "when": { // EXACTLY ONE of: "calendar": { "Hour": 10, "Minute": 30 } // launchd StartCalendarInterval // "calendar": [ {…}, {…} ] // multiple firing times // "interval_seconds": 3600 // StartInterval (>= 60) // "watch_path": "~/Downloads" // WatchPaths (fires on change) }, "sink": { // optional, WHERE the result lands "path": "~/.tap/ledger/{name}-{date}.json", // {date}{site}{name}{run_id} "select": "return" // return | envelope | return.… }, "on": { // optional, unified subscriptions "ok": [ { "write": "...", "select": "..." } ], // sink is sugar for ok.write "failed": [ { "notify_os": "🛑 scan failed — check the log" } ] // the only hook after a run dies }, "note": "why this trigger exists", // optional, lands as plist comment "disabled": true // optional; keeps the declaration, // materializer treats plist as orphan } ``` **`on` semantics** (ADR invocation-layer amendment): a run outcome is an event, and `on` is its declarative subscriber. The ok side fires when the run is committed AND `return.outcome` is absent or "ok" (identical to the sink write gate); the failed side is everything else — **including committed-but-outcome- not-ok** (a read-outcome failure is a failure event). The verb set is closed: `write | notify_os`. `run` (chaining another tap) is FUTURE — refused by name until a named consumer exists. `notify_os` passes arguments via osascript argv (injection-safe) and does not depend on Chrome — restoring the 🛑 abort-banner capability of the notify wrapper. ## Usage > **v2 (2026-07-12): the materializer was PROMOTED into core as the 5th > admin verb** — ADR `2026-07-12-invocation-layer-trigger-sink-schedule`. > The v1 skill-layer `scripts/materialize.ts` is retired; its 10 constraint > tests live on as `core/src/test/schedule_test.ts` (+ sink constraints). > This skill remains the declaration-format guide. ```bash # Compile all declarations → ~/Library/LaunchAgents/dev.taprun.trigger.*.plist tap schedule # report as JSON, exit 1 on any refusal # Remove plists whose declaration is gone/disabled tap schedule --prune # Sink (WHERE the committed result lands) — per-trigger: # "sink": { "path": "~/.tap/ledger/{name}-{date}.json", "select": "return" } # select: return (default) | envelope | return.... string → raw bytes # Failure writes NOTHING (absence = GAP signal). Same flags exist ad hoc: # tap / --out --select return.markdown # Activate / fire / remove (launchd side — `tap schedule` only writes files) launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.taprun.trigger...plist launchctl kickstart -k gui/$(id -u)/dev.taprun.trigger.. # fire NOW launchctl bootout gui/$(id -u)/dev.taprun.trigger.. launchctl list | grep dev.taprun.trigger # status ``` Logs land at `~/Library/Logs/taprun/