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.

Set "deferred": true to register a tool without advertising its definition initially. A loader tool can activate registered deferred tools by returning their names in activate_tools:

{"type":"tool_result","id":"...",
 "content":[{"type":"text","text":"Enabled weather lookup"}],
 "activate_tools":["weather"]}

On Kimi K3's OpenAI-compatible routes, zot places newly activated schemas at the tool-result position using Kimi's native deferred-tool format. Other models receive the complete active tool list on the next request. Unknown names are ignored. The Go extension SDK exposes DeferredTool and ToolResult.ActivateTools for the same protocol.

`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. activate_tools can name registered deferred tools that become available after this result.

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