Skip to content

Install and use plugins

Goal. Understand which format packs ship with binoc and when a separately published plugin package is needed.

Prerequisites. binoc working at the command line (see Diff two snapshots).

The current distribution model

The published binoc wheel is a fat wheel: most first-party format packs are compiled in and available without installing another package. The plugin catalog records each pack's distribution tier.

binoc-sqlite and binoc-stat-binary are not published as separate PyPI wheels today. binoc-stat-binary ships in the fat wheel. SQLite remains an explicit source-build opt-in and is excluded from the default bundled feature set.

Separately published plugins still use normal Python packaging. When a plugin is published independently, install it in the same environment as binoc:

pip install some-binoc-plugin
binoc diff snapshots/v1 snapshots/v2

With uvx, include the plugin package in the temporary environment:

uvx --with some-binoc-plugin binoc diff snapshots/v1 snapshots/v2

How it works

For separately published plugins, binoc scans Python entry points in the group binoc.plugins at startup and loads everything it finds. An installed plugin package declares an entry point in its pyproject.toml and exposes either a register(registry) function (for Python plugins) or a native module (for Rust plugins built with maturin). Either way, the host learns about the plugin's available surfaces at startup.

You don't need to "enable" the plugin to load it; installing the package is enough. Dataset-specific semantics still belong in dataset config when a plugin documents them.

See Plugin discovery for the exact strings involved, and Plugin model for the conceptual overview.

Where do plugins come from?

The binoc-* namespace on PyPI is the shared ecosystem namespace (similar to pytest-* or llm-*). The in-tree format packs are reference implementations, but separate PyPI publishing for native rule packs is paused until those rule-family plugin surfaces graduate.

For in-tree reference implementations see the model-plugins/ directory in the repository. They double as worked examples for the current Plugin model.

List what's registered

Once a plugin is installed, any stable plugin surfaces it exposes are available through the host. Current diff behavior uses correspondence rule packs and renderer plugins.

For current dataset semantics, use dataset config. For the rule-family dispatch model, see Dispatch model.

Trust

Plugins run in-process with the host's privileges. Only install plugins from sources you trust at least as much as you trust running their code on your machine. See Security and trust for the short version and Security posture and auditing ADR for the long version.

Where to go next