Bub

A tiny agent runtime, composable with plugins.

Bub is a small Python runtime for building agents in shared environments. It started in group chats, where multiple humans and agents had to work in the same conversation without hidden state, hand-wavy memory, or framework-specific magic.

Built on agents.md and Agent Skills , Bub stays intentionally small. Every turn stage is a pluggy hook. Builtins are included but replaceable. The same runtime drives CLI, Telegram, and any channel you add.

Website · GitHub

Quick Start

macOS and Linux:

curl -fsSL https://bub.build/install.sh | bash

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://bub.build/install.ps1 | iex"

The interactive installer uses a colored preset picker, accepts additional plugin dependencies, and runs bub onboard after installation. For automation, select a preset explicitly; non-interactive installs skip onboarding:

curl -fsSL https://bub.build/install.sh | bash -s -- --preset recommended --dependency extra-plugin

powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://bub.build/install.ps1))) --preset recommended --dependency extra-plugin"

Or from source:

git clone https://github.com/bubbuild/bub.git
cd bub
uv sync  # enough to run Bub from source

For local development, use make install instead so the website toolchain and prek hooks are installed too.

bub chat                         # interactive session
bub run "summarize this repo"    # one-shot task
bub gateway                      # channel listener mode

Why Bub

• Composable by design. Every turn stage is a plugin hook. Override one stage or replace the whole flow without forking the runtime.
• Tape context. Context is rebuilt from append-only records, not carried around as mutable session state. Easier to inspect, replay, and hand off.
• One runtime across surfaces. The same inbound pipeline runs across CLI, Telegram, and custom channels. Adapters change the surface, not the runtime model.
• Batteries included. CLI, Telegram, tools, skills, and model execution ship with the core runtime. Use the defaults first, replace them later.
• Operator equivalence. Humans and agents work inside the same runtime boundaries, with the same evidence trail and handoff model. No hidden operator class.

How It Works

Every inbound message goes through one turn pipeline. Each stage is a hook.

resolve_session → load_state → build_prompt → run_model
                                                   ↓
              dispatch_outbound ← render_outbound ← save_state

Builtins are registered first. External plugins load after them. At runtime, later plugins take precedence. There are no framework-only shortcuts.

Key source files:

• Turn orchestrator: src/bub/framework.py
• Hook contract: src/bub/hooks/specs.py
• Builtin hooks: src/bub/builtin/hook_impl.py
• Skill discovery: src/bub/skills.py

Extend It