extensions.md Raw History Folder

zot extensions

zot can be extended with custom slash commands by running an external program as a subprocess and exchanging newline-delimited JSON over its stdin/stdout. Extensions can be written in any language that can read and write JSON lines from stdio — Go, TypeScript, Python, Rust, shell with jq, anything.

Three phases shipped so far:

Phase 1: slash commands + chat notifications.
Phase 2: tools the LLM can call.
Phase 3: lifecycle event subscriptions + tool-call interception for guardrail extensions.

Quick start

The simplest extension is a script that prints a hello frame, reads commands, and prints responses. Here's the whole thing in Python, no SDK required:

#!/usr/bin/env python3
# $ZOT_HOME/extensions/hello-py/hello.py
import json, sys, threading

def emit(obj):
    sys.stdout.write(json.dumps(obj) + "\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)"})

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

Drop it in a directory with this extension.json:

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

chmod +x hello.py, install:

zot ext install ./hello-py

Restart zot, type /hellopy, the agent greets you. Done.

Built-in extensions

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.

The examples/extensions/ directory in the repo is reference code, not a default install set. To use any of those:

# go-based examples need a build first
cd path/to/zot/examples/extensions/hello && go build -o hello .

# install (copies to $ZOT_HOME/extensions/hello/)
zot ext install path/to/zot/examples/extensions/hello

# or load straight from the repo for one zot session
zot --ext path/to/zot/examples/extensions/hello

Nothing is auto-installed and nothing reaches out to the network without your explicit action.

Layout & discovery

zot scans two directories on startup, in this order:

Project-local: ./.zot/extensions/<name>/extension.json
Global: $ZOT_HOME/extensions/<name>/extension.json

A project-local extension with the same name wins over a global one. On macOS $ZOT_HOME defaults to ~/Library/Application Support/zot/; on Linux it's $XDG_STATE_HOME/zot or ~/.local/state/zot.

Each extension owns its own subdirectory. The extension.json manifest tells zot how to launch it:

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

field	meaning
`name`	required. how zot identifies the extension; must match what's sent in the `hello` frame.
`version`	optional. shown in `zot ext list`.
`exec`	required. path to the executable (relative to the manifest).
`args`	optional. extra argv passed to `exec`.
`language`	optional. informational only (`go`, `python`, `typescript`, ...).
`description`	optional. shown in `zot ext list`.
`enabled`	optional, defaults to `true`. set to `false` to disable without removing.

Lifecycle

