Plugins

config/plugins.toml declares plugins that extend agents with additional tools.

Each plugin is a JavaScript package that runs in-process in a constrained JavaScript engine inside the runtime process.

Plugins are trusted host extensions, not sandboxed agent actions. The runtime protects the operator from the agent; it does not protect the operator from plugin code they install.

Only install plugins you trust, and give them only the configuration and network access they need.

Declaring plugins

Every plugin must be listed in config/plugins.toml; there is no auto-discovery.

[[plugins]]
package = "@cireilclaw/plugin-brave-search"

[[plugins]]
name = "local-plugin"
allowOverride = true
stateQuotaBytes = 16777216

Each entry sets exactly one of:

• package — a package resolved from <root>/node_modules/<package>.
• name — a local directory resolved from <root>/plugins/<name>.

Entry flags

Field	Default	Description
allowOverride	false	Permit this plugin's tools to shadow built-in tools.
stateQuotaBytes	16777216	Per-agent plugin state quota in bytes.

A tool name collision against a built-in fails loudly at startup unless the plugin sets allowOverride. Two plugins with the same tool name always fail regardless.

Treat overrides as security-sensitive: replacing a built-in tool changes part of the boundary the runtime presents to the agent.

Installing packages

Install npm packages into the runtime root so the runtime can resolve them.

npm install --prefix ~/.cireilclaw @cireilclaw/plugin-brave-search

Local plugins are directories under plugins/; the plugin's entry module must be compiled JavaScript.

Local plugins with no external imports do not need a node_modules directory. If a local plugin imports another package, place that dependency in the plugin's node_modules directory or in the runtime root's node_modules directory.

Package resolution checks the exports map first, then main, then dist/index.mjs, dist/index.js, index.mjs, and index.js.

Plugin configuration

Plugins read their own configuration through their SDK context.

By convention these live at:

• <root>/config/plugins/<name>.toml — global.
• <root>/agents/<slug>/config/plugins/<name>.toml — per-agent override.

The <name> value must be a single file name without path separators or ./.. path segments. The runtime rejects names that would escape the plugin configuration directory. The plugin decides which valid <name> it reads and which keys it expects; consult the plugin's documentation.

Per-plugin configuration files are re-read on access; edits take effect on the next tool invocation that reads them.

Enabling plugin tools

Plugin tools are enabled per agent in tools.toml just like built-in tools.

example-search = true

Plugin state

Plugins keep private, persistent state per agent under agents/<slug>/state/<plugin-slug>/. State survives restarts and is not visible to the agent sandbox.

Restart requirements

Changes to plugins.toml or plugin code require a full runtime restart; they are not hot-reloaded.