Plugin definitions

A symposium plugin collects together all the extensions offered for a particular crate. Plugins are directories containing a Symposium.toml manifest file that references skills, hooks, MCP servers, and other resources relevant to your crate. These extensions can be packaged within the plugin directory or the plugin can contain pointers to external repositories.

Plugins enable capabilities beyond standalone skills — they’re needed when you want to add hooks or MCP servers. For simple skill publishing, see Authoring a plugin instead.

Example: a plugin definition with inline skills

You could define a plugin definition with inline skills by having a directory struct like this:

myplugin/
  Symposium.toml
  skills/
    skill-a/
      SKILL.md
    skill-b/
      SKILL.md

where myplugin/Symposium.toml is as follows:

name = "example"
depends-on = ["*"]

[[skills]]
source.path = "skills"

Top-level fields

A registry plugin gets no default skill group: its skills load only through the [[skills]] groups it declares, so a registry plugin that ships a skills/ directory needs [[skills]] source.path = "skills". Crate and workspace plugins get the default skills/ group unless [defaults] skills = false (workspace plugins also get a .agents/skills group by default, see Workspace skills).

Note: A registry plugin that references no dependency anywhere is dormant: it loads, but it never activates until the user enables it by name in the [plugins] use config (for example with cargo agents use). Use depends-on = ["*"] for a plugin that should always be active. These count as referencing a dependency:

• a depends-on field, or a depends-on(...) predicate in a predicates list, on the plugin itself, a [[skills]] group, an [[mcp_servers]] entry, or a [[plugins]] edge;
• a depends-on(...) predicate in a [[hooks]] entry’s predicates;
• a custom predicate used directly in the plugin-level predicates.

A depends-on(...) predicate counts wherever it sits in the list, including depends-on(*) and one nested inside not, any, or all.

These do not count: the crate named by a [[plugins]] edge’s source.cargo, a [subcommand.<name>]’s depends-on or predicates, and the frontmatter of a SKILL.md inside a [[skills]] group. Crate and workspace plugins never go dormant: what loaded the crate (a chained reference or the user’s enablement), or membership in the active workspace, is their gate.

Plugin-level filtering

The top-level depends-on field controls when the entire plugin is active:

name = "my-plugin"
depends-on = ["serde", "tokio"]  # Only active in projects using serde OR tokio

Use the wildcard depends-on = ["*"] instead for a plugin that always applies.

Plugin-level filtering is combined with skill group filtering using AND logic — both must match for skills to be available.

[[skills]] groups

Each [[skills]] entry declares a group of skills.

A skill group must have exactly one of source.path or source.git. A crate is not a skill-group source; to load a crate’s own skills, name it in a chained plugin.

Chained plugins

A [[plugins]] entry names another plugin that loads whenever this plugin is active (the “a package is a plugin” edge). Today the referenced plugin is a crate, which always loads as a first-class plugin built from its manifest sources (see Crate-embedded manifest below). The referenced crate loads without a consent step of its own: the plugin that names it vouches for it (see Configuration).

name = "serde-plugin"

# When serde is a dependency, load serde's plugin (its skills).
[[plugins]]
depends-on = ["serde"]
source.cargo = "serde"

The edge’s depends-on decides whether to load the referenced crate; the crate name in source.cargo decides which crate. List several [[plugins]] entries to load several crates.

Only source.cargo is supported today; source.git / source.path chained plugins are reserved and rejected with a clear error.

Crate-embedded manifest

A referenced crate describes its plugin with the ordinary plugin-manifest schema, from two interchangeable sources: a Symposium.toml at its source root, and/or a [package.metadata.symposium] table in its Cargo.toml. Both are honored the same as a registry manifest: [[skills]] groups, per-group predicates, source.path / source.git sources, and further [[plugins]] chained references. The crate’s effective manifest is the two sources merged over the crate defaults (merge order defaults -> [package.metadata.symposium] -> Symposium.toml): list entries from both are kept; where the two set the same scalar, the file wins. Each source is parsed leniently: a malformed layer is logged and dropped, and the crate still resolves through the remaining layers (at minimum the default skills/ group). A merged manifest that parses but fails validation (for example a hook naming an unknown installation) disables the crate’s whole plugin, default skills/ group included.

