Skip to content
Bub Bub Bub

Getting Started

This page introduces Bub and helps you pick one of three usage paths so the rest of this section reads in the right order.

Bub is a small Python framework for building agents that run in shared environments. The kernel handles a single turn pipeline; everything else is a plugin. You opt into channels, tools, skills, and storage backends as you need them.

Before you begin

Section titled “Before you begin”

You should have:

  • Python 3.12 or newer
  • uv on your PATH
  • one model access path for the model-backed step:
    • an API key exported as BUB_API_KEY or as a provider-specific BUB_<PROVIDER>_API_KEY, or
    • OpenAI Codex OAuth via uv run bub login openai with BUB_MODEL=openai:gpt-5-codex

If you only want to inspect Bub without running a model turn, the API key is optional — comma commands such as ,help work without one.

Three usage paths

Section titled “Three usage paths”

Bub serves three audiences. Pick the one that matches your goal today:

  • Operator — you want to run a Bub instance, configure channels, and ship it. Read this section for the first turn, then move to Operate Bub for configuration, channels, and deployment.
  • Plugin author — you want to extend Bub with new hooks, tools, or skills. Read this section through Build Your First Plugin, then move to Build Plugins for the full extension contract.
  • Distribution author — you want to package Bub plus a curated plugin set for a specific scenario. Read this section first, then go to Distribution for packaging conventions.

All three audiences share the same starting point: install Bub, run one turn, and confirm the runtime is healthy.

Section titled “Recommended path”

Work through these pages in order:

  1. Install Bub — install from PyPI or from source, pin Bub as a framework dependency, verify with bub hooks.
  2. Run Your First Turn — create a workspace, write AGENTS.md, send ,help, then run a model-backed turn.
  3. Author Your First Skill — write a project skill under .agents/skills/ and call it from a turn.
  4. Build Your First Plugin — ship a minimal plugin via Python entry points and verify it loads.

If you want the conceptual model first, read Concepts before any of the tutorials.

Next steps

Section titled “Next steps”