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.

Four 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.
Phase 4: interactive extension-owned panels rendered inside zot.
Theme-only extensions: ship theme.json without launching a subprocess. See themes.md.

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
}

exec is required for protocol extensions. If an extension only ships theme.json or themes/theme.json, no exec is required and zot does not spawn a subprocess.

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.

Because each extension owns its own directory, the recommended place for extension state is inside that directory itself (for example todos.json, settings.json, or an auth/cache file used only by that extension). The host also passes this path back in hello_ack as extension_dir / data_dir so runtime code does not need to guess it.

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, the active provider/model/cwd, and the extension's own data directory so it can persist files beside its manifest.
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. Panel-capable extensions may open an interactive panel, receive key events, and push redraws while the panel is focused.
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","panels"]}

`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.
"open_panel" — opens an extension-owned interactive panel inside zot. The panel content lives in open_panel.
"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.

Example:

{"type":"command_response","id":"...","action":"open_panel",
 "open_panel":{
   "id":"todos-main",
   "title":"Todos",
   "lines":["□ ship panel api","✓ persist state"],
   "footer":"↑/↓ navigate - a add - x complete - esc close"
 }}

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

`panel_render` (one-way, while a panel is open)

Pushes a fresh frame for an already-open panel.

{"type":"panel_render","panel_id":"todos-main",
 "title":"Todos",
 "lines":["□ ship panel api","✓ persist state"],
 "footer":"↑/↓ navigate - a add - x complete - esc close"}

`panel_close`

Closes a previously-open panel.

{"type":"panel_close","panel_id":"todos-main"}

`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. Notes are one-shot: they clear automatically when the user sends their next prompt (and on esc / /clear).

`clear_notes` (one-way, any time)

Removes every note this extension previously pushed via notify / display. Use it for transient status lines (e.g. an approval prompt) so they do not stack up; notes from other extensions are untouched.

{"type":"clear_notes"}

In --mode rpc, this surfaces to the host as an ext_clear_notes event (alongside ext_notify / ext_display).

`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",
 "extension_dir":"/Users/pat/Developer/zot/.zot/extensions/todos",
 "data_dir":"/Users/pat/Developer/zot/.zot/extensions/todos"}

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.). extension_dir / data_dir are where the extension should persist its own state (for example todos.json, cached metadata, or auth tokens scoped to that extension).

`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-..."}

`panel_key`

Sent while an extension-owned panel is focused. key is a normalized name (up, down, left, right, enter, esc, tab, pageup, pagedown, home, end, backspace, delete, rune). For key:"rune", text carries the typed character.

{"type":"panel_key","panel_id":"todos-main","key":"down"}
{"type":"panel_key","panel_id":"todos-main","key":"rune","text":"x"}

`panel_close`

Sent when the user closes the focused panel from zot (for example with Esc or Ctrl+C). The extension should treat this as the panel lifetime ending and stop sending panel_render updates for that panel_id.

{"type":"panel_close","panel_id":"todos-main"}

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

package main

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

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

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

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

    e.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:

// e is the *ext.Extension returned by ext.New(...).

// Refuse calls or rewrite args before they run.
e.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.
e.InterceptToolCallX(func(tool string, args json.RawMessage) ext.ToolCallDecision {
    return ext.ToolCallDecision{
        ModifiedArgs: json.RawMessage(`{"command":"echo GUARDED"}`),
    }
})

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

// Scrub or rewrite the assistant's final text before the user sees it.
e.InterceptAssistantMessage(func(text string) ext.AssistantMessageDecision {
    return ext.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)
examples/extensions/todo/ — interactive persistent panel + tool
examples/extensions/scratchpad/ — source-run TypeScript commands + tool

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

panel_render (one-way, while a panel is open)

panel_close

notify (one-way, any time)

clear_notes (one-way, any time)

shutdown_ack

Host → extension

hello_ack

command_invoked

tool_call

event

event_intercept

panel_key

panel_close

shutdown

Managing extensions from the CLI

Loading an extension for one run

SDKs

Go — packages/agent/ext

Hot reload

TypeScript / Python

Security

Roadmap

extensions.md Raw History Folder

`hello` (required, first frame)

`register_command`

`register_tool`

`ready`

`tool_result`

`subscribe`

`event_intercept_response`

`command_response` (reply to `command_invoked`)

`panel_render` (one-way, while a panel is open)

`panel_close`

`notify` (one-way, any time)

`clear_notes` (one-way, any time)

`shutdown_ack`

`hello_ack`

`command_invoked`

`tool_call`

`event`

`event_intercept`

`panel_key`

`panel_close`

`shutdown`

Go — `packages/agent/ext`