Skip to content

Scripts

A script is a small program in TypeScript (JavaScript with types) for the logic everyday actions cannot say: loops, sums, several collections at once, or an answer from the AI.

An example: a weekly review

This automation runs every Sunday at 20:00. It adds up the week’s workouts, asks the AI for three tips, and creates an entry in Weekly reviews.

import { Workouts, WeeklyReviews, ai, helpers } from "kzx";
export default async function run({ now }: Run) {
const week = await Workouts.entries({ from: now.minus({ days: 7 }) });
const km = week.reduce((sum, w) => sum + (w.Distance ?? 0), 0);
const byType = helpers.groupCount(week, w => w.Type?.name ?? "Other");
const tips = await ai.ask(
`Three short tips for next week. This week: ${km.toFixed(1)} km, ${week.length} workouts.`,
{ entries: week }
);
WeeklyReviews.create({
"@title": `Week of ${now.format("d MMM")}`,
Kilometres: km,
Document: helpers.table(byType) + "\n\n" + tips,
});
}

Everything a script uses comes from one place, kzx. The full list is in the Script toolbox.

Scripts suggest, the app decides

A script never changes your data itself. While it runs, its changes are collected, not applied. Inside the run, the script reads its own pending changes, so it behaves normally.

A script returns a list of changes. The app checks them, applies them as one undoable step, and only then sends anything outside.Scriptreturns a listof changesApp checkssame rulesas a tapAppliedas one stepyou can undoThen sentmessages,website postsIf anything fails or hits a limit, nothing is applied and nothing is sent.
A script’s changes go through the same path as your taps.

When the script finishes:

  1. The app checks every change with the same rules as a tap.
  2. The base check: if you edited a field after the run started, the script’s change to that field is skipped. The run history says so. A script never overwrites what you typed a moment ago.
  3. The app applies all the changes as one step in your history.
  4. Only then does the app send the run’s outside effects: notifications, messages, website posts and agent runs.

So you can test any script on an entry and see exactly what it would change, and undo any run in one click. See Testing, history and undo.

Your data, typed and named

The app writes a types file for your account (kzx.d.ts). Every collection becomes an object (Habits, Workouts). Every property gets its real type: Done is yes or no, Streak is a number, Status is one of your tags. The editor completes names as you type. The type check finds mistakes when you save, not at 3 a.m. when the automation runs.

How names become code names: spaces and symbols are dropped and words are joined, so “Weekly reviews” becomes WeeklyReviews. If two names would become the same, a name starts with a digit, or a name is a toolbox word (create, entries), the script uses entry.prop("Name") instead. It is typed in the same way.

Renames never break a script. The text shows names; a small map at the top of the file links each name to an id underneath. When you rename a property, the app rewrites every script that uses it, as a normal edit you can undo. If a property is deleted or changes type, the type check fails and the automation pauses with needs a fix and Fix with AI.

In the editor, collections, properties, tags and entries show as chips (small labels with the icon and colour). Type @ to insert an entry, a view, a tag or an agent from the one reference picker.

What a script cannot do

A script runs in a sealed box. It has no internet, no files, no keys and no storage of its own. It can reach a website only through the app, and only one you approved. It cannot delete anything. Each run starts in a fresh, empty box. The limits (5 seconds of computing, 2 minutes in all, 200 changes) are in the Script toolbox. Why this is safe: Safety and approval.