SKILL.md Raw History Folder

name: write-zot-extension description: Help the user create a new zot extension (slash command, LLM tool, or guard) in any language.

Writing a zot extension

Use this skill when the user asks for help building a zot extension — a new slash command, a new tool the LLM can call, an audit hook, or a permission gate. Skim this whole skill first, then collaborate with the user on the specific extension they want.

What an extension is

A zot extension is an external executable that zot launches as a subprocess and talks to over its stdin/stdout in newline-delimited JSON. It can be written in any language that can read/write JSON lines from stdio: Go, TypeScript (via tsx), Python, Rust, shell with jq, anything. Crash isolation is automatic; one bad extension never takes down zot.

Three things an extension can do (any combination):

Slash commands — register /foo so the user can run it from the input. The handler returns a "prompt" (submitted to the agent), an "insert" (text dropped into the editor), a "display" (one-shot styled note in the chat), or a "noop".
Tools — register tools the LLM itself calls. Schema is JSON Schema; zot routes the model's tool_call to the extension's tool_result. Same lifecycle as built-in tools (read/write/edit/bash/skill).
Lifecycle hooks — subscribe to events (session_start, turn_start, tool_call, turn_end, assistant_message) for telemetry / audit / custom UI, or intercept tool calls before execution to refuse dangerous patterns.

On-disk layout

Each extension lives in its own directory:

~/Library/Application Support/zot/extensions/<name>/
├── extension.json    # manifest (required)
└── <executable>      # whatever exec points at

Or project-local: <project>/.zot/extensions/<name>/. Project-local wins on name conflict.

For ad-hoc use during development, skip the install step entirely and run zot --ext PATH (repeatable: -e PATH -e PATH).

Manifest

{
  "name": "weather",
  "version": "1.0.0",
  "exec": "./weather",
  "args": [],
  "language": "go",
  "description": "current weather lookups for any city",
  "enabled": true
}

Field rules:

name (required, unique) — id zot uses internally; matches the hello frame. Slash commands & tools live in the same name space as built-ins; conflicts are silently shadowed by built-ins.
exec (required) — the executable path. Resolution:
- absolute: as-is
- starts with ./ or ../: relative to the manifest's directory
- bare name (no separator): looked up via $PATH (e.g. node, python3, npx, tsx)
args — extra argv passed to exec (e.g. ["index.js"])
language — informational only ("go", "typescript", "python", etc.)
enabled — defaults to true; set false to keep installed but skip

Wire format

Newline-delimited JSON in both directions. Top-level type is the discriminator. Optional id correlates command/tool requests with their responses.

Required handshake

The very first frame the extension sends is hello:

{"type":"hello","name":"weather","version":"1.0.0",
 "capabilities":["commands","tools"]}

Capabilities are advisory; current values are commands, tools, events. Send all that apply.

zot replies with hello_ack:

{"type":"hello_ack","protocol_version":1,"zot_version":"0.0.x",
 "provider":"anthropic","model":"claude-opus-4-7","cwd":"/path/to/project"}

Registration (immediately after hello)

Send registration frames in any order, then a single ready sentinel so zot can finalize the agent's tool registry:

{"type":"register_command","name":"weather","description":"current weather"}
{"type":"register_tool","name":"weather","description":"Get current weather for a city.",
 "schema":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}
{"type":"subscribe","events":["tool_call"],"intercept":["tool_call"]}
{"type":"ready"}

If you don't send ready, zot's idle watchdog auto-treats you as ready after 250ms of no frames, but always send it explicitly when you can — newer extensions on faster hosts shave that 250ms off.

Runtime frames

zot → extension:

{"type":"command_invoked","id":"abc","name":"weather","args":"berlin"}
{"type":"tool_call","id":"def","name":"weather","args":{"city":"Berlin"}}
{"type":"event","event":"turn_start","step":1}
{"type":"event_intercept","id":"ghi","event":"tool_call",
 "tool_name":"bash","tool_args":{"command":"rm -rf /tmp/foo"}}
{"type":"shutdown"}

extension → zot (replies + spontaneous notifications):

