What Is Bub? A Hook-First Runtime for Agentic Workflows

What Is Bub? A Hook-First Runtime for Agentic Workflows

Bub is a compact Python runtime designed for building AI agents that operate in shared environments — alongside humans, in group chats, or across multiple channels. Unlike heavyweight agent frameworks that impose rigid abstractions, Bub takes a hook-first approach: every stage of a conversational turn is a pluggable hook, letting you override exactly what you need without forking the core.

Why Hook-First Matters

In traditional agent frameworks, the runtime's behavior is a black box — you extend it through inheritance or configuration flags. Bub flips this model. Every phase of a turn — session resolution, state loading, prompt building, model execution, state saving, and outbound dispatch — is exposed as a pluggy hook. You can swap a single stage or replace the whole pipeline without touching the runtime itself.

Key Features

• Tape Context: Instead of mutable session state, Bub rebuilds context from append-only records. This makes debugging, replay, and handoffs straightforward.
• One Runtime, Multiple Surfaces: The same pipeline powers CLI, Telegram bots, and custom channels. Adapters change the surface, not the agent logic.
• Batteries Included: CLI, Telegram integration, tool execution, skill discovery, and model execution ship with the core.
• Operator Equivalence: Humans and agents share the same runtime boundaries, evidence trail, and handoff model — no hidden operator class.

Quick Start

Installing Bub takes seconds:

pip install bub
bub chat   # Interactive session
bub run "summarize this repo"   # One-shot
bub gateway   # Channel listener mode

For development, clone the repo and use uv sync — Bub uses modern Python tooling with no framework bloat.

Extending Bub

Plugins are Python modules with hook implementations registered via entry points. A minimal echo plugin is just 10 lines:

from bub import hookimpl

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

    @hookimpl
    async def run_model(self, prompt, session_id, state):
        return prompt

Bub is Apache-2.0 licensed and available on GitHub with over 1,500 stars. Whether you're building a personal assistant, a team bot, or a multi-channel automation agent, Bub's hook-first architecture gives you the flexibility to start simple and extend intentionally.