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. When XDG_STATE_HOME is set on any platform, $ZOT_HOME defaults to $XDG_STATE_HOME/zot. Otherwise it defaults to ~/Library/Application Support/zot/ on macOS, ~/.local/state/zot on Linux, or %LOCALAPPDATA%\zot on Windows.

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.

`submit` (one-way, any time)

Submits text as a user prompt in the interactive host. If the agent is idle, zot starts a turn immediately. If a turn is already running, zot queues the prompt behind it using the same queue path as typed input. Empty or whitespace-only text is ignored.

{"type":"submit","text":"Summarize the selected workspace."}

In print / JSON / RPC modes this frame is ignored because there is no interactive editor or prompt queue.

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

submit (one-way, any time)

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`)

`submit` (one-way, any time)

`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`