Because the chained reference is already the gate, a crate manifest may omit name (defaults to the crate) and a top-level depends-on; the default skills/ group is appended unless [defaults] skills = false. A crate with no manifest sources at all still resolves as a plugin whose only content is that default skills/ group.

The opt-out belongs to the referenced crate, not the referrer. The edge decides only whether to load the crate (via its depends-on / predicates); it cannot toggle the crate’s defaults. So for an active edge to crate foo:

• foo ships nothing → its skills/ directory loads.
• foo declares [[skills]] source.path = "guidance" → both guidance/ and skills/ load (combined with defaults).
• foo declares [defaults] skills = false plus a custom group → only the custom group loads.
• foo declares [defaults] skills = false and nothing else → nothing loads.
• foo carries its own [[plugins]] source.cargo = "bar" → bar resolves the same way, recursively.

Everything a crate manifest declares loads like a registry plugin’s: skills, hooks, MCP servers, subcommands, custom predicates, and further [[plugins]] references.

Delegating to another crate

A crate can delegate to another crate with a [[plugins]] chained reference of its own:

# In the referenced crate's Cargo.toml (in its Symposium.toml, write the table as [[plugins]])
[[package.metadata.symposium.plugins]]
source.cargo = "companion-crate"

Chained references are followed until no new crate is reached; there is no depth limit. A crate reached through several references loads only once (crates are identified by name, hyphen/underscore-insensitively), which also makes cycles harmless, and a SKILL.md reached two ways installs once, since a skill is identified by the path of its SKILL.md. See Supporting your crate for the full crate-author walkthrough.

Installations

An installation describes how to obtain (and optionally pre-configure) something a hook, subcommand, or custom predicate will run. They reference an installation as their command, either by name (command = "mytool") or inline at the use site (command = { script = "scripts/x.sh" }).

A [[installations]] entry has a name plus any of:

executable and script are mutually exclusive — pick one. The hook layer applies the same rule, and at most one of executable / script may be set across the hook AND the installation it references. An installation may have neither (then it’s pure setup — useful as a requirements entry). For a hook to run, the chosen layer pair must end up with exactly one runnable.

Inline installations (used as command or as a requirement entry) accept the same fields, including requirements.

Installation sources

cargo

[[installations]]
name = "rg"
source = "cargo"
crate = "ripgrep"
version = "13.0.0"     # optional; defaults to latest stable
executable = "rg"      # the binary to run; if omitted and the crate has a single binary, that one is used
args = ["--version"]   # optional default args

Symposium attempts cargo binstall first, falls back to cargo install, and caches the result under ~/.symposium/cache/binaries/<crate>/<version>/bin/ (passing --root so the install doesn’t pollute ~/.cargo/bin). The chosen executable resolves to <cache>/bin/<executable>. Hooks that depend on this installation get <cache>/bin/ prepended to $PATH, so scripts can invoke the binary by name.

To install from a git repo instead of crates.io, set git:

[[installations]]
name = "tool"
source = "cargo"
crate = "tool"
git = "https://github.com/example/tool"
executable = "tool"   # required for git sources (crates.io is not consulted)

To install into the user’s global cargo location (~/.cargo/bin) instead of a symposium-managed cache, set global = true. No --root is passed; $PATH is not augmented (the binary is expected to already be on $PATH). This can be useful if you are using scripts which require globally-installed programs, or if you want to use tools separately in a CLI. A global = true installation must set executable.

[[installations]]
name = "rg"
source = "cargo"
crate = "ripgrep"
executable = "rg"
global = true

github

[[installations]]
name = "mytool-hooks"
source = "github"
url = "https://github.com/example/mytool-hooks"
script = "hooks/claude/mytool-rewrite.sh"   # optional; see below
args = ["--format"]

Acquires the repo (or a subtree, if url points at …/tree/<ref>/<path>) into a local cache. The chosen executable / script resolves to a file inside the cached tree.

executable/script may be set on the installation or on the hook (but not both, in any combination). Setting it on the installation pins this entry to a specific file; omitting it lets multiple hooks each pick a different file.

no source

Omit source entirely when you just need to point at a path on disk (or rely on install_commands to put one there):

[[installations]]
name = "tool"
executable = "/usr/local/bin/tool"

Or “shell-only” installations — useful as side-effect requirements:

[[installations]]
name = "setup"
install_commands = [
    "ln -sf $HOME/.cache/foo $HOME/.local/bin/foo",
]

[[hooks]]

