Skip to content
Bub Bub Bub

Write your first plugin

A plugin changes how the Bub app handles a task. This one replaces the model stage with an echo response, so you can check plugin discovery and turn processing without model credentials. To use the builtin agent’s model calls and conversation recording, keep its model implementation.

Before you begin

Section titled “Before you begin”

Install Python 3.12+ and uv as described in Install Bub. This tutorial creates a project environment containing Bub 0.6.0 and your plugin.

Create the package

Section titled “Create the package”

Create this package layout:

bub-echo-plugin/
├── pyproject.toml
└── src/
    └── bub_echo_plugin/
        ├── __init__.py
        └── plugin.py

Leave __init__.py empty. Put this in pyproject.toml:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "bub-echo-plugin"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["bub[app]>=0.6.0"]

[project.entry-points."bub"]
echo = "bub_echo_plugin.plugin:echo_plugin"

[tool.hatch.build.targets.wheel]
packages = ["src/bub_echo_plugin"]

The bub entry-point group tells the application where to find the plugin.

Implement the response

Section titled “Implement the response”

Put this in src/bub_echo_plugin/plugin.py:

from bub import hookimpl


class EchoPlugin:
    @hookimpl
    def run_model(self, prompt, session_id, state):
        return f"[echo:{session_id}] {prompt}"


echo_plugin = EchoPlugin()

The application still builds the incoming prompt. Your run_model implementation supplies the response instead of calling the builtin agent.

Install and try it

Section titled “Install and try it”

From the plugin directory, install the project and its dependencies:

uv sync
uv run bub hooks

uv sync installs this package in editable mode. Run Bub through uv run in the same project so it can discover the plugin.

The report should include echo under run_model. The builtin agent appears under run_model_stream.

uv run bub run "hello from my plugin"

With no other plugin overriding the model stage, the response contains:

[echo:cli:local] hello from my plugin

If echo is missing, check that the package was installed in the environment running bub. If it is listed but another response wins, inspect the other model hooks and their priority.