# Writing scripts with gezel-sdk

A Gezel script is a small TypeScript automation that runs in a sandbox. It can inspect a project, create an artifact, update a task, ask a model a focused question, call an approved tool, or decide whether a craftbook step may advance. The `@bendyline/gezel-sdk` package is the typed bridge between that script and Gezel.

Scripts are project-scoped by default and live as readable files under `~/.gezel/projects/{projectId}/scripts/`. They can be run manually, attached to the start or end of a task step, used as a completion gate, or called by another script.

## Start in the app

Turn on **Settings → About → Advanced → Show advanced features**, then open **Scripts** from the sidebar. Choose a project and select **New script**. You can describe the automation for an AI draft, start from a working template, or begin with the blank skeleton.

The built-in editor supplies autocomplete for the exact SDK version used by the running daemon. Saving checks the metadata, TypeScript syntax, and Node-compatible type syntax; **Run** supplies a form for the inputs declared by the script and shows its output, logs, calls, and errors.

You do not need to install the SDK into each Gezel project. The daemon places its matching SDK in the sandbox at run time. Install `@bendyline/gezel-sdk` in a separate source repository only when that repository authors reusable scripts and should type-check them itself:

```bash
npm install --save-dev @bendyline/gezel-sdk
```

## The shape of a script

Every script exports a static `meta` block, reads validated input from `gezel.input`, and stamps one final result with `gezel.output()`. This gate checks that a workspace contains a README with something in it before a task step can finish:

```ts
import {
  defineScript,
  gezel,
  type GateScriptResult,
  type InferredInput,
} from '@bendyline/gezel-sdk';

export const meta = defineScript({
  name: 'require-readme',
  description: 'Require a README before this step can finish.',
  kind: 'gate',
  inputs: {
    path: {
      type: 'string',
      description: 'Workspace-relative README path.',
      default: 'README.md',
    },
  },
  requires: ['workspace.read'],
} as const);

const input = gezel.input as InferredInput<typeof meta>;
const files = await gezel.fs.listAll();
const text = files.includes(input.path) ? await gezel.fs.read(input.path) : '';

const result: GateScriptResult =
  text.trim().length > 0
    ? { decision: 'approve', message: `${input.path} is present.` }
    : {
        decision: 'reject',
        message: `Add ${input.path} with setup and usage instructions, then try again.`,
      };

gezel.output(result);
```

The file name is the script's invocation name, so keep it aligned with `meta.name`. Input descriptors drive the manual-run form and `InferredInput`; output descriptors document an action script's result. A gate instead returns `approve` or `reject`. A rejection must include a useful `message` because Gezel gives it directly to the working gezel as the repair instruction.

## Declare capabilities before using them

The `requires` list is both documentation and an enforced permission boundary. A call fails with `CAPABILITY_DENIED` when the matching capability was not declared, and project or installation policy can still deny a declared capability.

| Capability | SDK surface |
| --- | --- |
| `workspace.read`, `workspace.write` | `gezel.fs` for project workspace files: `read`, `write`, `list`, `listAll`, `stat`, `rm`, `mkdir`, `rename` |
| `artifacts.read`, `artifacts.write` | `gezel.artifacts` for generated project outputs |
| `documents.read`, `documents.write` | `gezel.documents` for the shared document library |
| `tasks.read`, `tasks.write` | `gezel.task` for task records, steps, and notes |
| `memory.read`, `memory.write` | `gezel.memory` for project memories |
| `index.read`, `index.refresh` | `gezel.index` for workspace-index status and the bounded make-it-fresh ensure |
| `reminders` | `gezel.reminder.set()` / `clear()` for the project's one reminder |
| `llm` | `gezel.llm.oneShot()` |
| `network` | `gezel.mcp.call()` and `gezel.http` |
| `credential:<name>` plus `network` | `gezel.http.authed()` with a project-approved named credential |