Each [[hooks]] entry declares a hook that responds to agent events. For the JSON schemas that symposium-format hooks receive and produce, see Symposium hook events.

Examples

Run a cargo-installed binary as the hook:

[[installations]]
name = "rg"
source = "cargo"
crate = "ripgrep"
executable = "rg"

[[hooks]]
name = "rg-version"
event = "PreToolUse"
command = "rg"
args = ["--version"]

Install a tool as a side requirement and run a hook script from a separate github source:

[[installations]]
name = "mytool"
source = "cargo"
crate = "mytool"

[[installations]]
name = "mytool-hooks"
source = "github"
url = "https://github.com/example/mytool-hooks"

[[hooks]]
name = "rewrite"
event = "PreToolUse"
requirements = ["mytool"]
command = "mytool-hooks"
script = "hooks/claude/mytool-rewrite.sh"
args = ["--format"]

Inline a one-off cargo install directly:

[[hooks]]
name = "rg-test"
event = "PreToolUse"
command = { source = "cargo", crate = "ripgrep", executable = "rg" }
args = ["--version"]

Run a script file on disk (no source):

[[hooks]]
name = "check"
event = "PreToolUse"
command = { script = "scripts/check.sh", args = ["--strict"] }

A cargo install with a post-install step (e.g. to symlink a wrapper script):

[[installations]]
name = "mytool"
source = "cargo"
crate = "mytool"
install_commands = [
    "ln -sf $HOME/.symposium/cache/binaries/mytool/*/bin/mytool $HOME/.local/bin/mytool",
]

[[hooks]]
name = "mytool-rewrite"
event = "PreToolUse"
command = "mytool"
args = ["rewrite"]

Agent-specific hooks

An agent-specific hook expects a particular agent’s native wire format on stdin. Use this when you need full access to an agent’s event schema. Symposium still intermediates, but an agent-specific hook fires only when Symposium runs for that agent, and receives that agent’s input unchanged. On every other agent it does not fire, and nothing is converted. To cover the other agents, pair it with a format = "symposium" hook.

A plugin with a Claude-specific hook and a symposium fallback:

[[installations]]
name = "my-hook-binary"
source = "cargo"
crate = "my-hook-binary"

[[hooks]]
name = "check-claude"
event = "PreToolUse"
format = "claude"
command = "my-hook-binary"

[[hooks]]
name = "check-portable"
event = "PreToolUse"
format = "symposium"
command = "my-hook-binary"
args = ["--symposium"]

On Claude, check-claude fires (receives Claude’s native JSON). On other agents, check-portable fires (receives symposium canonical JSON).

Requirements

requirements ensures other installations are acquired before the hook runs. Useful when the hook’s command relies on something else being on disk (or eventually on $PATH).

[[installations]]
name = "mytool"
source = "cargo"
crate = "mytool"

[[hooks]]
name = "uses-mytool-via-script"
event = "PreToolUse"
requirements = ["mytool", { source = "cargo", crate = "ripgrep" }]
command = { script = "scripts/uses-mytool.sh" }

Requirements may also be declared on an [[installations]] entry. Whenever that installation is referenced — as a hook’s command or in another requirements list — its declared requirements are appended (one level, prerequisites first):

[[installations]]
name = "mytool"
source = "cargo"
crate = "mytool"

[[installations]]
name = "mytool-hooks"
source = "github"
url = "https://github.com/example/mytool-hooks"
requirements = ["mytool"]   # mytool gets installed whenever mytool-hooks is used

[[hooks]]
name = "rewrite"
event = "PreToolUse"
command = "mytool-hooks"
script = "hooks/claude/mytool-rewrite.sh"

Requirement installation is best-effort: failures are logged and dispatch continues.

Hook environment

Hooks are spawned with the following extras on top of the parent environment:

<name> is the installation name with non-alphanumeric characters replaced by _ (e.g. mytool-hooks -> SYMPOSIUM_DIR_mytool_hooks). Both the hook’s command installation and every requirement (recursively, one level via installation-level requirements) contribute.

Global cargo installs (global = true) don’t set $SYMPOSIUM_DIR_<name> or augment $PATH — the binary is expected to already be on the user’s $PATH via ~/.cargo/bin.

