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":"clear_notes"}
{"type":"shutdown_ack"}

notify notes are one-shot: they clear when the user sends their next prompt (and on esc / /clear). Send clear_notes to retract every note this extension pushed earlier (e.g. a transient approval prompt) without waiting for the next turn; other extensions' notes are kept.

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 packages/agent/ext)

package main

import (
    "encoding/json"
    "github.com/patriceckhart/zot/packages/agent/ext"
)

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

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

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

    if err := e.Run(); err != nil {
        e.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 packages/agent/ext 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":"clear_notes"}
149{"type":"shutdown_ack"}
150```
151
152`notify` notes are one-shot: they clear when the user sends their next
153prompt (and on `esc` / `/clear`). Send `clear_notes` to retract every
154note this extension pushed earlier (e.g. a transient approval prompt)
155without waiting for the next turn; other extensions' notes are kept.
156
157`command_response.action` values:
158- `"prompt"` — submit `prompt` as a fresh user message
159- `"insert"` — drop `insert` into the editor at the cursor
160- `"display"` — append `display` to chat as a one-shot note (no
161  model call, not in transcript)
162- `"noop"` — handled internally; zot doesn't change the UI
163
164`tool_result.content[]` blocks: `{"type":"text","text":"..."}` or
165`{"type":"image","mime_type":"image/png","data":"<base64>"}`.
166
167Per-tool timeout: 60s. Per-intercept timeout: 5s. Missing the
168intercept timeout is treated as "allow" so an unresponsive guard
169never stalls the agent.
170
171## Important rules
172
173- **stdout is reserved for the protocol.** Anything you print to
174  stdout that isn't a JSON frame breaks the wire. Use stderr for
175  logs / debug output (zot captures stderr to
176  `$ZOT_HOME/logs/ext-<name>.log`).
177- **One JSON object per line.** No multi-line JSON. Always end
178  every frame with `\n`.
179- **Flush after writing.** Most stdout writes are line-buffered when
180  piped, which is fine, but explicitly flushing avoids surprise
181  buffering on slow handlers.
182- Extension processes inherit the user's permissions. A bad
183  extension can do anything the user can.
184
185## Recommended layout per language
186
187### Go (use the built-in SDK at packages/agent/ext)
188
189```go
190package main
191
192import (
193    "encoding/json"
194    "github.com/patriceckhart/zot/packages/agent/ext"
195)
196
197func main() {
198    e := ext.New("weather", "1.0.0")
199
200    e.Command("weather", "current weather for a city",
201        func(args string) ext.Response {
202            return ext.Prompt("Tell me the weather for " + args)
203        })
204
205    e.Tool("weather", "Get current weather for a city.",
206        json.RawMessage(`{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}`),
207        func(args json.RawMessage) ext.ToolResult {
208            var in struct{ City string `json:"city"` }
209            if err := json.Unmarshal(args, &in); err != nil {
210                return ext.TextErrorResult("invalid args")
211            }
212            return ext.TextResult(in.City + ": sunny, 21°C (fake)")
213        })
214
215    if err := e.Run(); err != nil {
216        e.Logf("fatal: %v", err)
217    }
218}
219```
220
221Build: `go build -o weather .`
222
223`extension.json`:
224```json
225{"name":"weather","version":"1.0.0","exec":"./weather","language":"go","enabled":true}
226```
227
228### TypeScript (no SDK; handles the protocol directly)
229
230Run via `tsx`, which executes `.ts` files without a build step.
231
232```json
233{"name":"scratchpad","version":"1.0.0","exec":"tsx","args":["index.ts"],"language":"typescript","enabled":true}
234```
235
236```typescript
237// index.ts (excerpt; see examples/extensions/scratchpad/index.ts for the full version)
238import { createInterface } from "node:readline";
239import { stderr, stdin, stdout } from "node:process";
240
241function send(o: object) { stdout.write(JSON.stringify(o) + "\n"); }
242function log(s: string) { stderr.write(`[scratchpad] ${s}\n`); }
243
244send({ type: "hello", name: "scratchpad", version: "1.0.0",
245       capabilities: ["commands", "tools"] });
246send({ type: "register_command", name: "note", description: "append a note" });
247send({ type: "register_tool", name: "read_notes",
248       description: "Read the user's scratchpad notes.",
249       schema: { type: "object", properties: {} } });
250send({ type: "ready" });
251
252const rl = createInterface({ input: stdin, crlfDelay: Infinity });
253rl.on("line", (line) => {
254  const f = JSON.parse(line);
255  if (f.type === "command_invoked" && f.name === "note") {
256    send({ type: "command_response", id: f.id, action: "display",
257           display: `noted: ${f.args}` });
258  } else if (f.type === "tool_call" && f.name === "read_notes") {
259    send({ type: "tool_result", id: f.id,
260           content: [{ type: "text", text: "(notes go here)" }] });
261  } else if (f.type === "shutdown") {
262    send({ type: "shutdown_ack" });
263    rl.close();
264  }
265});
266```
267
268`tsx` install: `npm install -g tsx`. Without global tsx, fall back
269to `"exec":"npx","args":["--yes","tsx","index.ts"]` (slower
270startup; npx checks the registry every launch).
271
272### Python
273
274```json
275{"name":"hello-py","version":"1.0.0","exec":"./hello.py","language":"python","enabled":true}
276```
277
278```python
279#!/usr/bin/env python3
280import json, sys
281
282def emit(o): sys.stdout.write(json.dumps(o) + "\n"); sys.stdout.flush()
283
284emit({"type": "hello", "name": "hello-py", "version": "1.0.0", "capabilities": ["commands"]})
285emit({"type": "register_command", "name": "hellopy", "description": "say hi (python)"})
286emit({"type": "ready"})
287
288for line in sys.stdin:
289    msg = json.loads(line)
290    if msg["type"] == "command_invoked":
291        emit({"type": "command_response", "id": msg["id"],
292              "action": "prompt", "prompt": "Say hi briefly."})
293    elif msg["type"] == "shutdown":
294        emit({"type": "shutdown_ack"})
295        break
296```
297
298`chmod +x hello.py`.
299
300## Install / dev workflow
301
302```bash
303zot ext install ./weather       # copy into $ZOT_HOME/extensions/
304zot --ext ./weather             # run from disk for one zot session (no install)
305zot --ext .                     # cwd is the extension dir
306zot ext list                    # show installed extensions
307zot ext logs weather            # cat the extension's stderr
308zot ext logs weather -f         # tail it
309zot ext disable weather         # keep installed but skip on launch
310zot ext enable weather
311zot ext remove weather
312```
313
314For TS / Python extensions, no build step is needed — edit the source
315in place and relaunch zot.
316
317For Go, run `go build -o <name> .` in the extension directory after
318edits, then `zot ext install` (which copies the manifest + binary)
319or `zot --ext .` to test from the working tree.
320
321## Manual debug
322
323The extension is just a process. Drive it directly with shell pipes
324to see exactly what's happening on the wire:
325
326```bash
327{
328  printf '%s\n' '{"type":"hello_ack","protocol_version":1,"zot_version":"x","provider":"a","model":"o","cwd":"/tmp"}'
329  sleep 0.2
330  printf '%s\n' '{"type":"command_invoked","id":"1","name":"weather","args":"Berlin"}'
331  sleep 0.5
332  printf '%s\n' '{"type":"shutdown"}'
333} | ./weather
334```
335
336Compare what comes out of stdout to the expected wire format. If a
337frame doesn't match what zot expects, it's discarded silently and
338logged to `ext-<name>.log`.
339
340## Process to follow with the user
341
3421. Ask what the extension should DO. One sentence.
3432. Pick the right capability:
344   - "I want a slash command that triggers a prompt" → `command` only
345   - "I want the model to be able to do X" → `tool`
346   - "I want to gate / log every bash command" → `event` + `intercept`
3473. Pick a language. Default to **Go via packages/agent/ext** for new
348   extensions if the user has Go installed; **TypeScript via tsx**
349   if they prefer JS-flavored ergonomics; **Python** for one-off
350   scripts.
3514. Write the extension dir (manifest + source).
3525. For Go, build it. For TS / Python, mark the script executable.
3536. Suggest `zot --ext <path>` for testing without committing to an
354   install.
3557. When happy, `zot ext install <path>`.
356
357Don't try to write a full SDK or framework on top of the protocol
358unless the user asked for one — the wire format is small enough
359that a 30-line raw script is the right answer for most extensions.

SKILL.md RawHistoryFolder