Skip to content
Bub Bub Bub

Getting Started

Bub is a small Python framework for building agents in shared environments. It gives you a clear turn pipeline, a simple workspace layout, and a normal Python packaging story for extensions.

If you are new to Bub, start here. This section helps you get one working setup first, then add only the pieces you actually need.

What You Need To Know

Section titled “What You Need To Know”
  1. A small core Bub runs each turn through a visible hook pipeline. You can replace one stage without rewriting the whole system.
  2. A shared workspace Put workspace instructions in AGENTS.md and repeatable local procedures in .agents/skills.
  3. Standard Python extensions Plugins are normal Python packages discovered through entry points. Skills can ship with plugins through regular build tooling, including PEP 517 build hooks.
  4. A migration path from other agents Bub follows agents.md for workspace instructions and Agent Skills for skills. If you already use those conventions elsewhere, you can usually reuse your AGENTS.md file and skill directories.

Before You Start

Section titled “Before You Start”

Have these ready:

  • Python 3.12+
  • uv
  • one model access path for the model-backed step:
    • an API key via BUB_API_KEY, or
    • OAuth login via uv run bub login openai

What You Will Build

Section titled “What You Will Build”

By the end of this section, you will have:

  • one local Bub workspace
  • one project skill under .agents/skills
  • one installed extension from bub-contrib
  • one minimal plugin package you can iterate on locally
Section titled “Recommended Path”
  1. Run Bub Locally Install Bub, create a workspace, inspect the builtin kernel, and complete the first successful turn.
  2. Equip Your Bub Add rules in AGENTS.md, add one project skill, and install only the extension you actually need.
  3. Build Your First Plugin Create a minimal plugin package, install it locally, and verify that Bub loads its hook implementations.

If You Need Something Else First

Section titled “If You Need Something Else First”

This section is meant to get you started, not cover every option. Deployment details, full Telegram setup, and the complete plugin API stay in the Guides, Concepts, and Extending sections.