install_commands runs before env vars are set. The $SYMPOSIUM_* vars and the augmented $PATH are only available to the hook’s spawned process. install_commands runs earlier, inside the symposium dispatch process, so it cannot reference its own (or any other) installation’s env vars. Use absolute paths in install_commands instead.

Supported hook events

Not every agent delivers every event, and agents name them differently. See Agent support for which events each agent delivers.

Hook semantics

• Exit codes:

  • 0 — success: the hook’s stdout is parsed as JSON and merged into the overall hook result.
  • 2 (or no reported exit code): block. The action is blocked, dispatch stops, and the hook’s stderr becomes the reason the agent is given. See exit codes for how each agent receives the block.
  • any other non-zero code — treated as success for dispatching purposes; stdout is still parsed and merged when possible.

• Stdout handling: Hooks should write a JSON object to stdout to contribute structured data back to the caller. Valid JSON objects are merged together across successful hooks; keys from later hooks overwrite earlier keys. The exception is additionalContext on SessionStart, UserPromptSubmit and PostToolUse: symposium’s own context and every hook’s are joined, in order, so none replaces another.

• Stderr handling: If a hook exits with code 2 (or no exit code), dispatch returns immediately with the hook’s stderr as the block reason. Otherwise stderr is captured but not returned on success.

Testing hooks

To exercise a hook end to end, pipe a real agent payload into cargo agents hook <agent> <event>, using the event’s CLI name from the table above. For Claude Code:

echo '{"session_id":"s","cwd":"/path/to/project","hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"cargo test"}}' \
  | cargo agents hook claude pre-tool-use

This runs the full dispatch (including the automatic sync, when auto-sync is on) for the workspace at cwd, so the plugin must be installed and active there; the output is in the agent’s own format. The payload must be the named agent’s native JSON: you can also use antigravity, copilot, codex, or kiro as the agent name, each with that agent’s payload. To test a symposium-format handler on its own, pipe canonical JSON straight into it (see Testing).

[[predicate]]

Each [[predicate]] entry defines a custom predicate function that can be used in predicates expressions anywhere a predicate is accepted. Custom predicates extend the built-in predicate language with plugin-specific checks.

How custom predicates work

Custom predicates are registered globally — a predicate defined in one plugin can be used by any other plugin’s predicates expressions. Registration is unconditional: even if the defining plugin’s own crate predicates don’t match the current workspace, its [[predicate]] entries are still available.

When a predicate expression uses a function name that isn’t a builtin, Symposium looks it up in the custom predicate registry. If found, it spawns the declared command with the static args followed by the raw argument text from the expression.

[[installations]]
name = "cargo-bp-install"
source = "cargo"
crate = "cargo-bp"
executable = "cargo-bp"

[[predicate]]
name = "battery_pack"
command = "cargo-bp-install"
args = ["bp", "status", "--check"]

Usage in a predicates expression:

predicates = ["battery_pack(cli>=0.3)"]

This evaluates as:

cargo-bp bp status --check cli>=0.3

Exit 0 means the predicate passes; non-zero means it fails.

The argument is trimmed of leading/trailing whitespace before being passed. An empty argument — battery_pack() or battery_pack( ) — does not append anything to the command (only the static args are passed).

A custom predicate is a boolean gate only: it passes if the command exits 0. Its stdout does not affect the result; it may carry watch events that control caching.

Collisions

If two plugins define the same predicate name, both definitions are skipped and a warning is emitted. Skills referencing the collided name evaluate as false.

Caching

Symposium caches a custom predicate’s result on disk, per workspace (under ~/.symposium/cache/predicates/), keyed by the call as written (battery_pack(cli>=0.3)). Later syncs reuse the cached result without spawning the command until one of the inputs the predicate reported changes. Within one run, the same call is spawned at most once.

The predicate reports its inputs by printing watch events on stdout as JSON Lines, one object per line:

{"watchFile":"/path/to/project/Config"}
{"watchEnv":"LAMBDA_ENV"}
{"watchTime":60000}

The events from one run are combined, and a line that is not a known event is skipped with a warning. A predicate that exits non-zero is cached the same way as one that exits 0. A predicate that prints no events is cached forever, so report every input the result depends on, or print {"watchTime":0}. The cache is also discarded when a Symposium upgrade changes its format; delete ~/.symposium/cache/predicates/ to force every predicate to run again.