{"type":"command_response","id":"abc","action":"prompt",
 "prompt":"Show today's weather for Berlin in one line."}
{"type":"tool_result","id":"def","content":[{"type":"text","text":"Berlin: 16°C, fog"}]}
{"type":"event_intercept_response","id":"ghi","block":true,
 "reason":"refused: command matches the danger pattern \"rm -rf\""}
{"type":"notify","level":"info","message":"refreshed cache"}
{"type":"shutdown_ack"}

command_response.action values:

"prompt" — submit prompt as a fresh user message
"insert" — drop insert into the editor at the cursor
"display" — append display to chat as a one-shot note (no model call, not in transcript)
"noop" — handled internally; zot doesn't change the UI

tool_result.content[] blocks: {"type":"text","text":"..."} or {"type":"image","mime_type":"image/png","data":"<base64>"}.

Per-tool timeout: 60s. Per-intercept timeout: 5s. Missing the intercept timeout is treated as "allow" so an unresponsive guard never stalls the agent.

Important rules

stdout is reserved for the protocol. Anything you print to stdout that isn't a JSON frame breaks the wire. Use stderr for logs / debug output (zot captures stderr to $ZOT_HOME/logs/ext-<name>.log).
One JSON object per line. No multi-line JSON. Always end every frame with \n.
Flush after writing. Most stdout writes are line-buffered when piped, which is fine, but explicitly flushing avoids surprise buffering on slow handlers.
Extension processes inherit the user's permissions. A bad extension can do anything the user can.

Recommended layout per language

Go (use the built-in SDK at pkg/zotext)

package main

import (
    "encoding/json"
    "github.com/patriceckhart/zot/pkg/zotext"
)

func main() {
    ext := zotext.New("weather", "1.0.0")

    ext.Command("weather", "current weather for a city",
        func(args string) zotext.Response {
            return zotext.Prompt("Tell me the weather for " + args)
        })

    ext.Tool("weather", "Get current weather for a city.",
        json.RawMessage(`{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}`),
        func(args json.RawMessage) zotext.ToolResult {
            var in struct{ City string `json:"city"` }
            if err := json.Unmarshal(args, &in); err != nil {
                return zotext.TextErrorResult("invalid args")
            }
            return zotext.TextResult(in.City + ": sunny, 21°C (fake)")
        })

    if err := ext.Run(); err != nil {
        ext.Logf("fatal: %v", err)
    }
}

Build: go build -o weather .

extension.json:

{"name":"weather","version":"1.0.0","exec":"./weather","language":"go","enabled":true}

TypeScript (no SDK; handles the protocol directly)

Run via tsx, which executes .ts files without a build step.

{"name":"scratchpad","version":"1.0.0","exec":"tsx","args":["index.ts"],"language":"typescript","enabled":true}

// index.ts (excerpt; see examples/extensions/scratchpad/index.ts for the full version)
import { createInterface } from "node:readline";
import { stderr, stdin, stdout } from "node:process";

function send(o: object) { stdout.write(JSON.stringify(o) + "\n"); }
function log(s: string) { stderr.write(`[scratchpad] ${s}\n`); }

send({ type: "hello", name: "scratchpad", version: "1.0.0",
       capabilities: ["commands", "tools"] });
send({ type: "register_command", name: "note", description: "append a note" });
send({ type: "register_tool", name: "read_notes",
       description: "Read the user's scratchpad notes.",
       schema: { type: "object", properties: {} } });
send({ type: "ready" });

const rl = createInterface({ input: stdin, crlfDelay: Infinity });
rl.on("line", (line) => {
  const f = JSON.parse(line);
  if (f.type === "command_invoked" && f.name === "note") {
    send({ type: "command_response", id: f.id, action: "display",
           display: `noted: ${f.args}` });
  } else if (f.type === "tool_call" && f.name === "read_notes") {
    send({ type: "tool_result", id: f.id,
           content: [{ type: "text", text: "(notes go here)" }] });
  } else if (f.type === "shutdown") {
    send({ type: "shutdown_ack" });
    rl.close();
  }
});

