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

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"]})

for line in sys.stdin:
    msg = json.loads(line)
    if msg["type"] == "hello_ack":
        emit({"type":"register_command","name":"hellopy","description":"say hi (python)"})
        emit({"type":"ready"})
    elif msg["type"] == "command_invoked":
        emit({"type":"command_response","id":msg["id"],"action":"prompt",
              "prompt": "Greet me very briefly in one sentence."})
    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's first stdout frame must be hello; 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: after receiving hello_ack, the extension sends register_command, register_tool, and subscription frames, then sends ready. 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: after ready, zot dispatches command_invoked frames when the user runs a registered command; the extension responds with command_response. Extensions can also push notify frames during runtime. 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. The canonical startup order is hello, hello_ack, registration frames, then ready. Do not send notify, logs, or any other stdout frame before hello.

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. Wait for this frame before sending registrations if they depend on host metadata. 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.). cwd is the user's project directory; the extension process itself runs from the extension directory, so do not use os.Getwd() or process.cwd() when you need the project path. 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 doctor                  diagnose load, registration, and conflict issues
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 doctor runs the same discovery path as zot startup, but reports what happened instead of changing the fail-soft runtime behavior. It shows manifest errors, disabled or shadowed extensions, subprocess load errors, ready/auto-ready status, registered commands/tools, registration conflicts, warnings, and each extension's stderr log path.

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")
        })

    // Optional: register project-specific commands after hello_ack.
    e.OnHello(func(host ext.HostInfo) {
        if host.CWD != "" {
            e.Command("cwd", "show the current project directory", func(args string) ext.Response {
                return ext.Display(host.CWD)
            })
        }
    })

    e.Run()
}

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