In Rust, the symposium-sdk crate prints these events for you: symposium_sdk::env::var and symposium_sdk::fs::read_to_string read a value and report it as an input, and symposium_sdk::predicate::PredicateEmitter writes events directly (watch_file, watch_env, watch_time).

[[mcp_servers]]

Each [[mcp_servers]] entry declares an MCP server that Symposium registers into the agent’s configuration during cargo agents sync (and the automatic sync that hooks run).

Symposium does not install MCP servers: unlike hooks and subcommands, they do not use [[installations]]. A stdio server’s command is written into the agent’s MCP configuration verbatim, so it must be an absolute path, or a command name the agent can find on the user’s PATH.

There are multiple MCP transports:

Stdio

[[mcp_servers]]
name = "my-server"
command = "/usr/local/bin/my-server"
args = ["--stdio"]
env = [{ name = "RUST_LOG", value = "info" }]

Stdio entries do not need a type field.

HTTP

[[mcp_servers]]
type = "http"
name = "my-server"
url = "http://localhost:8080/mcp"
headers = []

SSE

[[mcp_servers]]
type = "sse"
name = "my-server"
url = "http://localhost:8080/sse"
headers = []

How registration works

During cargo agents sync, each MCP server entry is written into each configured agent’s config file in the format that agent expects. Registration is idempotent — existing entries with correct values are left untouched, stale entries are updated in place.

When a user runs cargo agents sync (or the hook triggers it automatically), Symposium:

1. Collects [[mcp_servers]] entries from all enabled plugins.
2. Writes each server into the agent’s MCP configuration file.

All supported agents have MCP server configuration. Symposium handles the format differences — you declare the server once and it works across agents.

Servers are registered at the scope chosen by the hook-scope setting (see Configuration): with "project", in the files above; with "global" (the default), in each agent’s user-level configuration. Agents without a project-level file always get the user-level one. See each agent’s page under Supported agents for the global locations.

[subcommand.<name>]

A [subcommand.<name>] table adds a command that users and agents run as cargo agents <name>. By convention, <name> is the crate’s name, so an agent can run cargo agents <crate> --help to discover the crate’s own CLI. Symposium resolves command through the same installation pipeline hooks use, runs it with the installation’s args followed by the arguments typed after <name>, passes its output through, and exits with its exit code. The command owns its own arguments, validation, and --help.

# A recommendations entry; in a crate's own Symposium.toml, leave out name and depends-on.
name = "widgetlib"
depends-on = ["widgetlib"]

[[installations]]
name = "widgetlib-cli"
source = "cargo"
crate = "widgetlib-cli"
executable = "widgetlib-cli"

# `cargo agents widgetlib check --strict` runs `widgetlib-cli check --strict`
[subcommand.widgetlib]
description = "Check and inspect the widget definitions in this workspace"
audience = "agents"
command = "widgetlib-cli"

<name> is the word typed after cargo agents. It may contain only ASCII letters, digits, -, and _, and it must not be the name of a built-in command: init, sync, search, use, status, hook, plugin, self-update, crate-info, telemetry, or help.

A subcommand is listed in cargo agents --help, and can be run, only while its plugin is active and its own depends-on and predicates hold. If two active plugins define the same name, running it fails with an error naming both plugins. A subcommand’s gate does not keep its plugin out of dormancy.

Example: full manifest

# A recommendations entry; in a crate's own Symposium.toml, leave out name and depends-on.
name = "widgetlib"
depends-on = ["widgetlib"]

# Skills shipped inside the widgetlib crate source (in skills/)
[[plugins]]
source.cargo = "widgetlib"

# Additional skills hosted in a git repo (the recommendations repository does not accept git sources)
[[skills]]
depends-on = ["widgetlib^1.0"]
source.git = "https://github.com/org/widgetlib/tree/main/symposium/skills"

[[hooks]]
name = "check-widget-usage"
event = "PreToolUse"
matcher = "^(Bash|bash|run_command|execute_bash)$"
command = { script = "scripts/check-widget.sh" }

[[mcp_servers]]
name = "widgetlib-mcp"
command = "/usr/local/bin/widgetlib-mcp"
args = ["--stdio"]
env = []

Validation

cargo agents plugin validate path/to/Symposium.toml

This parses the manifest and reports any errors. The file must be named Symposium.toml for Symposium to discover it; to validate every entry in a registry directory, pass the directory instead (see Plugin sources). Crate name checking against crates.io is on by default; use --no-check-crates to skip it.