A reminder is for a time the script worked out from the project's own state, such as when the next flashcard comes due. It is never a time picked for its own sake. `at` must be in the future and at most 30 days ahead, the title is up to 80 characters, and the body up to 160. Setting a reminder replaces the project's earlier one. The app turns it into a notification, within the person's daily allowance.

A register of due dates (permits, contract notice dates, certificates that expire) keeps its one reminder on the soonest open item. End every action that changes the register with the same step: find the earliest open item, take its due date minus the app's lead time, and set the reminder for that moment when it falls within the next 30 days; otherwise clear it. An item further out arms nothing yet. The next run of any of the register's tools re-arms it, so a status tool the page or the model calls routinely should run the step too. Wrap the call in `try`: a host without reminders still keeps the register.

```ts
async function remindNextDue(items: Array<{ title: string; dueAt: string; open: boolean }>, leadDays: number) {
  const now = Date.now();
  const next = items
    .filter((i) => i.open && Date.parse(i.dueAt) - leadDays * 86_400_000 > now)
    .sort((a, b) => Date.parse(a.dueAt) - Date.parse(b.dueAt))[0];
  const at = next ? Date.parse(next.dueAt) - leadDays * 86_400_000 : NaN;
  try {
    if (!next || at - now > 30 * 86_400_000) await gezel.reminder.clear();
    else await gezel.reminder.set({ at: new Date(at).toISOString(), title: `${next.title} is due soon`, body: `Due ${next.dueAt.slice(0, 10)}.` });
  } catch {
    // Reminders are a convenience; the register is the record.
  }
}
```

`gezel.input`, `gezel.output()`, `gezel.log()`, and `gezel.script.run()` need no capability. A nested script runs under its own metadata and permission set, and nesting is limited to four levels.

Ask only for what the script needs. In particular, use `gezel.fs` for workspace I/O rather than importing Node's `fs`: raw filesystem code runs in an isolated scratch directory and cannot see the project workspace. For authenticated HTTP, the service attaches the named credential and scrubs it from the response; the secret value never enters the script.

## Actions, gates, and hooks

An action script produces ordinary structured output. Declare `outputs` in `meta`, then call `gezel.output()` exactly once with that shape. Actions are useful for reports, task updates, model-assisted transforms, and small integrations.

A gate script sets `kind: 'gate'` and returns a `GateScriptResult`. `approve` allows the step to complete. `reject` holds the step and explains what must change. Optional `goto` routing can send work back to an earlier step, while an approved `handoff` can pass a message and parameters to the next step.

After a script works manually, attach it from a task's step automation controls. Craftbooks can also ship scripts and connect them to step entry, exit, and gate moments. Gezel preserves a trace for each run: input, stamped output, logs, host calls, duration, trigger, and any error.

## Reusable helpers

The package has three public entry points:

| Import | Purpose |
| --- | --- |
| `@bendyline/gezel-sdk` | `defineScript`, `gezel`, metadata types, inferred input/output types, and gate result types |
| `@bendyline/gezel-sdk/checks` | Reusable gate-check predicates, `gateResult()`, and `workspaceFromGezel()` for adapting `gezel.fs` to check helpers |
| `@bendyline/gezel-sdk/stores` | File-backed `logStore`, `rosterStore`, and integer-cents `ledgerStore` helpers for scripts that maintain structured project state |

The separate `@bendyline/gezel-script-stdlib` package contains Gezel's trusted standard gate scripts. Use those by their `standard` scope when they already express the check you need; write a project script when the behavior belongs to one project, and a reusable craftbook script when it belongs to a workflow others will install.

If the code becomes part of a complete reusable in-Gezel experience, see [Building AI Apps inside Gezel](https://gezel.com/docs/building-ai-apps-inside-gezel/). If it lives in another application rather than inside Gezel's sandbox, use [gezel-app-sdk](https://gezel.com/docs/building-connected-apps-with-gezel-app-sdk/) instead.
