Bub

Bub is a lightweight Python runtime (~200 lines of core code) designed for multi-human and multi-agent shared conversational environments such as group chats. Its design centers on two key mechanisms:

Hook-first Orchestration: Each inbound message flows through a turn pipeline — resolve_session → load_state → build_prompt → run_model → save_state → render_outbound → dispatch_outbound — where every stage is a pluggy-based hook. Developers can override any stage or the entire flow via Python entry-points without forking the runtime itself.

Tape Context Model: Unlike traditional mutable session state, Bub rebuilds context from an append-only tape composed of immutable fact sequences. Anchors mark phase boundaries, and Corrections append new facts to supersede old records without overwriting. This makes every decision auditable, replayable, and forkable, supporting sub-agent history search and handoff tracking.

Bub adopts a channel-agnostic design where the same process_inbound() pipeline drives CLI, Telegram, and custom channels. Built-in capabilities (CLI, Telegram adapter, tools, Skills, model execution) work out of the box but are fully replaceable. Humans and agents share the same runtime boundary and handoff semantics with no special operator class. The plugin system uses entry-points (group="bub") with last-registered-wins priority and no framework privilege paths.

The project supports Comma Commands for inline instructions, skill discovery and authoring based on the agents.md / Agent Skills specifications, and provides Dockerfile and docker-compose.yml for containerized deployment. The default model is openrouter:qwen/qwen3-coder-next, with flexible model provider, API format, and call parameter switching via environment variables.

Installation & Quick Start

pip install bub

git clone https://github.com/bubbuild/bub.git
cd bub
uv sync

uv run bub chat                         # Interactive REPL
uv run bub run "summarize this repo"    # Single turn execution
uv run bub gateway                      # Channel listener mode

CLI Commands

Environment Variables

Plugin Extension Example

from bub import hookimpl

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

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

[project.entry-points."bub"]
echo = "my_package.plugin:EchoPlugin"

Key Source Files