OnHello is optional. Use it when configuration or registrations need host metadata such as HostInfo.CWD, Provider, Model, ZotVersion, ExtensionDir, or DataDir. The SDK sends hello, waits for hello_ack, runs OnHello, announces registrations, then sends ready.

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
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#### `panel_render` (one-way, while a panel is open)
320
321Pushes a fresh frame for an already-open panel.
322
323```json
324{"type":"panel_render","panel_id":"todos-main",
325 "title":"Todos",
326 "lines":["□ ship panel api","✓ persist state"],
327 "footer":"↑/↓ navigate - a add - x complete - esc close"}
328```
329
330#### `panel_close`
331
332Closes a previously-open panel.
333
334```json
335{"type":"panel_close","panel_id":"todos-main"}
336```
337
338#### `notify` (one-way, any time)
339
340```json
341{"type":"notify","level":"info",
342 "message":"refreshed cache (12 entries)"}
343```
344
345`level` is one of `info`, `success`, `warn`, `error`. The note shows
346up below the transcript with the extension's name in brackets. Notes
347are one-shot: they clear automatically when the user sends their next
348prompt (and on `esc` / `/clear`).
349
350#### `clear_notes` (one-way, any time)
351
352Removes every note this extension previously pushed via `notify` /
353`display`. Use it for transient status lines (e.g. an approval prompt)
354so they do not stack up; notes from other extensions are untouched.
355
356```json
357{"type":"clear_notes"}
358```
359
360In `--mode rpc`, this surfaces to the host as an `ext_clear_notes`
361event (alongside `ext_notify` / `ext_display`).
362
363#### `shutdown_ack`
364
365Sent in response to `shutdown`. Extension should exit promptly after.
366
367### Host → extension
368
369#### `hello_ack`
370
371```json
372{"type":"hello_ack","protocol_version":1,
373 "zot_version":"0.0.7","provider":"anthropic",
374 "model":"claude-opus-4-7","cwd":"/Users/pat/Developer/zot",
375 "extension_dir":"/Users/pat/Developer/zot/.zot/extensions/todos",
376 "data_dir":"/Users/pat/Developer/zot/.zot/extensions/todos"}
377```
378
379Sent immediately after `hello`. Wait for this frame before sending
380registrations if they depend on host metadata. The extension can use
381these fields to decide which commands to register (e.g. only register
382a Python tool on macOS, only register a model-specific shortcut for
383opus, etc.). `cwd` is the user's project directory; the extension
384process itself runs from the extension directory, so do not use
385`os.Getwd()` or `process.cwd()` when you need the project path.
386`extension_dir` / `data_dir` are where the extension should persist
387its own state (for example `todos.json`, cached metadata, or auth
388tokens scoped to that extension).
389
390#### `command_invoked`
391
392```json
393{"type":"command_invoked","id":"...",
394 "name":"weather","args":"berlin"}
395```
396
397`args` is everything the user typed after the command name, trimmed.
398
399#### `tool_call`
400
401Sent when the LLM invokes a tool the extension registered. `args` is
402the parsed JSON object the model produced; the extension is
403responsible for validating/coercing it.
404
405```json
406{"type":"tool_call","id":"...","name":"weather",
407 "args":{"city":"Berlin"}}
408```
409
410Reply with `tool_result` within the host's tool timeout (default 60s).
411Missing the timeout surfaces an error to the model and the call is
412marked as failed.
413
414#### `event`
415
416Lifecycle notification for events the extension subscribed to via
417`subscribe`. One-way — no response expected.
418
419```json
420{"type":"event","event":"turn_start","step":1}
421{"type":"event","event":"tool_call",
422 "tool_id":"...","tool_name":"read","tool_args":{"path":"foo.go"}}
423{"type":"event","event":"turn_end","stop":"end_turn"}
424```
425
426#### `event_intercept`
427
428Sent when zot wants to give the extension a chance to block, modify,
429or annotate a lifecycle event before it happens. Reply with
430`event_intercept_response` within 5s; missing the deadline is
431treated as "allow".
432
433Payload fields depend on the event:
434
435```json
436// tool_call: includes the tool id, name, and parsed args
437{"type":"event_intercept","id":"...","event":"tool_call",
438 "tool_id":"...","tool_name":"bash",
439 "tool_args":{"command":"rm -rf /tmp/foo"}}
440
441// turn_start: includes the step number
442{"type":"event_intercept","id":"...","event":"turn_start",
443 "step":3}
444
445// assistant_message: includes the assembled text
446{"type":"event_intercept","id":"...","event":"assistant_message",
447 "text":"here is your api key: sk-ant-..."}
448```
449
450#### `panel_key`
451
452Sent while an extension-owned panel is focused. `key` is a normalized
453name (`up`, `down`, `left`, `right`, `enter`, `esc`, `tab`, `pageup`,
454`pagedown`, `home`, `end`, `backspace`, `delete`, `rune`). For
455`key:"rune"`, `text` carries the typed character.
456
457```json
458{"type":"panel_key","panel_id":"todos-main","key":"down"}
459{"type":"panel_key","panel_id":"todos-main","key":"rune","text":"x"}
460```
461
462#### `panel_close`
463
464Sent when the user closes the focused panel from zot (for example with
465Esc or Ctrl+C). The extension should treat this as the panel lifetime
466ending and stop sending `panel_render` updates for that `panel_id`.
467
468```json
469{"type":"panel_close","panel_id":"todos-main"}
470```
471
472#### `shutdown`
473
474Sent during graceful zot exit (or `/reload-ext` once that lands).
475Reply with `shutdown_ack` and then exit.
476
477## Managing extensions from the CLI
478
479```
480zot ext list                    list installed extensions and their state
481zot ext doctor                  diagnose load, registration, and conflict issues
482zot ext install <path|git-url>  copy / clone into $ZOT_HOME/extensions/
483zot ext remove <name>           delete an extension directory
484zot ext enable <name>           re-enable a disabled extension
485zot ext disable <name>          disable without removing
486zot ext logs <name> [-f]        cat / tail the extension's stderr
487```
488
489`zot ext doctor` runs the same discovery path as zot startup, but reports
490what happened instead of changing the fail-soft runtime behavior. It shows
491manifest errors, disabled or shadowed extensions, subprocess load errors,
492ready/auto-ready status, registered commands/tools, registration conflicts,
493warnings, and each extension's stderr log path.
494
495`zot ext install <path>` does a recursive copy; `<git-url>` does a
496shallow clone. Both validate that the destination contains an
497`extension.json` and roll back if not.
498
499## Loading an extension for one run
500
501For iteration on a working copy, skip the install + reload cycle
502and load straight from disk for one zot session:
503
504```
505zot --ext ./my-extension        # short form: -e ./my-extension
506zot --ext ./a -e ./b            # repeatable
507```
508
509`--ext` paths take precedence over installed extensions of the same
510name, so you can shadow an installed copy with a work-in-progress
511version without uninstalling first. Nothing is copied or persisted;
512the extension dies with zot like any other subprocess.
513
514## SDKs
515
516Writing the wire protocol by hand is fine for one-off scripts, but
517for anything bigger the SDKs handle the boilerplate.
518
519### Go — `packages/agent/ext`
520
521```go
522package main
523
524import (
525    "encoding/json"
526    "github.com/patriceckhart/zot/packages/agent/ext"
527)
528
529func main() {
530    e := ext.New("hello", "1.0.0")
531
532    // Slash command
533    e.Command("hello", "say hi", func(args string) ext.Response {
534        return ext.Prompt("Greet me in one short sentence.")
535    })
536
537    // LLM-callable tool
538    e.Tool("weather", "Current weather for a city.",
539        json.RawMessage(`{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}`),
540        func(args json.RawMessage) ext.ToolResult {
541            var in struct{ City string `json:"city"` }
542            json.Unmarshal(args, &in)
543            return ext.TextResult(in.City + ": sunny")
544        })
545
546    // Optional: register project-specific commands after hello_ack.
547    e.OnHello(func(host ext.HostInfo) {
548        if host.CWD != "" {
549            e.Command("cwd", "show the current project directory", func(args string) ext.Response {
550                return ext.Display(host.CWD)
551            })
552        }
553    })
554
555    e.Run()
556}
557```
558
559Build with `go build -o hello .`, drop the binary + an `extension.json`
560into `$ZOT_HOME/extensions/hello/`.
561
562`OnHello` is optional. Use it when configuration or registrations need
563host metadata such as `HostInfo.CWD`, `Provider`, `Model`, `ZotVersion`,
564`ExtensionDir`, or `DataDir`. The SDK sends `hello`, waits for
565`hello_ack`, runs `OnHello`, announces registrations, then sends `ready`.
566
567The SDK has four interceptor hooks, all optional:
568
569```go
570// e is the *ext.Extension returned by ext.New(...).
571
572// Refuse calls or rewrite args before they run.
573e.InterceptToolCall(func(tool string, args json.RawMessage) (bool, string) {
574    if tool == "bash" { /* inspect args, return false, reason */ }
575    return true, ""
576})
577
578// Richer variant: returns ToolCallDecision so you can also rewrite
579// args via ModifiedArgs.
580e.InterceptToolCallX(func(tool string, args json.RawMessage) ext.ToolCallDecision {
581    return ext.ToolCallDecision{
582        ModifiedArgs: json.RawMessage(`{"command":"echo GUARDED"}`),
583    }
584})
585
586// Block the next turn before the model is called.
587e.InterceptTurnStart(func(step int) ext.TurnStartDecision {
588    if time.Now().Hour() < 9 { return ext.TurnStartDecision{Block: true, Reason: "outside business hours"} }
589    return ext.TurnStartDecision{}
590})
591
592// Scrub or rewrite the assistant's final text before the user sees it.
593e.InterceptAssistantMessage(func(text string) ext.AssistantMessageDecision {
594    return ext.AssistantMessageDecision{
595        ReplaceText: strings.ReplaceAll(text, "SECRET", "[redacted]"),
596    }
597})
598```
599
600See:
601- `examples/extensions/hello/` — slash commands
602- `examples/extensions/clock/` — slash commands in plain Node, no SDK
603- `examples/extensions/weather/` — LLM-callable tool
604- `examples/extensions/guard/` — event subscriptions + tool-call
605  interception (refuses dangerous bash patterns)
606- `examples/extensions/todo/` — interactive persistent panel + tool
607- `examples/extensions/scratchpad/` — source-run TypeScript commands + tool
608
609### Hot reload
610
611Type `/reload-ext` in the TUI to tear down every running extension
612subprocess, re-read the manifests from disk, and respawn the set.
613The agent's tool registry is rebuilt automatically, so freshly-
614registered extension tools become callable without restarting zot.
615Useful while developing an extension: edit, save, `/reload-ext`,
616done. Explicit `--ext` paths are remembered and reloaded alongside
617discovered extensions.
618
619### TypeScript / Python
620
621These SDKs aren't in the main repo yet; the wire format is small
622enough that a `~30 line` raw script gets you started in either
623language. See the [Quick start](#quick-start) Python example for the
624shape. SDK packages will land in follow-up commits.
625
626## Security
627
628Extensions run with **the user's full filesystem and network
629permissions**. Treat installing an extension the same as installing
630any other binary on your machine.
631
632`zot ext install <git-url>` clones from any URL you give it. There's
633no sandbox in v1; if you need isolation, install only extensions you
634trust or run zot under your platform's sandboxing tool (`bwrap` /
635`sandbox-exec` / AppContainer).
636
637## Roadmap
638
639Phase 1 (shipped):
640- [x] subprocess lifecycle + hello handshake
641- [x] `register_command` + `command_invoked`
642- [x] `notify` + `clear_notes`
643- [x] `zot ext` CLI
644
645Phase 2 (shipped):
646- [x] `register_tool` + `tool_call` + `tool_result`
647- [x] `ready` sentinel for safe agent-registry build timing
648- [x] tool result attribution surfaces extension name in details
649
650Phase 3 (shipped):
651- [x] event subscriptions (`session_start`, `turn_start`, `turn_end`,
652      `tool_call`, `assistant_message`)
653- [x] tool-call interception (block before execution)
654
655Phase 4 (shipped):
656- [x] interception for `turn_start` and `assistant_message` (in
657      addition to `tool_call`)
658- [x] modify tool args mid-flight via `modified_args`
659- [x] rewrite user-visible assistant text via `replace_text`
660- [x] `/reload-ext` slash command (hot-reload without restarting zot)
661
662Future (no firm timeline):
663- [ ] TypeScript and Python SDK packages (currently the wire format
664      is stable enough to hand-roll, see the Python quick-start)
665- [ ] HTTP / WebSocket transport variants (today: subprocess stdio)
666- [ ] 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`