1# zot extensions
2
3zot can be extended with custom slash commands by running an external
4program as a subprocess and exchanging newline-delimited JSON over
5its stdin/stdout. Extensions can be written in **any language** that
6can read and write JSON lines from stdio — Go, TypeScript, Python,
7Rust, shell with `jq`, anything.
8
9Four phases shipped so far:
10
11- **Phase 1**: slash commands + chat notifications.
12- **Phase 2**: tools the LLM can call.
13- **Phase 3**: lifecycle event subscriptions + tool-call interception
14  for guardrail extensions.
15- **Phase 4**: interactive extension-owned panels rendered inside zot.
16- **Theme-only extensions**: ship `theme.json` without launching a
17  subprocess. See [themes.md](themes.md).
18
19## Quick start
20
21The simplest extension is a script that prints a hello frame, reads
22commands, and prints responses. Here's the whole thing in **Python**,
23no SDK required:
24
25```python
26#!/usr/bin/env python3
27# $ZOT_HOME/extensions/hello-py/hello.py
28import json, sys
29
30def emit(obj):
31    sys.stdout.write(json.dumps(obj) + "\n")
32    sys.stdout.flush()
33
34emit({"type":"hello","name":"hello-py","version":"1.0.0","capabilities":["commands"]})
35
36for line in sys.stdin:
37    msg = json.loads(line)
38    if msg["type"] == "hello_ack":
39        emit({"type":"register_command","name":"hellopy","description":"say hi (python)"})
40        emit({"type":"ready"})
41    elif msg["type"] == "command_invoked":
42        emit({"type":"command_response","id":msg["id"],"action":"prompt",
43              "prompt": "Greet me very briefly in one sentence."})
44    elif msg["type"] == "shutdown":
45        emit({"type":"shutdown_ack"})
46        break
47```
48
49Drop it in a directory with this `extension.json`:
50
51```json
52{
53  "name": "hello-py",
54  "version": "1.0.0",
55  "exec": "./hello.py",
56  "language": "python",
57  "enabled": true
58}
59```
60
61`exec` is required for protocol extensions. If an extension only ships
62`theme.json` or `themes/theme.json`, no `exec` is required and zot does
63not spawn a subprocess.
64
65`chmod +x hello.py`, install:
66
67```bash
68zot ext install ./hello-py
69```
70
71Restart `zot`, type `/hellopy`, the agent greets you. Done.
72
73## Built-in extensions
74
75**zot ships with no extensions installed by default.** A fresh `zot install` (or `go install`) gives you a clean agent. Extensions are entirely opt-in: you install (or `--ext` for one run) only the ones you want.
76
77The `examples/extensions/` directory in the repo is reference code, not a default install set. To use any of those:
78
79```bash
80# go-based examples need a build first
81cd path/to/zot/examples/extensions/hello && go build -o hello .
82
83# install (copies to $ZOT_HOME/extensions/hello/)
84zot ext install path/to/zot/examples/extensions/hello
85
86# or load straight from the repo for one zot session
87zot --ext path/to/zot/examples/extensions/hello
88```
89
90Nothing is auto-installed and nothing reaches out to the network without your explicit action.
91
92## Layout & discovery
93
94zot scans two directories on startup, in this order:
95
961. **Project-local**: `./.zot/extensions/<name>/extension.json`
972. **Global**: `$ZOT_HOME/extensions/<name>/extension.json`
98
99A project-local extension with the same name wins over a global one.
100On macOS `$ZOT_HOME` defaults to `~/Library/Application Support/zot/`;
101on Linux it's `$XDG_STATE_HOME/zot` or `~/.local/state/zot`.
102
103Because each extension owns its own directory, the recommended place
104for extension state is inside that directory itself (for example
105`todos.json`, `settings.json`, or an auth/cache file used only by that
106extension). The host also passes this path back in `hello_ack` as
107`extension_dir` / `data_dir` so runtime code does not need to guess it.
108
109Each extension owns its own subdirectory. The `extension.json`
110manifest tells zot how to launch it:
111
112```json
113{
114  "name": "weather",
115  "version": "1.0.0",
116  "exec": "./weather",
117  "args": ["--mode", "daemon"],
118  "language": "go",
119  "description": "current weather for any city",
120  "enabled": true
121}
122```
123
124| field | meaning |
125|---|---|
126| `name` | required. how zot identifies the extension; must match what's sent in the `hello` frame. |
127| `version` | optional. shown in `zot ext list`. |
128| `exec` | required. path to the executable (relative to the manifest). |
129| `args` | optional. extra argv passed to `exec`. |
130| `language` | optional. informational only (`go`, `python`, `typescript`, ...). |
131| `description` | optional. shown in `zot ext list`. |
132| `enabled` | optional, defaults to `true`. set to `false` to disable without removing. |
133
134## Lifecycle
135
1361. **Discovery**: zot reads every `extension.json` in the search dirs.
1372. **Spawn**: enabled extensions are launched as subprocesses. stderr
138   redirects to `$ZOT_HOME/logs/ext-<name>.log` (one file per
139   extension, append-mode).
1403. **Hello handshake**: the extension's first stdout frame must be
141   `hello`; zot replies with `hello_ack` containing the protocol
142   version, the active provider/model/cwd, and the extension's own
143   data directory so it can persist files beside its manifest.
1444. **Registration**: after receiving `hello_ack`, the extension sends
145   `register_command`, `register_tool`, and subscription frames, then
146   sends `ready`. First-come-first-served: a name already taken by a
147   built-in or by a previously-loaded extension is silently shadowed
148   (logged in the extension's own log file).
1495. **Runtime**: after `ready`, zot dispatches `command_invoked` frames
150   when the user runs a registered command; the extension responds
151   with `command_response`. Extensions can also push `notify` frames
152   during runtime. Panel-capable extensions may open an interactive
153   panel, receive key events, and push redraws while the panel is
154   focused.
1556. **Shutdown**: when zot exits, it sends `shutdown` and waits up to
156   2s for the extension to send `shutdown_ack`. Holdouts are
157   SIGTERM'd, then SIGKILL'd.
158
159A crashing extension does not bring down zot. The slash command it
160owned simply stops working until the extension is fixed and zot is
161restarted.
162
163## Wire format
164
165All frames are one JSON object per line. Top-level `type` is the
166discriminator. Optional `id` correlates request frames with their
167responses. The canonical startup order is `hello`, `hello_ack`,
168registration frames, then `ready`. Do not send `notify`, logs, or any
169other stdout frame before `hello`.
170
171### Extension → host
172
173#### `hello` (required, first frame)
174
175```json
176{"type":"hello","name":"weather","version":"1.0.0",
177 "capabilities":["commands","tools","panels"]}
178```
179
180#### `register_command`
181
182```json
183{"type":"register_command","name":"weather",
184 "description":"current weather for a city"}
185```
186
187#### `register_tool`
188
189Registers a tool the LLM can call. `schema` is a JSON Schema object
190describing the tool's args (the same shape Anthropic and OpenAI accept).
191
192```json
193{"type":"register_tool","name":"weather",
194 "description":"Get the current weather for a city.",
195 "schema":{
196   "type":"object",
197   "properties":{"city":{"type":"string"}},
198   "required":["city"]
199 }}
200```
201
202Tool names live in the same namespace as built-in tools (`read`,
203`write`, `edit`, `bash`, `skill`). Conflicts are silently shadowed by
204the built-in.
205
206#### `ready`
207
208Sentinel telling zot "all initial registrations are flushed". Send it
209right after your last `register_*` frame so the host can build the
210agent's tool registry without racing the registration window.
211
212```json
213{"type":"ready"}
214```
215
216#### `tool_result`
217
218Reply to a `tool_call` from the host. `content[]` is a list of
219message blocks; each block is `{"type":"text","text":"..."}` or
220`{"type":"image","mime_type":"image/png","data":"<base64>"}`. Set
221`is_error: true` to mark the call as failed.
222
223```json
224{"type":"tool_result","id":"...",
225 "content":[{"type":"text","text":"Berlin: 16°C, fog"}]}
226```
227
228#### `subscribe`
229
230Declares which lifecycle events the extension wants to observe and
231which it wants to intercept. Send once after `hello`, before `ready`.
232
233```json
234{"type":"subscribe",
235 "events":["session_start","turn_start","tool_call","turn_end","assistant_message"],
236 "intercept":["tool_call","turn_start","assistant_message"]}
237```
238
239Recognised event names: `session_start`, `turn_start`, `turn_end`,
240`tool_call`, `assistant_message`.
241
242Interceptable events:
243
244- `tool_call`: block the call (model sees `reason` as the tool
245  error) or rewrite args via `modified_args`.
246- `turn_start`: block the turn before the model is called. Useful
247  for rate-limiting and business-hour gates. `reason` is shown to
248  the user as a status line. No rewrite supported.
249- `assistant_message`: suppress the message via `block`, or rewrite
250  the user-visible text via `replace_text`. The model's original
251  text stays in the transcript so the model sees what it actually
252  said on subsequent turns.
253
254#### `event_intercept_response`
255
256Reply to an `event_intercept` from the host. All fields default to
257"allow, pass through unmodified".
258
259| field | meaning |
260|---|---|
261| `block` | `true` refuses the action. For `tool_call`, `reason` is shown to the model; for `turn_start` / `assistant_message`, `reason` is shown to the user. |
262| `reason` | refusal text (on block) or pass-through note. |
263| `modified_args` | for `tool_call`: rewritten JSON args the tool will actually see. Must be a valid JSON object. Ignored when `block` is true. |
264| `replace_text` | for `assistant_message`: replaces the user-visible text. The model's original output still lives in the transcript. Ignored when `block` is true. |
265
266Missing the response within 5s is treated as "allow" (i.e. an
267unresponsive extension never stalls the agent). When multiple
268extensions subscribe to the same event, they're consulted serially;
269the first `block` wins and rewrites (args / text) chain: each
270subsequent interceptor sees the previous one's output.
271
272```json
273{"type":"event_intercept_response","id":"...",
274 "block":true,"reason":"refused: matches danger pattern \"rm -rf\""}
275
276{"type":"event_intercept_response","id":"...",
277 "modified_args":{"command":"echo GUARDED: ls"}}
278
279{"type":"event_intercept_response","id":"...",
280 "replace_text":"[redacted]"}
281```
282
283#### `command_response` (reply to `command_invoked`)
284
285```json
286{"type":"command_response","id":"...","action":"prompt",
287 "prompt":"Show today's weather for Berlin in one line."}
288```
289
290`action` is one of:
291
292- `"prompt"` — submits `prompt` as a fresh user message; the agent
293  runs a turn against it.
294- `"insert"` — inserts `insert` into the editor at the cursor without
295  submitting.
296- `"display"` — appends `display` to the chat as a one-shot styled
297  note. No model call, nothing written to the transcript.
298- `"open_panel"` — opens an extension-owned interactive panel inside
299  zot. The panel content lives in `open_panel`.
300- `"noop"` — the extension handled it itself (e.g. it pushed
301  `notify` frames or kicked off background work). zot doesn't change
302  the UI in response.
303
304Example:
305
306```json
307{"type":"command_response","id":"...","action":"open_panel",
308 "open_panel":{
309   "id":"todos-main",
310   "title":"Todos",
311   "lines":["□ ship panel api","✓ persist state"],
312   "footer":"↑/↓ navigate - a add - x complete - esc close"
313 }}
314```
315
316If `error` is non-empty, zot renders it as a red status line
317regardless of `action`.
318
319#### `submit` (one-way, any time)
320
321Submits text as a user prompt in the interactive host. If the agent is
322idle, zot starts a turn immediately. If a turn is already running, zot
323queues the prompt behind it using the same queue path as typed input.
324Empty or whitespace-only text is ignored.
325
326```json
327{"type":"submit","text":"Summarize the selected workspace."}
328```
329
330In print / JSON / RPC modes this frame is ignored because there is no
331interactive editor or prompt queue.
332
333#### `panel_render` (one-way, while a panel is open)
334
335Pushes a fresh frame for an already-open panel.
336
337```json
338{"type":"panel_render","panel_id":"todos-main",
339 "title":"Todos",
340 "lines":["□ ship panel api","✓ persist state"],
341 "footer":"↑/↓ navigate - a add - x complete - esc close"}
342```
343
344#### `panel_close`
345
346Closes a previously-open panel.
347
348```json
349{"type":"panel_close","panel_id":"todos-main"}
350```
351
352#### `notify` (one-way, any time)
353
354```json
355{"type":"notify","level":"info",
356 "message":"refreshed cache (12 entries)"}
357```
358
359`level` is one of `info`, `success`, `warn`, `error`. The note shows
360up below the transcript with the extension's name in brackets. Notes
361are one-shot: they clear automatically when the user sends their next
362prompt (and on `esc` / `/clear`).
363
364#### `clear_notes` (one-way, any time)
365
366Removes every note this extension previously pushed via `notify` /
367`display`. Use it for transient status lines (e.g. an approval prompt)
368so they do not stack up; notes from other extensions are untouched.
369
370```json
371{"type":"clear_notes"}
372```
373
374In `--mode rpc`, this surfaces to the host as an `ext_clear_notes`
375event (alongside `ext_notify` / `ext_display`).
376
377#### `shutdown_ack`
378
379Sent in response to `shutdown`. Extension should exit promptly after.
380
381### Host → extension
382
383#### `hello_ack`
384
385```json
386{"type":"hello_ack","protocol_version":1,
387 "zot_version":"0.0.7","provider":"anthropic",
388 "model":"claude-opus-4-7","cwd":"/Users/pat/Developer/zot",
389 "extension_dir":"/Users/pat/Developer/zot/.zot/extensions/todos",
390 "data_dir":"/Users/pat/Developer/zot/.zot/extensions/todos"}
391```
392
393Sent immediately after `hello`. Wait for this frame before sending
394registrations if they depend on host metadata. The extension can use
395these fields to decide which commands to register (e.g. only register
396a Python tool on macOS, only register a model-specific shortcut for
397opus, etc.). `cwd` is the user's project directory; the extension
398process itself runs from the extension directory, so do not use
399`os.Getwd()` or `process.cwd()` when you need the project path.
400`extension_dir` / `data_dir` are where the extension should persist
401its own state (for example `todos.json`, cached metadata, or auth
402tokens scoped to that extension).
403
404#### `command_invoked`
405
406```json
407{"type":"command_invoked","id":"...",
408 "name":"weather","args":"berlin"}
409```
410
411`args` is everything the user typed after the command name, trimmed.
412
413#### `tool_call`
414
415Sent when the LLM invokes a tool the extension registered. `args` is
416the parsed JSON object the model produced; the extension is
417responsible for validating/coercing it.
418
419```json
420{"type":"tool_call","id":"...","name":"weather",
421 "args":{"city":"Berlin"}}
422```
423
424Reply with `tool_result` within the host's tool timeout (default 60s).
425Missing the timeout surfaces an error to the model and the call is
426marked as failed.
427
428#### `event`
429
430Lifecycle notification for events the extension subscribed to via
431`subscribe`. One-way — no response expected.
432
433```json
434{"type":"event","event":"turn_start","step":1}
435{"type":"event","event":"tool_call",
436 "tool_id":"...","tool_name":"read","tool_args":{"path":"foo.go"}}
437{"type":"event","event":"turn_end","stop":"end_turn"}
438```
439
440#### `event_intercept`
441
442Sent when zot wants to give the extension a chance to block, modify,
443or annotate a lifecycle event before it happens. Reply with
444`event_intercept_response` within 5s; missing the deadline is
445treated as "allow".
446
447Payload fields depend on the event:
448
449```json
450// tool_call: includes the tool id, name, and parsed args
451{"type":"event_intercept","id":"...","event":"tool_call",
452 "tool_id":"...","tool_name":"bash",
453 "tool_args":{"command":"rm -rf /tmp/foo"}}
454
455// turn_start: includes the step number
456{"type":"event_intercept","id":"...","event":"turn_start",
457 "step":3}
458
459// assistant_message: includes the assembled text
460{"type":"event_intercept","id":"...","event":"assistant_message",
461 "text":"here is your api key: sk-ant-..."}
462```
463
464#### `panel_key`
465
466Sent while an extension-owned panel is focused. `key` is a normalized
467name (`up`, `down`, `left`, `right`, `enter`, `esc`, `tab`, `pageup`,
468`pagedown`, `home`, `end`, `backspace`, `delete`, `rune`). For
469`key:"rune"`, `text` carries the typed character.
470
471```json
472{"type":"panel_key","panel_id":"todos-main","key":"down"}
473{"type":"panel_key","panel_id":"todos-main","key":"rune","text":"x"}
474```
475
476#### `panel_close`
477
478Sent when the user closes the focused panel from zot (for example with
479Esc or Ctrl+C). The extension should treat this as the panel lifetime
480ending and stop sending `panel_render` updates for that `panel_id`.
481
482```json
483{"type":"panel_close","panel_id":"todos-main"}
484```
485
486#### `shutdown`
487
488Sent during graceful zot exit (or `/reload-ext` once that lands).
489Reply with `shutdown_ack` and then exit.
490
491## Managing extensions from the CLI
492
493```
494zot ext list                    list installed extensions and their state
495zot ext doctor                  diagnose load, registration, and conflict issues
496zot ext install <path|git-url>  copy / clone into $ZOT_HOME/extensions/
497zot ext remove <name>           delete an extension directory
498zot ext enable <name>           re-enable a disabled extension
499zot ext disable <name>          disable without removing
500zot ext logs <name> [-f]        cat / tail the extension's stderr
501```
502
503`zot ext doctor` runs the same discovery path as zot startup, but reports
504what happened instead of changing the fail-soft runtime behavior. It shows
505manifest errors, disabled or shadowed extensions, subprocess load errors,
506ready/auto-ready status, registered commands/tools, registration conflicts,
507warnings, and each extension's stderr log path.
508
509`zot ext install <path>` does a recursive copy; `<git-url>` does a
510shallow clone. Both validate that the destination contains an
511`extension.json` and roll back if not.
512
513## Loading an extension for one run
514
515For iteration on a working copy, skip the install + reload cycle
516and load straight from disk for one zot session:
517
518```
519zot --ext ./my-extension        # short form: -e ./my-extension
520zot --ext ./a -e ./b            # repeatable
521```
522
523`--ext` paths take precedence over installed extensions of the same
524name, so you can shadow an installed copy with a work-in-progress
525version without uninstalling first. Nothing is copied or persisted;
526the extension dies with zot like any other subprocess.
527
528## SDKs
529
530Writing the wire protocol by hand is fine for one-off scripts, but
531for anything bigger the SDKs handle the boilerplate.
532
533### Go — `packages/agent/ext`
534
535```go
536package main
537
538import (
539    "encoding/json"
540    "github.com/patriceckhart/zot/packages/agent/ext"
541)
542
543func main() {
544    e := ext.New("hello", "1.0.0")
545
546    // Slash command
547    e.Command("hello", "say hi", func(args string) ext.Response {
548        return ext.Prompt("Greet me in one short sentence.")
549    })
550
551    // LLM-callable tool
552    e.Tool("weather", "Current weather for a city.",
553        json.RawMessage(`{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}`),
554        func(args json.RawMessage) ext.ToolResult {
555            var in struct{ City string `json:"city"` }
556            json.Unmarshal(args, &in)
557            return ext.TextResult(in.City + ": sunny")
558        })
559
560    // Optional: register project-specific commands after hello_ack.
561    e.OnHello(func(host ext.HostInfo) {
562        if host.CWD != "" {
563            e.Command("cwd", "show the current project directory", func(args string) ext.Response {
564                return ext.Display(host.CWD)
565            })
566        }
567    })
568
569    e.Run()
570}
571```
572
573Build with `go build -o hello .`, drop the binary + an `extension.json`
574into `$ZOT_HOME/extensions/hello/`.
575
576`OnHello` is optional. Use it when configuration or registrations need
577host metadata such as `HostInfo.CWD`, `Provider`, `Model`, `ZotVersion`,
578`ExtensionDir`, or `DataDir`. The SDK sends `hello`, waits for
579`hello_ack`, runs `OnHello`, announces registrations, then sends `ready`.
580
581The SDK has four interceptor hooks, all optional:
582
583```go
584// e is the *ext.Extension returned by ext.New(...).
585
586// Refuse calls or rewrite args before they run.
587e.InterceptToolCall(func(tool string, args json.RawMessage) (bool, string) {
588    if tool == "bash" { /* inspect args, return false, reason */ }
589    return true, ""
590})
591
592// Richer variant: returns ToolCallDecision so you can also rewrite
593// args via ModifiedArgs.
594e.InterceptToolCallX(func(tool string, args json.RawMessage) ext.ToolCallDecision {
595    return ext.ToolCallDecision{
596        ModifiedArgs: json.RawMessage(`{"command":"echo GUARDED"}`),
597    }
598})
599
600// Block the next turn before the model is called.
601e.InterceptTurnStart(func(step int) ext.TurnStartDecision {
602    if time.Now().Hour() < 9 { return ext.TurnStartDecision{Block: true, Reason: "outside business hours"} }
603    return ext.TurnStartDecision{}
604})
605
606// Scrub or rewrite the assistant's final text before the user sees it.
607e.InterceptAssistantMessage(func(text string) ext.AssistantMessageDecision {
608    return ext.AssistantMessageDecision{
609        ReplaceText: strings.ReplaceAll(text, "SECRET", "[redacted]"),
610    }
611})
612```
613
614See:
615- `examples/extensions/hello/` — slash commands
616- `examples/extensions/clock/` — slash commands in plain Node, no SDK
617- `examples/extensions/weather/` — LLM-callable tool
618- `examples/extensions/guard/` — event subscriptions + tool-call
619  interception (refuses dangerous bash patterns)
620- `examples/extensions/todo/` — interactive persistent panel + tool
621- `examples/extensions/scratchpad/` — source-run TypeScript commands + tool
622
623### Hot reload
624
625Type `/reload-ext` in the TUI to tear down every running extension
626subprocess, re-read the manifests from disk, and respawn the set.
627The agent's tool registry is rebuilt automatically, so freshly-
628registered extension tools become callable without restarting zot.
629Useful while developing an extension: edit, save, `/reload-ext`,
630done. Explicit `--ext` paths are remembered and reloaded alongside
631discovered extensions.
632
633### TypeScript / Python
634
635These SDKs aren't in the main repo yet; the wire format is small
636enough that a `~30 line` raw script gets you started in either
637language. See the [Quick start](#quick-start) Python example for the
638shape. SDK packages will land in follow-up commits.
639
640## Security
641
642Extensions run with **the user's full filesystem and network
643permissions**. Treat installing an extension the same as installing
644any other binary on your machine.
645
646`zot ext install <git-url>` clones from any URL you give it. There's
647no sandbox in v1; if you need isolation, install only extensions you
648trust or run zot under your platform's sandboxing tool (`bwrap` /
649`sandbox-exec` / AppContainer).
650
651## Roadmap
652
653Phase 1 (shipped):
654- [x] subprocess lifecycle + hello handshake
655- [x] `register_command` + `command_invoked`
656- [x] `notify` + `clear_notes`
657- [x] `zot ext` CLI
658
659Phase 2 (shipped):
660- [x] `register_tool` + `tool_call` + `tool_result`
661- [x] `ready` sentinel for safe agent-registry build timing
662- [x] tool result attribution surfaces extension name in details
663
664Phase 3 (shipped):
665- [x] event subscriptions (`session_start`, `turn_start`, `turn_end`,
666      `tool_call`, `assistant_message`)
667- [x] tool-call interception (block before execution)
668
669Phase 4 (shipped):
670- [x] interception for `turn_start` and `assistant_message` (in
671      addition to `tool_call`)
672- [x] modify tool args mid-flight via `modified_args`
673- [x] rewrite user-visible assistant text via `replace_text`
674- [x] `/reload-ext` slash command (hot-reload without restarting zot)
675
676Future (no firm timeline):
677- [ ] TypeScript and Python SDK packages (currently the wire format
678      is stable enough to hand-roll, see the Python quick-start)
679- [ ] HTTP / WebSocket transport variants (today: subprocess stdio)
680- [ ] per-extension permission scopes (today: full user privileges)