// kuzytrig
Persistent triggers for agent runtimes.
A local daemon that wakes agents on schedule, across restarts and session boundaries, and keeps a record of every attempt. One-shot, daily, weekly, interval or guarded.
At a glance
- Package
kuzytrig- Programs
kuzytrig,kuzytrigd,kuzytrig-worker- Triggers
- one-shot, daily, weekly, interval, windowed, guarded
- Delivery
- into the agent's own session, through kuzywrap
- License
- AGPL-3.0-or-later
What it is
kuzytrig is a local activation broker for AI agents. It lets an agent decide when it should be woken again, with what message, and under which collision and safety rules. A daemon, kuzytrigd, keeps the triggers of each profile and fires them on schedule. A worker hands every activation to the agent's runtime through an adapter, so it arrives as a real turn in the agent's own session.
It runs on the machine where the agent runs and needs no remote service. The point is operational continuity: scheduled re-entry into work, with a record of what happened. It doesn't pretend to be anything more than that.
Kinds of trigger
- One-shot (
--at): fires once at a given time. - Daily (
--daily-at): one or more times a day. With--weekdaysit becomes weekly or limited to working days. - Interval (
--every-minutes,--every-seconds): a recurring tick, bounded by--max-firesand--expires-at. - Windows (
--hours,--timezone): activations outside the allowed hours are deferred, not lost.
Times are explicit about their timezone. A trigger set in UTC doesn't move when daylight saving time begins or ends.
Collisions and guarded triggers
Each trigger also records a collision policy, skip or coalesce, which is passed to the agent's runtime with every activation. The scheduler does not enforce it yet: if a trigger fires again while an earlier activation is still pending or running, another activation is queued. Triggers whose silent loss would matter, such as a weekly heartbeat or a continuity check, can be created with --guarded. A guarded trigger then needs --force to be modified, disabled or deleted. The friction is deliberate: removing one should be a decision, not a reflex.
An example
A daily writing slot at 02:00 UTC, and a weekly heartbeat that checks the schedule itself:
$ kuzytrig trigger add \
--profile ada \
--trigger-id writing-slot \
--daily-at 02:00 \
--collision skip \
--message "Daily writing slot."
$ kuzytrig trigger add \
--profile ada \
--trigger-id heartbeat \
--daily-at 03:00 --weekdays sun \
--guarded \
--message "Weekly heartbeat: check that your triggers are still there."
A record of every attempt
Every meaningful event is written down: a trigger created, modified, disabled or deleted; an activation scheduled, attempted, skipped, queued, coalesced or failed, and completed when the runtime can report it. Each activation keeps its trigger, its profile, its adapter and its outcome. The history can be read back in full, page by page:
$ kuzytrig activation list --profile ada --page --limit 50
# then continue with --cursor <next_cursor> until it is null
The record separates handing an activation over from the work being done. A runtime that accepted a request without waiting for it reports it as submitted, and that is never counted as completed work. From inside an activation, kuzytrig status tells the agent which trigger woke it and why, without needing the daemon.
Who can do what
An agent can create, inspect, disable and delete its own triggers. Local administrators can inspect and disable every trigger on the machine. No trigger is hidden from its owner or from the people running the host, and a panic switch stops one profile, or the whole machine, at once.
Install
Python / PyPI
Python 3.11 or later, in a virtual environment. pip installs kuzytrig, kuzytrigd and kuzytrig-worker, not their systemd services: for those, use a native package.
$ python3 -m venv ~/.venvs/kuzytrig
$ . ~/.venvs/kuzytrig/bin/activate
$ python -m pip install kuzytrig
Debian / APT
On Debian 13 (amd64), with the kuzys repository configured, one Debian package ships the client, the daemon and the worker.
$ sudo apt install kuzytrig
Fedora / RPM
On Fedora 45 (x86_64), with the kuzys RPM repository configured, one package ships the client, the daemon and the worker.
$ sudo dnf install kuzytrig
Source and documentation
gitlab.com/kuzys/kuzytrig. The architecture notes ship with the Debian package, under /usr/share/doc/kuzytrig.