tsx install: npm install -g tsx. Without global tsx, fall back to "exec":"npx","args":["--yes","tsx","index.ts"] (slower startup; npx checks the registry every launch).

Python

{"name":"hello-py","version":"1.0.0","exec":"./hello.py","language":"python","enabled":true}

#!/usr/bin/env python3
import json, sys

def emit(o): sys.stdout.write(json.dumps(o) + "\n"); sys.stdout.flush()

emit({"type": "hello", "name": "hello-py", "version": "1.0.0", "capabilities": ["commands"]})
emit({"type": "register_command", "name": "hellopy", "description": "say hi (python)"})
emit({"type": "ready"})

for line in sys.stdin:
    msg = json.loads(line)
    if msg["type"] == "command_invoked":
        emit({"type": "command_response", "id": msg["id"],
              "action": "prompt", "prompt": "Say hi briefly."})
    elif msg["type"] == "shutdown":
        emit({"type": "shutdown_ack"})
        break

chmod +x hello.py.

Install / dev workflow

zot ext install ./weather       # copy into $ZOT_HOME/extensions/
zot --ext ./weather             # run from disk for one zot session (no install)
zot --ext .                     # cwd is the extension dir
zot ext list                    # show installed extensions
zot ext logs weather            # cat the extension's stderr
zot ext logs weather -f         # tail it
zot ext disable weather         # keep installed but skip on launch
zot ext enable weather
zot ext remove weather

For TS / Python extensions, no build step is needed — edit the source in place and relaunch zot.

For Go, run go build -o <name> . in the extension directory after edits, then zot ext install (which copies the manifest + binary) or zot --ext . to test from the working tree.

Manual debug

The extension is just a process. Drive it directly with shell pipes to see exactly what's happening on the wire:

{
  printf '%s\n' '{"type":"hello_ack","protocol_version":1,"zot_version":"x","provider":"a","model":"o","cwd":"/tmp"}'
  sleep 0.2
  printf '%s\n' '{"type":"command_invoked","id":"1","name":"weather","args":"Berlin"}'
  sleep 0.5
  printf '%s\n' '{"type":"shutdown"}'
} | ./weather

Compare what comes out of stdout to the expected wire format. If a frame doesn't match what zot expects, it's discarded silently and logged to ext-<name>.log.

Process to follow with the user

Ask what the extension should DO. One sentence.
Pick the right capability:
- "I want a slash command that triggers a prompt" → command only
- "I want the model to be able to do X" → tool
- "I want to gate / log every bash command" → event + intercept
Pick a language. Default to Go via pkg/zotext for new extensions if the user has Go installed; TypeScript via tsx if they prefer JS-flavored ergonomics; Python for one-off scripts.
Write the extension dir (manifest + source).
For Go, build it. For TS / Python, mark the script executable.
Suggest zot --ext <path> for testing without committing to an install.
When happy, zot ext install <path>.

Don't try to write a full SDK or framework on top of the protocol unless the user asked for one — the wire format is small enough that a 30-line raw script is the right answer for most extensions.

source

