README.md Raw History Folder

scratchpad — TypeScript extension example

Real .ts (not .js), no build step, no SDK. Runs via npx tsx, which downloads itself into the npm cache on first invocation and runs from cache on every subsequent call.

Demonstrates:

registering slash commands (/note, /notes, /clear-notes)
registering an LLM-callable tool (read_notes)
the wire protocol from a typed TypeScript perspective
running TypeScript via npx tsx from extension.json

Requirements

Node 18+ and tsx on $PATH:

npm install -g tsx

This is what extension.json invokes (exec: "tsx"). Without the global install, swap to "exec": "npx" + "args": ["--yes", "tsx", "index.ts"] — functional but adds ~1 second to each zot startup because npm checks the registry on every invocation.

Install

From this directory:

zot ext install .

Use

In zot:

/note remind me to update the changelog — appends to the scratchpad
/notes — shows everything stored
/clear-notes — wipes the scratchpad

The model also has a read_notes tool. Ask it:

"What did I tell you to remember?"

…and it will call the tool and tell you.

Storage

Notes persist as JSONL at <cwd>/.zot/scratchpad-notes.jsonl. The file is created on first /note and survives zot restarts. Each line is one note: {"at":"2026-04-19T13:00:00.000Z","text":"..."}.

Scope is per-project: switching to a different cwd gives you a different scratchpad. Cross-project sharing isn't supported in this example (would just be a matter of changing the path constant).

Why TypeScript here

The extension protocol is small enough that you can hand-write it in any language. JS works fine; TS adds type safety on the frame shapes without any infrastructure beyond tsx. If you want richer ergonomics (decorators, schema-from-types), publish your own SDK on top.

1# scratchpad — TypeScript extension example
2
3Real `.ts` (not `.js`), no build step, no SDK. Runs via `npx tsx`,
4which downloads itself into the npm cache on first invocation and
5runs from cache on every subsequent call.
6
7Demonstrates:
8
9- registering slash commands (`/note`, `/notes`, `/clear-notes`)
10- registering an LLM-callable tool (`read_notes`)
11- the wire protocol from a typed TypeScript perspective
12- running TypeScript via `npx tsx` from `extension.json`
13
14## Requirements
15
16Node 18+ and `tsx` on `$PATH`:
17
18```bash
19npm install -g tsx
20```
21
22This is what `extension.json` invokes (`exec: "tsx"`). Without the
23global install, swap to `"exec": "npx"` + `"args": ["--yes", "tsx",
24"index.ts"]` — functional but adds ~1 second to each zot startup
25because npm checks the registry on every invocation.
26
27## Install
28
29From this directory:
30
31```bash
32zot ext install .
33```
34
35## Use
36
37In zot:
38
39- `/note remind me to update the changelog`  — appends to the scratchpad
40- `/notes`                                    — shows everything stored
41- `/clear-notes`                              — wipes the scratchpad
42
43The model also has a `read_notes` tool. Ask it:
44
45> "What did I tell you to remember?"
46
47…and it will call the tool and tell you.
48
49## Storage
50
51Notes persist as JSONL at `<cwd>/.zot/scratchpad-notes.jsonl`. The
52file is created on first `/note` and survives zot restarts. Each line
53is one note: `{"at":"2026-04-19T13:00:00.000Z","text":"..."}`.
54
55Scope is per-project: switching to a different cwd gives you a
56different scratchpad. Cross-project sharing isn't supported in this
57example (would just be a matter of changing the path constant).
58
59## Why TypeScript here
60
61The extension protocol is small enough that you can hand-write it in
62any language. JS works fine; TS adds type safety on the frame shapes
63without any infrastructure beyond `tsx`. If you want richer ergonomics
64(decorators, schema-from-types), publish your own SDK on top.
65
66## See also
67
68- `examples/extensions/clock` — JS sibling (no tsx required)
69- `examples/extensions/hello` — Go SDK
70- `examples/extensions/weather` — Go SDK, exposes one tool
71- `examples/extensions/guard` — Go SDK, demonstrates intercepts
72- `docs/extensions.md` — full protocol reference

README.md RawHistoryFolder