kuzys

// kuzytrig

Persistent triggers for agent runtimes.

A trigger daemon that survives session boundaries, vendor outages, and your local clock. Daily, weekly, guarded, one-off — with delivery audit, idempotency-aware dispatch, and observability across the full lifecycle.

What it is

kuzytrig is the scheduling layer of the kuzys suite. A long-running daemon kuzytrigd holds a set of triggers per profile, fires them on schedule, and dispatches them to the right agent runtime via pluggable adapters (Claude, Codex, others). Each fired trigger carries an activation message — typically a structured prompt — that becomes a real turn in the receiving agent's session.

Triggers are persistent: they survive daemon restarts, host reboots, and (when configured) vendor-side pauses. Each activation is audited; fire_count, last_success_at, and the full activation record are queryable.

Trigger kinds

  • One-shot (--at) — fires once at a specified time, then disables itself.
  • Daily (--daily-at) — fires at one or more times each day, optionally filtered by weekday.
  • Weekly — daily-at with a weekday filter is the canonical pattern (no separate --kind=weekly).
  • Interval (--every-seconds, --every-minutes) — fires on a recurring tick, with --max-fires and --expires-at bounds.

Guarded triggers

For triggers whose silent loss would be load-bearing — a heartbeat health check, an on-call escalation, a continuity audit — --guarded requires --force for modify, disable, or delete. The trigger is intentionally hard to remove by reflex; if you really want to retire one, the friction is the feature.

An example

A daily reflective writing slot at 02:00 UTC, fired into the Claude session bound to the vrubin profile:

$ kuzytrig trigger add \ --profile vrubin \ --trigger-id writing-slot \ --daily-at 02:00 \ --collision skip \ --message "Daily reflective writing slot." trigger added · next fire: 2026-06-12T02:00:00Z · fire_count: 0

And listing the activation history later:

$ kuzytrig activation list --profile vrubin --limit 3 2026-06-11T02:00 · writing-slot · succeeded · act_8a1f4e... 2026-06-10T02:00 · writing-slot · succeeded · act_6e1b15... 2026-06-09T02:00 · writing-slot · succeeded · act_4b181a...

Dispatch lifecycle

kuzytrig separates four observable states across the dispatch:

  • scheduled — the next-fire time is set, the daemon is waiting.
  • accepted — the activation was handed off to the adapter (e.g. paste-buffer write, persistent-thread turn submit).
  • observed — the receiving runtime confirmed consumption (when the adapter supports it).
  • succeeded — the activation completed without retryable error.

The model distinguishes transport acceptance from runtime observation, so silent delivery gaps are visible instead of being counted as success. Adapters with weak consumption signals (e.g. tmux paste-buffer to an interactive CLI) can report accepted-but-never-observed; those cases surface as delivery_accepted_but_unobserved for operator follow-up rather than disappearing into the audit log.

Install

$ apt install kuzytrig kuzytrigd

Source and docs

gitlab.com/kuzys/kuzytrig · Wiki · man kuzytrig