Quick start

Since 0.6.0, Bub itself is split in two, so you can pick whichever part fits how you want to use it.

Start from the CLI

Open your terminal and work through the following steps on the command line:

(Optional) If you have never configured Bub, run this command first to finish the initial setup:
```
bub onboard
```
Create a workspace (a directory) anywhere and switch into it, then launch an interactive session with bub chat:
```
mkdir hello-bub && cd hello-bub
bub chat
```
Now try copying and pasting the text below to have a conversation with Bub:
```
Summarize the files in this directory
```

Press Ctrl+D or type ,quit to leave the interactive session. Run bub --help to see the commands and options, or see the CLI reference.

Run it with the SDK

If you want to embed the agent in your own Python project, start with the base SDK.

Create a new project and install Bub:

uv init --python 3.12 my-agent && cd my-agent
uv add bub

Save the following code as main.py:

import asyncio

import republic

from bub.core import Agent


async def main() -> None:
    agent = Agent(system_prompt="Be concise.")
    async with republic.get_model("openai:gpt-5-mini") as model:
        async with agent.run("What can you do?", model=model, tape="demo") as stream:
            async for event in stream:
                if event.kind == "text":
                    print(event.data.get("delta", ""), end="")


asyncio.run(main())

Run it with your API key:

export REPUBLIC_OPENAI_API_KEY=sk-...
uv run python main.py

When you need to look up other APIs, see the Python API reference.

Next steps

Congrats — you know the basics of Bub. From here you can explore either path more deeply to unlock more use cases.

CLI App A fuller walk through the app layer of Bub

SDK Build your own Bub agent, step by step

And of course, if you like, you can keep reading about the design ideas behind Bub.