Embedding

Two ways to drive zot from another program. Both share the same event schema, so transcripts captured by one can be replayed through the other.

Go, in-process

Import github.com/patriceckhart/zot/packages/agent/sdk. One Runtime per project; Prompt(ctx, text, images) returns a channel of Event. Example in examples/sdk/.

Any language, out-of-process

Spawn zot rpc as a subprocess and exchange NDJSON over its stdin/stdout. Reference clients for Python, Node, shell, and Go live under examples/rpc/.

Extension prompt hooks in RPC

RPC mode supports the before_agent_start extension hook. Subscribed extensions receive the complete assembled system prompt before the first model call and can replace it exactly. This uses the extension subprocess protocol, not a new RPC client command. Ordinary follow-up prompts reuse the result; an accepted clear or model change invalidates it for the next prompt. Failures keep the current prompt and surface as ext_notify warnings. See Extensions for lifecycle, privacy, and response limits.

RPC state changes while busy

clear, set_model, and set_reasoning require an idle agent. During prompt preparation, including extension hooks, model/tool execution, or compaction, they return success:false with an agent is busy error and leave state unchanged. These commands are not queued.

Wait for the active operation to finish, or send abort, wait for completion, and retry. The RPC read loop remains responsive to abort while an extension hook or provider is busy.

Packaged SDKs

For the two most common app targets, drop-in packages wrap the RPC handshake so you do not manage the child process by hand:

• Node.js SDK - a TypeScript client (@patriceckhart/zot-sdk-javascript) that runs zot rpc for you in any Node-compatible server runtime.
• Swift bridge - zot's Go agent core compiled into an Apple xcframework for native, on-device chat in iOS and macOS apps.