Discovery: zot reads every extension.json in the search dirs.
Spawn: enabled extensions are launched as subprocesses. stderr redirects to $ZOT_HOME/logs/ext-<name>.log (one file per extension, append-mode).
Hello handshake: the extension sends a hello frame; zot replies with hello_ack containing the protocol version and the active provider/model/cwd.
Registration: the extension sends register_command frames. First-come-first-served: a name already taken by a built-in or by a previously-loaded extension is silently shadowed (logged in the extension's own log file).
Runtime: zot dispatches command_invoked frames when the user runs a registered command; the extension responds with command_response. Extensions can also push notify frames at any time.
Shutdown: when zot exits, it sends shutdown and waits up to 2s for the extension to send shutdown_ack. Holdouts are SIGTERM'd, then SIGKILL'd.

A crashing extension does not bring down zot. The slash command it owned simply stops working until the extension is fixed and zot is restarted.

Wire format

All frames are one JSON object per line. Top-level type is the discriminator. Optional id correlates request frames with their responses.

Extension → host

`hello` (required, first frame)

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

`register_command`

{"type":"register_command","name":"weather",
 "description":"current weather for a city"}

`register_tool`

Registers a tool the LLM can call. schema is a JSON Schema object describing the tool's args (the same shape Anthropic and OpenAI accept).

{"type":"register_tool","name":"weather",
 "description":"Get the current weather for a city.",
 "schema":{
   "type":"object",
   "properties":{"city":{"type":"string"}},
   "required":["city"]
 }}

Tool names live in the same namespace as built-in tools (read, write, edit, bash, skill). Conflicts are silently shadowed by the built-in.

`ready`

Sentinel telling zot "all initial registrations are flushed". Send it right after your last register_* frame so the host can build the agent's tool registry without racing the registration window.

{"type":"ready"}

`tool_result`

Reply to a tool_call from the host. content[] is a list of message blocks; each block is {"type":"text","text":"..."} or {"type":"image","mime_type":"image/png","data":"<base64>"}. Set is_error: true to mark the call as failed.

{"type":"tool_result","id":"...",
 "content":[{"type":"text","text":"Berlin: 16°C, fog"}]}

`subscribe`

Declares which lifecycle events the extension wants to observe and which it wants to intercept. Send once after hello, before ready.

{"type":"subscribe",
 "events":["session_start","turn_start","tool_call","turn_end","assistant_message"],
 "intercept":["tool_call","turn_start","assistant_message"]}

Recognised event names: session_start, turn_start, turn_end, tool_call, assistant_message.

Interceptable events:

tool_call: block the call (model sees reason as the tool error) or rewrite args via modified_args.
turn_start: block the turn before the model is called. Useful for rate-limiting and business-hour gates. reason is shown to the user as a status line. No rewrite supported.
assistant_message: suppress the message via block, or rewrite the user-visible text via replace_text. The model's original text stays in the transcript so the model sees what it actually said on subsequent turns.

`event_intercept_response`

Reply to an event_intercept from the host. All fields default to "allow, pass through unmodified".

field	meaning
`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.
`reason`	refusal text (on block) or pass-through note.
`modified_args`	for `tool_call`: rewritten JSON args the tool will actually see. Must be a valid JSON object. Ignored when `block` is true.
`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.

Missing the response within 5s is treated as "allow" (i.e. an unresponsive extension never stalls the agent). When multiple extensions subscribe to the same event, they're consulted serially; the first block wins and rewrites (args / text) chain: each subsequent interceptor sees the previous one's output.

{"type":"event_intercept_response","id":"...",
 "block":true,"reason":"refused: matches danger pattern \"rm -rf\""}

{"type":"event_intercept_response","id":"...",
 "modified_args":{"command":"echo GUARDED: ls"}}

{"type":"event_intercept_response","id":"...",
 "replace_text":"[redacted]"}

`command_response` (reply to `command_invoked`)

{"type":"command_response","id":"...","action":"prompt",
 "prompt":"Show today's weather for Berlin in one line."}

action is one of:

"prompt" — submits prompt as a fresh user message; the agent runs a turn against it.
"insert" — inserts insert into the editor at the cursor without submitting.
"display" — appends display to the chat as a one-shot styled note. No model call, nothing written to the transcript.
"noop" — the extension handled it itself (e.g. it pushed notify frames or kicked off background work). zot doesn't change the UI in response.

If error is non-empty, zot renders it as a red status line regardless of action.

`notify` (one-way, any time)

{"type":"notify","level":"info",
 "message":"refreshed cache (12 entries)"}

level is one of info, success, warn, error. The note shows up below the transcript with the extension's name in brackets.

`shutdown_ack`

Sent in response to shutdown. Extension should exit promptly after.

Host → extension

`hello_ack`

{"type":"hello_ack","protocol_version":1,
 "zot_version":"0.0.7","provider":"anthropic",
 "model":"claude-opus-4-7","cwd":"/Users/pat/Developer/zot"}

Sent immediately after hello. The extension can use these fields to decide which commands to register (e.g. only register a Python tool on macOS, only register a model-specific shortcut for opus, etc.).

`command_invoked`

{"type":"command_invoked","id":"...",
 "name":"weather","args":"berlin"}

args is everything the user typed after the command name, trimmed.

`tool_call`

Sent when the LLM invokes a tool the extension registered. args is the parsed JSON object the model produced; the extension is responsible for validating/coercing it.

{"type":"tool_call","id":"...","name":"weather",
 "args":{"city":"Berlin"}}

Reply with tool_result within the host's tool timeout (default 60s). Missing the timeout surfaces an error to the model and the call is marked as failed.

`event`

Lifecycle notification for events the extension subscribed to via subscribe. One-way — no response expected.

{"type":"event","event":"turn_start","step":1}
{"type":"event","event":"tool_call",
 "tool_id":"...","tool_name":"read","tool_args":{"path":"foo.go"}}
{"type":"event","event":"turn_end","stop":"end_turn"}

`event_intercept`

Sent when zot wants to give the extension a chance to block, modify, or annotate a lifecycle event before it happens. Reply with event_intercept_response within 5s; missing the deadline is treated as "allow".

Payload fields depend on the event:

// tool_call: includes the tool id, name, and parsed args
{"type":"event_intercept","id":"...","event":"tool_call",
 "tool_id":"...","tool_name":"bash",
 "tool_args":{"command":"rm -rf /tmp/foo"}}

// turn_start: includes the step number
{"type":"event_intercept","id":"...","event":"turn_start",
 "step":3}

// assistant_message: includes the assembled text
{"type":"event_intercept","id":"...","event":"assistant_message",
 "text":"here is your api key: sk-ant-..."}

`shutdown`

Sent during graceful zot exit (or /reload-ext once that lands). Reply with shutdown_ack and then exit.

Managing extensions from the CLI

zot ext list                    list installed extensions and their state
zot ext install <path|git-url>  copy / clone into $ZOT_HOME/extensions/
zot ext remove <name>           delete an extension directory
zot ext enable <name>           re-enable a disabled extension
zot ext disable <name>          disable without removing
zot ext logs <name> [-f]        cat / tail the extension's stderr

zot ext install <path> does a recursive copy; <git-url> does a shallow clone. Both validate that the destination contains an extension.json and roll back if not.

Loading an extension for one run

For iteration on a working copy, skip the install + reload cycle and load straight from disk for one zot session:

zot --ext ./my-extension        # short form: -e ./my-extension
zot --ext ./a -e ./b            # repeatable

--ext paths take precedence over installed extensions of the same name, so you can shadow an installed copy with a work-in-progress version without uninstalling first. Nothing is copied or persisted; the extension dies with zot like any other subprocess.

SDKs

Writing the wire protocol by hand is fine for one-off scripts, but for anything bigger the SDKs handle the boilerplate.

Go — `pkg/zotext`

package main

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

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

    // Slash command
    ext.Command("hello", "say hi", func(args string) zotext.Response {
        return zotext.Prompt("Greet me in one short sentence.")
    })

    // LLM-callable tool
    ext.Tool("weather", "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"` }
            json.Unmarshal(args, &in)
            return zotext.TextResult(in.City + ": sunny")
        })

    ext.Run()
}

Build with go build -o hello ., drop the binary + an extension.json into $ZOT_HOME/extensions/hello/.

The SDK has four interceptor hooks, all optional:

// Refuse calls or rewrite args before they run.
ext.InterceptToolCall(func(tool string, args json.RawMessage) (bool, string) {
    if tool == "bash" { /* inspect args, return false, reason */ }
    return true, ""
})

// Richer variant: returns ToolCallDecision so you can also rewrite
// args via ModifiedArgs.
ext.InterceptToolCallX(func(tool string, args json.RawMessage) zotext.ToolCallDecision {
    return zotext.ToolCallDecision{
        ModifiedArgs: json.RawMessage(`{"command":"echo GUARDED"}`),
    }
})

// Block the next turn before the model is called.
ext.InterceptTurnStart(func(step int) zotext.TurnStartDecision {
    if time.Now().Hour() < 9 { return zotext.TurnStartDecision{Block: true, Reason: "outside business hours"} }
    return zotext.TurnStartDecision{}
})

// Scrub or rewrite the assistant's final text before the user sees it.
ext.InterceptAssistantMessage(func(text string) zotext.AssistantMessageDecision {
    return zotext.AssistantMessageDecision{
        ReplaceText: strings.ReplaceAll(text, "SECRET", "[redacted]"),
    }
})

See:

examples/extensions/hello/ — slash commands
examples/extensions/clock/ — slash commands in plain Node, no SDK
examples/extensions/weather/ — LLM-callable tool
examples/extensions/guard/ — event subscriptions + tool-call interception (refuses dangerous bash patterns)

Hot reload

Type /reload-ext in the TUI to tear down every running extension subprocess, re-read the manifests from disk, and respawn the set. The agent's tool registry is rebuilt automatically, so freshly- registered extension tools become callable without restarting zot. Useful while developing an extension: edit, save, /reload-ext, done. Explicit --ext paths are remembered and reloaded alongside discovered extensions.

TypeScript / Python

These SDKs aren't in the main repo yet; the wire format is small enough that a ~30 line raw script gets you started in either language. See the Quick start Python example for the shape. SDK packages will land in follow-up commits.

Security

Extensions run with the user's full filesystem and network permissions. Treat installing an extension the same as installing any other binary on your machine.

zot ext install <git-url> clones from any URL you give it. There's no sandbox in v1; if you need isolation, install only extensions you trust or run zot under your platform's sandboxing tool (bwrap / sandbox-exec / AppContainer).

Roadmap

Phase 1 (shipped):

subprocess lifecycle + hello handshake
register_command + command_invoked
notify
zot ext CLI

Phase 2 (shipped):

register_tool + tool_call + tool_result
ready sentinel for safe agent-registry build timing
tool result attribution surfaces extension name in details

Phase 3 (shipped):

event subscriptions (session_start, turn_start, turn_end, tool_call, assistant_message)
tool-call interception (block before execution)

Phase 4 (shipped):

interception for turn_start and assistant_message (in addition to tool_call)
modify tool args mid-flight via modified_args
rewrite user-visible assistant text via replace_text
/reload-ext slash command (hot-reload without restarting zot)

Future (no firm timeline):

TypeScript and Python SDK packages (currently the wire format is stable enough to hand-roll, see the Python quick-start)
HTTP / WebSocket transport variants (today: subprocess stdio)
per-extension permission scopes (today: full user privileges)

source

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
9Three 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
16## Quick start
17
18The simplest extension is a script that prints a hello frame, reads
19commands, and prints responses. Here's the whole thing in **Python**,
20no SDK required:
21
22```python
23#!/usr/bin/env python3
24# $ZOT_HOME/extensions/hello-py/hello.py
25import json, sys, threading
26
27def emit(obj):
28    sys.stdout.write(json.dumps(obj) + "\n")
29    sys.stdout.flush()
30
31emit({"type":"hello","name":"hello-py","version":"1.0.0","capabilities":["commands"]})
32emit({"type":"register_command","name":"hellopy","description":"say hi (python)"})
33
34for line in sys.stdin:
35    msg = json.loads(line)
36    if msg["type"] == "command_invoked":
37        emit({"type":"command_response","id":msg["id"],"action":"prompt",
38              "prompt": "Greet me very briefly. Add one emoji."})
39    elif msg["type"] == "shutdown":
40        emit({"type":"shutdown_ack"})
41        break
42```
43
44Drop it in a directory with this `extension.json`:
45
46```json
47{
48  "name": "hello-py",
49  "version": "1.0.0",
50  "exec": "./hello.py",
51  "language": "python",
52  "enabled": true
53}
54```
55
56`chmod +x hello.py`, install:
57
58```bash
59zot ext install ./hello-py
60```
61
62Restart `zot`, type `/hellopy`, the agent greets you. Done.
63
64## Built-in extensions
65
66**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.
67
68The `examples/extensions/` directory in the repo is reference code, not a default install set. To use any of those:
69
70```bash
71# go-based examples need a build first
72cd path/to/zot/examples/extensions/hello && go build -o hello .
73
74# install (copies to $ZOT_HOME/extensions/hello/)
75zot ext install path/to/zot/examples/extensions/hello
76
77# or load straight from the repo for one zot session
78zot --ext path/to/zot/examples/extensions/hello
79```
80
81Nothing is auto-installed and nothing reaches out to the network without your explicit action.
82
83## Layout & discovery
84
85zot scans two directories on startup, in this order:
86
871. **Project-local**: `./.zot/extensions/<name>/extension.json`
882. **Global**: `$ZOT_HOME/extensions/<name>/extension.json`
89
90A project-local extension with the same name wins over a global one.
91On macOS `$ZOT_HOME` defaults to `~/Library/Application Support/zot/`;
92on Linux it's `$XDG_STATE_HOME/zot` or `~/.local/state/zot`.
93
94Each extension owns its own subdirectory. The `extension.json`
95manifest tells zot how to launch it:
96
97```json
98{
99  "name": "weather",
100  "version": "1.0.0",
101  "exec": "./weather",
102  "args": ["--mode", "daemon"],
103  "language": "go",
104  "description": "current weather for any city",
105  "enabled": true
106}
107```
108
109| field | meaning |
110|---|---|
111| `name` | required. how zot identifies the extension; must match what's sent in the `hello` frame. |
112| `version` | optional. shown in `zot ext list`. |
113| `exec` | required. path to the executable (relative to the manifest). |
114| `args` | optional. extra argv passed to `exec`. |
115| `language` | optional. informational only (`go`, `python`, `typescript`, ...). |
116| `description` | optional. shown in `zot ext list`. |
117| `enabled` | optional, defaults to `true`. set to `false` to disable without removing. |
118
119## Lifecycle
120
1211. **Discovery**: zot reads every `extension.json` in the search dirs.
1222. **Spawn**: enabled extensions are launched as subprocesses. stderr
123   redirects to `$ZOT_HOME/logs/ext-<name>.log` (one file per
124   extension, append-mode).
1253. **Hello handshake**: the extension sends a `hello` frame; zot
126   replies with `hello_ack` containing the protocol version and the
127   active provider/model/cwd.
1284. **Registration**: the extension sends `register_command` frames.
129   First-come-first-served: a name already taken by a built-in or by
130   a previously-loaded extension is silently shadowed (logged in the
131   extension's own log file).
1325. **Runtime**: zot dispatches `command_invoked` frames when the
133   user runs a registered command; the extension responds with
134   `command_response`. Extensions can also push `notify` frames at
135   any time.
1366. **Shutdown**: when zot exits, it sends `shutdown` and waits up to
137   2s for the extension to send `shutdown_ack`. Holdouts are
138   SIGTERM'd, then SIGKILL'd.
139
140A crashing extension does not bring down zot. The slash command it
141owned simply stops working until the extension is fixed and zot is
142restarted.
143
144## Wire format
145
146All frames are one JSON object per line. Top-level `type` is the
147discriminator. Optional `id` correlates request frames with their
148responses.
149
150### Extension → host
151
152#### `hello` (required, first frame)
153
154```json
155{"type":"hello","name":"weather","version":"1.0.0",
156 "capabilities":["commands","tools"]}
157```
158
159#### `register_command`
160
161```json
162{"type":"register_command","name":"weather",
163 "description":"current weather for a city"}
164```
165
166#### `register_tool`
167
168Registers a tool the LLM can call. `schema` is a JSON Schema object
169describing the tool's args (the same shape Anthropic and OpenAI accept).
170
171```json
172{"type":"register_tool","name":"weather",
173 "description":"Get the current weather for a city.",
174 "schema":{
175   "type":"object",
176   "properties":{"city":{"type":"string"}},
177   "required":["city"]
178 }}
179```
180
181Tool names live in the same namespace as built-in tools (`read`,
182`write`, `edit`, `bash`, `skill`). Conflicts are silently shadowed by
183the built-in.
184
185#### `ready`
186
187Sentinel telling zot "all initial registrations are flushed". Send it
188right after your last `register_*` frame so the host can build the
189agent's tool registry without racing the registration window.
190
191```json
192{"type":"ready"}
193```
194
195#### `tool_result`
196
197Reply to a `tool_call` from the host. `content[]` is a list of
198message blocks; each block is `{"type":"text","text":"..."}` or
199`{"type":"image","mime_type":"image/png","data":"<base64>"}`. Set
200`is_error: true` to mark the call as failed.
201
202```json
203{"type":"tool_result","id":"...",
204 "content":[{"type":"text","text":"Berlin: 16°C, fog"}]}
205```
206
207#### `subscribe`
208
209Declares which lifecycle events the extension wants to observe and
210which it wants to intercept. Send once after `hello`, before `ready`.
211
212```json
213{"type":"subscribe",
214 "events":["session_start","turn_start","tool_call","turn_end","assistant_message"],
215 "intercept":["tool_call","turn_start","assistant_message"]}
216```
217
218Recognised event names: `session_start`, `turn_start`, `turn_end`,
219`tool_call`, `assistant_message`.
220
221Interceptable events:
222
223- `tool_call`: block the call (model sees `reason` as the tool
224  error) or rewrite args via `modified_args`.
225- `turn_start`: block the turn before the model is called. Useful
226  for rate-limiting and business-hour gates. `reason` is shown to
227  the user as a status line. No rewrite supported.
228- `assistant_message`: suppress the message via `block`, or rewrite
229  the user-visible text via `replace_text`. The model's original
230  text stays in the transcript so the model sees what it actually
231  said on subsequent turns.
232
233#### `event_intercept_response`
234
235Reply to an `event_intercept` from the host. All fields default to
236"allow, pass through unmodified".
237
238| field | meaning |
239|---|---|
240| `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. |
241| `reason` | refusal text (on block) or pass-through note. |
242| `modified_args` | for `tool_call`: rewritten JSON args the tool will actually see. Must be a valid JSON object. Ignored when `block` is true. |
243| `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. |
244
245Missing the response within 5s is treated as "allow" (i.e. an
246unresponsive extension never stalls the agent). When multiple
247extensions subscribe to the same event, they're consulted serially;
248the first `block` wins and rewrites (args / text) chain: each
249subsequent interceptor sees the previous one's output.
250
251```json
252{"type":"event_intercept_response","id":"...",
253 "block":true,"reason":"refused: matches danger pattern \"rm -rf\""}
254
255{"type":"event_intercept_response","id":"...",
256 "modified_args":{"command":"echo GUARDED: ls"}}
257
258{"type":"event_intercept_response","id":"...",
259 "replace_text":"[redacted]"}
260```
261
262#### `command_response` (reply to `command_invoked`)
263
264```json
265{"type":"command_response","id":"...","action":"prompt",
266 "prompt":"Show today's weather for Berlin in one line."}
267```
268
269`action` is one of:
270
271- `"prompt"` — submits `prompt` as a fresh user message; the agent
272  runs a turn against it.
273- `"insert"` — inserts `insert` into the editor at the cursor without
274  submitting.
275- `"display"` — appends `display` to the chat as a one-shot styled
276  note. No model call, nothing written to the transcript.
277- `"noop"` — the extension handled it itself (e.g. it pushed
278  `notify` frames or kicked off background work). zot doesn't change
279  the UI in response.
280
281If `error` is non-empty, zot renders it as a red status line
282regardless of `action`.
283
284#### `notify` (one-way, any time)
285
286```json
287{"type":"notify","level":"info",
288 "message":"refreshed cache (12 entries)"}
289```
290
291`level` is one of `info`, `success`, `warn`, `error`. The note shows
292up below the transcript with the extension's name in brackets.
293
294#### `shutdown_ack`
295
296Sent in response to `shutdown`. Extension should exit promptly after.
297
298### Host → extension
299
300#### `hello_ack`
301
302```json
303{"type":"hello_ack","protocol_version":1,
304 "zot_version":"0.0.7","provider":"anthropic",
305 "model":"claude-opus-4-7","cwd":"/Users/pat/Developer/zot"}
306```
307
308Sent immediately after `hello`. The extension can use these fields to
309decide which commands to register (e.g. only register a Python tool
310on macOS, only register a model-specific shortcut for opus, etc.).
311
312#### `command_invoked`
313
314```json
315{"type":"command_invoked","id":"...",
316 "name":"weather","args":"berlin"}
317```
318
319`args` is everything the user typed after the command name, trimmed.
320
321#### `tool_call`
322
323Sent when the LLM invokes a tool the extension registered. `args` is
324the parsed JSON object the model produced; the extension is
325responsible for validating/coercing it.
326
327```json
328{"type":"tool_call","id":"...","name":"weather",
329 "args":{"city":"Berlin"}}
330```
331
332Reply with `tool_result` within the host's tool timeout (default 60s).
333Missing the timeout surfaces an error to the model and the call is
334marked as failed.
335
336#### `event`
337
338Lifecycle notification for events the extension subscribed to via
339`subscribe`. One-way — no response expected.
340
341```json
342{"type":"event","event":"turn_start","step":1}
343{"type":"event","event":"tool_call",
344 "tool_id":"...","tool_name":"read","tool_args":{"path":"foo.go"}}
345{"type":"event","event":"turn_end","stop":"end_turn"}
346```
347
348#### `event_intercept`
349
350Sent when zot wants to give the extension a chance to block, modify,
351or annotate a lifecycle event before it happens. Reply with
352`event_intercept_response` within 5s; missing the deadline is
353treated as "allow".
354
355Payload fields depend on the event:
356
357```json
358// tool_call: includes the tool id, name, and parsed args
359{"type":"event_intercept","id":"...","event":"tool_call",
360 "tool_id":"...","tool_name":"bash",
361 "tool_args":{"command":"rm -rf /tmp/foo"}}
362
363// turn_start: includes the step number
364{"type":"event_intercept","id":"...","event":"turn_start",
365 "step":3}
366
367// assistant_message: includes the assembled text
368{"type":"event_intercept","id":"...","event":"assistant_message",
369 "text":"here is your api key: sk-ant-..."}
370```
371
372#### `shutdown`
373
374Sent during graceful zot exit (or `/reload-ext` once that lands).
375Reply with `shutdown_ack` and then exit.
376
377## Managing extensions from the CLI
378
379```
380zot ext list                    list installed extensions and their state
381zot ext install <path|git-url>  copy / clone into $ZOT_HOME/extensions/
382zot ext remove <name>           delete an extension directory
383zot ext enable <name>           re-enable a disabled extension
384zot ext disable <name>          disable without removing
385zot ext logs <name> [-f]        cat / tail the extension's stderr
386```
387
388`zot ext install <path>` does a recursive copy; `<git-url>` does a
389shallow clone. Both validate that the destination contains an
390`extension.json` and roll back if not.
391
392## Loading an extension for one run
393
394For iteration on a working copy, skip the install + reload cycle
395and load straight from disk for one zot session:
396
397```
398zot --ext ./my-extension        # short form: -e ./my-extension
399zot --ext ./a -e ./b            # repeatable
400```
401
402`--ext` paths take precedence over installed extensions of the same
403name, so you can shadow an installed copy with a work-in-progress
404version without uninstalling first. Nothing is copied or persisted;
405the extension dies with zot like any other subprocess.
406
407## SDKs
408
409Writing the wire protocol by hand is fine for one-off scripts, but
410for anything bigger the SDKs handle the boilerplate.
411
412### Go — `pkg/zotext`
413
414```go
415package main
416
417import (
418    "encoding/json"
419    "github.com/patriceckhart/zot/pkg/zotext"
420)
421
422func main() {
423    ext := zotext.New("hello", "1.0.0")
424
425    // Slash command
426    ext.Command("hello", "say hi", func(args string) zotext.Response {
427        return zotext.Prompt("Greet me in one short sentence.")
428    })
429
430    // LLM-callable tool
431    ext.Tool("weather", "Current weather for a city.",
432        json.RawMessage(`{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}`),
433        func(args json.RawMessage) zotext.ToolResult {
434            var in struct{ City string `json:"city"` }
435            json.Unmarshal(args, &in)
436            return zotext.TextResult(in.City + ": sunny")
437        })
438
439    ext.Run()
440}
441```
442
443Build with `go build -o hello .`, drop the binary + an `extension.json`
444into `$ZOT_HOME/extensions/hello/`.
445
446The SDK has four interceptor hooks, all optional:
447
448```go
449// Refuse calls or rewrite args before they run.
450ext.InterceptToolCall(func(tool string, args json.RawMessage) (bool, string) {
451    if tool == "bash" { /* inspect args, return false, reason */ }
452    return true, ""
453})
454
455// Richer variant: returns ToolCallDecision so you can also rewrite
456// args via ModifiedArgs.
457ext.InterceptToolCallX(func(tool string, args json.RawMessage) zotext.ToolCallDecision {
458    return zotext.ToolCallDecision{
459        ModifiedArgs: json.RawMessage(`{"command":"echo GUARDED"}`),
460    }
461})
462
463// Block the next turn before the model is called.
464ext.InterceptTurnStart(func(step int) zotext.TurnStartDecision {
465    if time.Now().Hour() < 9 { return zotext.TurnStartDecision{Block: true, Reason: "outside business hours"} }
466    return zotext.TurnStartDecision{}
467})
468
469// Scrub or rewrite the assistant's final text before the user sees it.
470ext.InterceptAssistantMessage(func(text string) zotext.AssistantMessageDecision {
471    return zotext.AssistantMessageDecision{
472        ReplaceText: strings.ReplaceAll(text, "SECRET", "[redacted]"),
473    }
474})
475```
476
477See:
478- `examples/extensions/hello/` — slash commands
479- `examples/extensions/clock/` — slash commands in plain Node, no SDK
480- `examples/extensions/weather/` — LLM-callable tool
481- `examples/extensions/guard/` — event subscriptions + tool-call
482  interception (refuses dangerous bash patterns)
483
484### Hot reload
485
486Type `/reload-ext` in the TUI to tear down every running extension
487subprocess, re-read the manifests from disk, and respawn the set.
488The agent's tool registry is rebuilt automatically, so freshly-
489registered extension tools become callable without restarting zot.
490Useful while developing an extension: edit, save, `/reload-ext`,
491done. Explicit `--ext` paths are remembered and reloaded alongside
492discovered extensions.
493
494### TypeScript / Python
495
496These SDKs aren't in the main repo yet; the wire format is small
497enough that a `~30 line` raw script gets you started in either
498language. See the [Quick start](#quick-start) Python example for the
499shape. SDK packages will land in follow-up commits.
500
501## Security
502
503Extensions run with **the user's full filesystem and network
504permissions**. Treat installing an extension the same as installing
505any other binary on your machine.
506
507`zot ext install <git-url>` clones from any URL you give it. There's
508no sandbox in v1; if you need isolation, install only extensions you
509trust or run zot under your platform's sandboxing tool (`bwrap` /
510`sandbox-exec` / AppContainer).
511
512## Roadmap
513
514Phase 1 (shipped):
515- [x] subprocess lifecycle + hello handshake
516- [x] `register_command` + `command_invoked`
517- [x] `notify`
518- [x] `zot ext` CLI
519
520Phase 2 (shipped):
521- [x] `register_tool` + `tool_call` + `tool_result`
522- [x] `ready` sentinel for safe agent-registry build timing
523- [x] tool result attribution surfaces extension name in details
524
525Phase 3 (shipped):
526- [x] event subscriptions (`session_start`, `turn_start`, `turn_end`,
527      `tool_call`, `assistant_message`)
528- [x] tool-call interception (block before execution)
529
530Phase 4 (shipped):
531- [x] interception for `turn_start` and `assistant_message` (in
532      addition to `tool_call`)
533- [x] modify tool args mid-flight via `modified_args`
534- [x] rewrite user-visible assistant text via `replace_text`
535- [x] `/reload-ext` slash command (hot-reload without restarting zot)
536
537Future (no firm timeline):
538- [ ] TypeScript and Python SDK packages (currently the wire format
539      is stable enough to hand-roll, see the Python quick-start)
540- [ ] HTTP / WebSocket transport variants (today: subprocess stdio)
541- [ ] per-extension permission scopes (today: full user privileges)

extensions.md RawHistoryFolder

zot extensions

Quick start

Built-in extensions

Layout & discovery

Lifecycle

Wire format

Extension → host

hello (required, first frame)

register_command

register_tool

ready

tool_result

subscribe

event_intercept_response

command_response (reply to command_invoked)

notify (one-way, any time)

shutdown_ack