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.jsonwithout 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. A skill-only bundle may instead provide a skills
array and is also never spawned.
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. |
skills |
optional. directories (recursively scanned) or direct SKILL.md paths, relative to the manifest. |
enabled |
optional, defaults to true. set to false to disable without removing. |
Lifecycle
- Discovery: zot reads every
extension.jsonin 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 withhello_ackcontaining 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 sendsregister_command,register_tool, and subscription frames, then sendsready. 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 dispatchescommand_invokedframes when the user runs a registered command; the extension responds withcommand_response. Extensions can also pushnotifyframes 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
shutdownand waits up to 2s for the extension to sendshutdown_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"}
Command names are matched case-insensitively. zot sends command_invoked.name using the canonical spelling registered here. Registrations that differ only by case conflict, and the first registration remains active.
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","tool_confirmation_requested","turn_end","assistant_message"],
"intercept":["tool_call","turn_start","assistant_message"]}
Recognised event names: session_start, turn_start, turn_end,
tool_call, tool_confirmation_requested, assistant_message.
tool_confirmation_requested fires only when zot is about to wait for
interactive approval. Calls running in yolo mode, calls covered by a
remembered approval, and calls blocked before confirmation do not emit it.
The event includes tool_id, tool_name, and the short tool_preview
shown in the confirmation dialog.
Interceptable events:
tool_call: block the call (model seesreasonas the tool error) or rewrite args viamodified_args.turn_start: block the turn before the model is called. Useful for rate-limiting and business-hour gates.reasonis shown to the user as a status line. No rewrite supported.assistant_message: suppress the message viablock, or rewrite the user-visible text viareplace_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"— submitspromptas a fresh user message; the agent runs a turn against it."insert"— insertsinsertinto the editor at the cursor without submitting."display"— appendsdisplayto 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 inopen_panel."noop"— the extension handled it itself (e.g. it pushednotifyframes 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":"tool_confirmation_requested",
"tool_id":"...","tool_name":"read","tool_preview":"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 commandsexamples/extensions/clock/— slash commands in plain Node, no SDKexamples/extensions/weather/— LLM-callable toolexamples/extensions/guard/— event subscriptions + tool-call interception (refuses dangerous bash patterns)examples/extensions/todo/— interactive persistent panel + toolexamples/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. The temporary reload status reports each load
error in red, including its message, and dismisses itself after five
seconds. Extension failures from startup and /reload-ext remain in the
scrolling chat until a successful reload or /clear, without being sent to
the model or saved in the session transcript. Subprocess startup and
handshake errors include the exact stderr log path for the failed extension.
If a subprocess exits before sending hello, the error also reports its exit
status or terminating signal.
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 extCLI
Phase 2 (shipped):
-
register_tool+tool_call+tool_result -
readysentinel 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_startandassistant_message(in addition totool_call) - modify tool args mid-flight via
modified_args - rewrite user-visible assistant text via
replace_text -
/reload-extslash 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)