Plugins

The GptmePlugin interface for packaging tools, hooks, commands, and providers into an installable plugin. See Plugin System for how plugins are discovered and configured.

Plugin system for gptme.

Provides a simple folder-based plugin discovery mechanism where each plugin is a directory containing:

• __init__.py (plugin metadata)

• tools/ (optional: tool modules)

• hooks/ (optional: hook modules)

• commands/ (optional: command modules - future)

Plugins are discovered from configured paths and loaded similarly to how custom tools currently work via TOOL_MODULES.

class gptme.plugins.GptmePlugin

Unified plugin manifest.

A plugin can provide any combination of tools, hooks, commands, and LLM providers. Both folder-based plugins (discovered from filesystem paths) and entry-point plugins (installed packages) produce instances of this class.

For entry-point plugins, register via pyproject.toml:

[project.entry-points."gptme.plugins"]
my_plugin = "my_package:plugin"

Where plugin is a GptmePlugin instance.

__init__(name: str, provider: ProviderPlugin | None = None, tool_modules: list[str] = <factory>, tools: list[ToolSpec] = <factory>, register_hooks: Callable[[], None] | None = None, register_commands: Callable[[], None] | None = None, init: Callable[[Config], None] | None = None) → None

init: Callable[[Config], None] | None = None

Optional plugin-level initialization. Called once at discovery time with the full Config, before subsystem init. Plugin-specific config is stored under [plugin.<name>] in the TOML config files and is accessible via:

user_cfg = config.user.plugin.get("<name>", {})
project_cfg = config.project.plugin.get("<name>", {}) if config.project else {}

Note that config.project may be None when no project config is present, so always guard access with a if config.project check.

name: str

Unique plugin name.

provider: ProviderPlugin | None = None

LLM provider definition. When set, the plugin registers a custom LLM provider accessible as <provider.name>/<model>.

register_commands: Callable[[], None] | None = None

Callable that registers commands via register_command(). Called once during command initialization.

register_hooks: Callable[[], None] | None = None

Callable that registers hooks via register_hook(). Called once during hook initialization.

tool_modules: list[str]

Module names containing ToolSpec instances. These are passed to the existing tool discovery system.

tools: list[ToolSpec]

Direct ToolSpec instances. Useful for entry-point plugins that want to provide tools without a separate module.

class gptme.plugins.Plugin

Represents a discovered plugin with its components.

__init__(name: str, path: Path, tool_modules: list[str] = <factory>, hook_modules: list[str] = <factory>, command_modules: list[str] = <factory>) → None

gptme.plugins.detect_install_environment() → str

Detect how gptme is installed.

Returns:

‘pipx’, ‘uvx’, ‘venv’, or ‘system’

Return type:

Environment type

gptme.plugins.discover_all_plugins(folder_paths: list[Path] | None = None, enabled_plugins: list[str] | None = None) → list[GptmePlugin]

Run all discovery mechanisms and merge results.

Parameters:

• folder_paths – Paths to search for folder-based plugins.

• enabled_plugins – Optional allowlist of plugin names (None = all).

Returns:

List of all discovered GptmePlugin instances.

gptme.plugins.discover_plugins(plugin_paths: list[Path]) → list[Plugin]

Discover plugins from the given search paths with smart src/ layout detection.

For each path, tries in order:

1. If path itself is a plugin (has __init__.py + tools/hooks/commands), load it

2. If path has pyproject.toml + src/ subdirectory, search src/ for plugins

3. Otherwise search for plugin directories in the path

A valid plugin is a directory containing:

• __init__.py (makes it a Python package)

• At least one of: tools/, hooks/, commands/ subdirectories

Parameters:

plugin_paths – List of paths to search for plugins

Returns:

List of discovered Plugin instances

gptme.plugins.get_all_plugins() → list[GptmePlugin]

Return all discovered plugins.

Returns an empty list if discover_all_plugins() has not been called.

gptme.plugins.get_install_instructions(plugin_path: Path, env_type: str | None = None) → str

Get installation instructions for a plugin based on the environment.

Parameters:

• plugin_path – Path to the plugin directory (with pyproject.toml)

• env_type – Environment type (‘pipx’, ‘uvx’, ‘venv’, ‘system’). If None, auto-detects using detect_install_environment()

Returns:

Installation command string

gptme.plugins.get_plugin_tool_modules(plugin_paths: list[Path], enabled_plugins: list[str] | None = None) → list[str]

Get tool module names from all enabled plugins.

This integrates with the existing tool discovery system by returning module names that can be passed to _discover_tools().

Parameters:

• plugin_paths – Paths to search for plugins

• enabled_plugins – Optional allowlist of plugin names (None = all)

Returns:

List of module names containing tools (e.g., “my_plugin.tools”)

gptme.plugins.register_plugin_commands(plugin_paths: list[Path], enabled_plugins: list[str] | None = None) → None

Register commands from all enabled plugins.

Discovers plugins, imports their command modules, and calls their register() functions to register commands with the gptme command system.

Parameters:

• plugin_paths – Paths to search for plugins

• enabled_plugins – Optional allowlist of plugin names (None = all)

gptme.plugins.register_plugin_hooks(plugin_paths: list[Path], enabled_plugins: list[str] | None = None) → None

Register hooks from all enabled plugins.

Discovers plugins, imports their hook modules, and calls their register() functions to register hooks with the gptme hook system.

Parameters:

• plugin_paths – Paths to search for plugins

• enabled_plugins – Optional allowlist of plugin names (None = all)