# `BeamAgent.Plugins`
[🔗](https://github.com/beardedeagle/beam-agent/blob/main/lib/beam_agent/plugins.ex#L1)

Plugin management for the BeamAgent SDK.

This module provides global plugin registration -- listing, registering,
unregistering, and querying plugins that are shared across all sessions.
Mutations notify the reload bus so live sessions react without restart.

## When to use directly vs through `BeamAgent`

Most callers interact with plugins through `BeamAgent`. Use this module
directly when you need focused access to plugin operations -- for example,
in a plugin management UI, a plugin marketplace browser, or a configuration
tool that bulk-enables/disables plugins.

## Quick example

```elixir
# Register a plugin:
:ok = BeamAgent.Plugins.register("my-plugin", %{
  name: "My Plugin",
  description: "Does cool stuff",
  version: "1.0.0",
  enabled: true
})

# List all plugins:
plugins = BeamAgent.Plugins.list()
for p <- plugins, do: IO.puts(p.name)

# Unregister:
:ok = BeamAgent.Plugins.unregister("my-plugin")
```

## Architecture deep dive

This module is a thin Elixir facade that delegates every call to the
`:beam_agent_catalog` Erlang module's global registry functions. Zero
business logic, zero state, zero processes live here -- the Erlang module
owns the implementation. The underlying plugin data is stored in the
unified ETS table managed by `:beam_agent_registry`.

See also: `BeamAgent`, `BeamAgent.Catalog`, `BeamAgent.Agents`.

# `plugin_def`

```elixir
@type plugin_def() :: %{
  :id =&gt; binary(),
  :name =&gt; binary(),
  :kind =&gt; :agent | :plugin | :slash,
  :enabled =&gt; boolean(),
  optional(:description) =&gt; binary(),
  optional(:version) =&gt; binary(),
  optional(:config) =&gt; map()
}
```

A plugin definition stored in the global registry.

# `clear`

```elixir
@spec clear() :: :ok
```

Remove all registered plugins.

# `ensure_table`

```elixir
@spec ensure_table() :: :ok
```

Create the global registry ETS table. Idempotent.

# `get`

```elixir
@spec get(binary()) :: {:ok, plugin_def()} | {:error, :not_found}
```

Fetch a single plugin by id.

# `list`

```elixir
@spec list() :: [plugin_def()]
```

List all registered plugins.

# `register`

```elixir
@spec register(binary(), map()) :: :ok
```

Register a plugin globally (shared across all sessions).

## Parameters

- `id` -- unique binary identifier for the plugin.
- `opts` -- map of plugin options (`:name`, `:description`, `:version`, `:enabled`, `:config`).

# `unregister`

```elixir
@spec unregister(binary()) :: :ok
```

Unregister a plugin by id. Idempotent.

---

*Consult [api-reference.md](api-reference.md) for complete listing*