1---
2name: write-zot-extension
3description: Help the user create a new zot extension (slash command, LLM tool, or guard) in any language.
4---
5
6# Writing a zot extension
7
8Use this skill when the user asks for help building a zot extension —
9a new slash command, a new tool the LLM can call, an audit hook, or
10a permission gate. Skim this whole skill first, then collaborate
11with the user on the specific extension they want.
12
13## What an extension is
14
15A zot extension is **an external executable** that zot launches as a
16subprocess and talks to over its stdin/stdout in newline-delimited
17JSON. It can be written in any language that can read/write JSON
18lines from stdio: Go, TypeScript (via tsx), Python, Rust, shell with
19jq, anything. Crash isolation is automatic; one bad extension never
20takes down zot.
21
22Three things an extension can do (any combination):
23
241. **Slash commands** — register `/foo` so the user can run it from
25   the input. The handler returns a "prompt" (submitted to the
26   agent), an "insert" (text dropped into the editor), a "display"
27   (one-shot styled note in the chat), or a "noop".
28
292. **Tools** — register tools the LLM itself calls. Schema is
30   JSON Schema; zot routes the model's `tool_call` to the
31   extension's `tool_result`. Same lifecycle as built-in tools
32   (read/write/edit/bash/skill).
33
343. **Lifecycle hooks** — subscribe to events
35   (session_start, turn_start, tool_call, turn_end,
36   assistant_message) for telemetry / audit / custom UI, or
37   intercept tool calls before execution to refuse dangerous
38   patterns.
39
40## On-disk layout
41
42Each extension lives in its own directory:
43
44```
45~/Library/Application Support/zot/extensions/<name>/
46├── extension.json    # manifest (required)
47└── <executable>      # whatever exec points at
48```
49
50Or project-local: `<project>/.zot/extensions/<name>/`. Project-local
51wins on name conflict.
52
53For ad-hoc use during development, skip the install step entirely
54and run `zot --ext PATH` (repeatable: `-e PATH -e PATH`).
55
56### Manifest
57
58```json
59{
60  "name": "weather",
61  "version": "1.0.0",
62  "exec": "./weather",
63  "args": [],
64  "language": "go",
65  "description": "current weather lookups for any city",
66  "enabled": true
67}
68```
69
70Field rules:
71- `name` (required, unique) — id zot uses internally; matches the
72  hello frame. Slash commands & tools live in the same name space
73  as built-ins; conflicts are silently shadowed by built-ins.
74- `exec` (required) — the executable path. Resolution:
75  - absolute: as-is
76  - starts with `./` or `../`: relative to the manifest's directory
77  - bare name (no separator): looked up via `$PATH` (e.g. `node`,
78    `python3`, `npx`, `tsx`)
79- `args` — extra argv passed to `exec` (e.g. `["index.js"]`)
80- `language` — informational only (`"go"`, `"typescript"`,
81  `"python"`, etc.)
82- `enabled` — defaults to true; set false to keep installed but skip
83
84## Wire format
85
86Newline-delimited JSON in both directions. Top-level `type` is the
87discriminator. Optional `id` correlates command/tool requests with
88their responses.
89
90### Required handshake
91
92The very first frame the extension sends is `hello`:
93
94```json
95{"type":"hello","name":"weather","version":"1.0.0",
96 "capabilities":["commands","tools"]}
97```
98
99Capabilities are advisory; current values are `commands`, `tools`,
100`events`. Send all that apply.
101
102zot replies with `hello_ack`:
103
104```json
105{"type":"hello_ack","protocol_version":1,"zot_version":"0.0.x",
106 "provider":"anthropic","model":"claude-opus-4-7","cwd":"/path/to/project"}
107```
108
109### Registration (immediately after hello)
110
111Send registration frames in any order, then a single `ready`
112sentinel so zot can finalize the agent's tool registry:
113
114```json
115{"type":"register_command","name":"weather","description":"current weather"}
116{"type":"register_tool","name":"weather","description":"Get current weather for a city.",
117 "schema":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}
118{"type":"subscribe","events":["tool_call"],"intercept":["tool_call"]}
119{"type":"ready"}
120```
121
122If you don't send `ready`, zot's idle watchdog auto-treats you as
123ready after 250ms of no frames, but always send it explicitly when
124you can — newer extensions on faster hosts shave that 250ms off.
125
126### Runtime frames
127
128**zot → extension:**
129
130```json
131{"type":"command_invoked","id":"abc","name":"weather","args":"berlin"}
132{"type":"tool_call","id":"def","name":"weather","args":{"city":"Berlin"}}
133{"type":"event","event":"turn_start","step":1}
134{"type":"event_intercept","id":"ghi","event":"tool_call",
135 "tool_name":"bash","tool_args":{"command":"rm -rf /tmp/foo"}}
136{"type":"shutdown"}
137```
138
139**extension → zot (replies + spontaneous notifications):**
140
141```json
142{"type":"command_response","id":"abc","action":"prompt",
143 "prompt":"Show today's weather for Berlin in one line."}
144{"type":"tool_result","id":"def","content":[{"type":"text","text":"Berlin: 16°C, fog"}]}
145{"type":"event_intercept_response","id":"ghi","block":true,
146 "reason":"refused: command matches the danger pattern \"rm -rf\""}
147{"type":"notify","level":"info","message":"refreshed cache"}
148{"type":"shutdown_ack"}
149```
150
151`command_response.action` values:
152- `"prompt"` — submit `prompt` as a fresh user message
153- `"insert"` — drop `insert` into the editor at the cursor
154- `"display"` — append `display` to chat as a one-shot note (no
155  model call, not in transcript)
156- `"noop"` — handled internally; zot doesn't change the UI
157
158`tool_result.content[]` blocks: `{"type":"text","text":"..."}` or
159`{"type":"image","mime_type":"image/png","data":"<base64>"}`.
160
161Per-tool timeout: 60s. Per-intercept timeout: 5s. Missing the
162intercept timeout is treated as "allow" so an unresponsive guard
163never stalls the agent.
164
165## Important rules
166
167- **stdout is reserved for the protocol.** Anything you print to
168  stdout that isn't a JSON frame breaks the wire. Use stderr for
169  logs / debug output (zot captures stderr to
170  `$ZOT_HOME/logs/ext-<name>.log`).
171- **One JSON object per line.** No multi-line JSON. Always end
172  every frame with `\n`.
173- **Flush after writing.** Most stdout writes are line-buffered when
174  piped, which is fine, but explicitly flushing avoids surprise
175  buffering on slow handlers.
176- Extension processes inherit the user's permissions. A bad
177  extension can do anything the user can.
178
179## Recommended layout per language
180
181### Go (use the built-in SDK at pkg/zotext)
182
183```go
184package main
185
186import (
187    "encoding/json"
188    "github.com/patriceckhart/zot/pkg/zotext"
189)
190
191func main() {
192    ext := zotext.New("weather", "1.0.0")
193
194    ext.Command("weather", "current weather for a city",
195        func(args string) zotext.Response {
196            return zotext.Prompt("Tell me the weather for " + args)
197        })
198
199    ext.Tool("weather", "Get current weather for a city.",
200        json.RawMessage(`{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}`),
201        func(args json.RawMessage) zotext.ToolResult {
202            var in struct{ City string `json:"city"` }
203            if err := json.Unmarshal(args, &in); err != nil {
204                return zotext.TextErrorResult("invalid args")
205            }
206            return zotext.TextResult(in.City + ": sunny, 21°C (fake)")
207        })
208
209    if err := ext.Run(); err != nil {
210        ext.Logf("fatal: %v", err)
211    }
212}
213```
214
215Build: `go build -o weather .`
216
217`extension.json`:
218```json
219{"name":"weather","version":"1.0.0","exec":"./weather","language":"go","enabled":true}
220```
221
222### TypeScript (no SDK; handles the protocol directly)
223
224Run via `tsx`, which executes `.ts` files without a build step.
225
226```json
227{"name":"scratchpad","version":"1.0.0","exec":"tsx","args":["index.ts"],"language":"typescript","enabled":true}
228```
229
230```typescript
231// index.ts (excerpt; see examples/extensions/scratchpad/index.ts for the full version)
232import { createInterface } from "node:readline";
233import { stderr, stdin, stdout } from "node:process";
234
235function send(o: object) { stdout.write(JSON.stringify(o) + "\n"); }
236function log(s: string) { stderr.write(`[scratchpad] ${s}\n`); }
237
238send({ type: "hello", name: "scratchpad", version: "1.0.0",
239       capabilities: ["commands", "tools"] });
240send({ type: "register_command", name: "note", description: "append a note" });
241send({ type: "register_tool", name: "read_notes",
242       description: "Read the user's scratchpad notes.",
243       schema: { type: "object", properties: {} } });
244send({ type: "ready" });
245
246const rl = createInterface({ input: stdin, crlfDelay: Infinity });
247rl.on("line", (line) => {
248  const f = JSON.parse(line);
249  if (f.type === "command_invoked" && f.name === "note") {
250    send({ type: "command_response", id: f.id, action: "display",
251           display: `noted: ${f.args}` });
252  } else if (f.type === "tool_call" && f.name === "read_notes") {
253    send({ type: "tool_result", id: f.id,
254           content: [{ type: "text", text: "(notes go here)" }] });
255  } else if (f.type === "shutdown") {
256    send({ type: "shutdown_ack" });
257    rl.close();
258  }
259});
260```
261
262`tsx` install: `npm install -g tsx`. Without global tsx, fall back
263to `"exec":"npx","args":["--yes","tsx","index.ts"]` (slower
264startup; npx checks the registry every launch).
265
266### Python
267
268```json
269{"name":"hello-py","version":"1.0.0","exec":"./hello.py","language":"python","enabled":true}
270```
271
272```python
273#!/usr/bin/env python3
274import json, sys
275
276def emit(o): sys.stdout.write(json.dumps(o) + "\n"); sys.stdout.flush()
277
278emit({"type": "hello", "name": "hello-py", "version": "1.0.0", "capabilities": ["commands"]})
279emit({"type": "register_command", "name": "hellopy", "description": "say hi (python)"})
280emit({"type": "ready"})
281
282for line in sys.stdin:
283    msg = json.loads(line)
284    if msg["type"] == "command_invoked":
285        emit({"type": "command_response", "id": msg["id"],
286              "action": "prompt", "prompt": "Say hi briefly."})
287    elif msg["type"] == "shutdown":
288        emit({"type": "shutdown_ack"})
289        break
290```
291
292`chmod +x hello.py`.
293
294## Install / dev workflow
295
296```bash
297zot ext install ./weather       # copy into $ZOT_HOME/extensions/
298zot --ext ./weather             # run from disk for one zot session (no install)
299zot --ext .                     # cwd is the extension dir
300zot ext list                    # show installed extensions
301zot ext logs weather            # cat the extension's stderr
302zot ext logs weather -f         # tail it
303zot ext disable weather         # keep installed but skip on launch
304zot ext enable weather
305zot ext remove weather
306```
307
308For TS / Python extensions, no build step is needed — edit the source
309in place and relaunch zot.
310
311For Go, run `go build -o <name> .` in the extension directory after
312edits, then `zot ext install` (which copies the manifest + binary)
313or `zot --ext .` to test from the working tree.
314
315## Manual debug
316
317The extension is just a process. Drive it directly with shell pipes
318to see exactly what's happening on the wire:
319
320```bash
321{
322  printf '%s\n' '{"type":"hello_ack","protocol_version":1,"zot_version":"x","provider":"a","model":"o","cwd":"/tmp"}'
323  sleep 0.2
324  printf '%s\n' '{"type":"command_invoked","id":"1","name":"weather","args":"Berlin"}'
325  sleep 0.5
326  printf '%s\n' '{"type":"shutdown"}'
327} | ./weather
328```
329
330Compare what comes out of stdout to the expected wire format. If a
331frame doesn't match what zot expects, it's discarded silently and
332logged to `ext-<name>.log`.
333
334## Process to follow with the user
335
3361. Ask what the extension should DO. One sentence.
3372. Pick the right capability:
338   - "I want a slash command that triggers a prompt" → `command` only
339   - "I want the model to be able to do X" → `tool`
340   - "I want to gate / log every bash command" → `event` + `intercept`
3413. Pick a language. Default to **Go via pkg/zotext** for new
342   extensions if the user has Go installed; **TypeScript via tsx**
343   if they prefer JS-flavored ergonomics; **Python** for one-off
344   scripts.
3454. Write the extension dir (manifest + source).
3465. For Go, build it. For TS / Python, mark the script executable.
3476. Suggest `zot --ext <path>` for testing without committing to an
348   install.
3497. When happy, `zot ext install <path>`.
350
351Don't try to write a full SDK or framework on top of the protocol
352unless the user asked for one — the wire format is small enough
353that a 30-line raw script is the right answer for most extensions.

SKILL.md RawHistoryFolder