**A common shape for agents that live alongside people.**

Bub started in group chats. Not as a demo or a personal assistant, but as a teammate that had to coexist with real humans and other agents in the same messy conversations — concurrent tasks, incomplete context, and nobody waiting.

It is hook-first, built on [pluggy](https://pluggy.readthedocs.io/), with a small core (~200 lines) and builtins that are just default plugins you can replace. Context comes from [tape](https://tape.systems), not session accumulation. The same pipeline runs across CLI, Telegram, and any channel you add.

pip install bub

uv run bub chat # interactive session

uv run bub run "summarize this repo" # one-shot task

uv run bub gateway # channel listener mode

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

Builtins are plugins registered first. Later plugins override earlier ones. No special cases.

Key source files:

- Turn orchestrator: [`src/bub/framework.py`](src/bub/framework.py)

- Hook contract: [`src/bub/hookspecs.py`](src/bub/hookspecs.py)

- Builtin hooks: [`src/bub/builtin/hook_impl.py`](src/bub/builtin/hook_impl.py)

- Skill discovery: [`src/bub/skills.py`](src/bub/skills.py)

- **Context from tape.** History is append-only facts. Anchors mark phase transitions. Context is assembled on demand — not accumulated, not compressed into lossy summaries.

- **Hooks all the way down.** The turn pipeline *is* hooks. Override `build_prompt`, `run_model`, or `render_outbound` to change behavior. The core does not privilege its own builtins.

- **One pipeline across channels.** CLI and Telegram share the same `process_inbound()` path. Hooks don't know which channel they're in.

- **Skills as documents.** Skills are `SKILL.md` files with validated frontmatter, not code modules with magic registration.

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

echo = "my_package.plugin:EchoPlugin"

See the [Extension Guide](https://bub.build/extension-guide/) for hook semantics and plugin packaging.

| Command | Description |

|---------|-------------|

| `bub chat` | Interactive REPL |

| `bub run MESSAGE` | One-shot turn |

| `bub gateway` | Channel listener (Telegram, etc.) |

| `bub login openai` | OpenAI Codex OAuth |

| `bub hooks` | Print hook-to-plugin bindings |

Lines starting with `,` enter internal command mode (`,help`, `,tools`, `,fs.read path=README.md`).

| Variable | Default | Description |

|----------|---------|-------------|

| `BUB_MODEL` | `openrouter:qwen/qwen3-coder-next` | Model identifier |

| `BUB_API_KEY` | — | Provider key (optional with `bub login openai`) |

| `BUB_API_BASE` | — | Custom provider endpoint |

| `BUB_API_FORMAT` | `completion` | `completion`, `responses`, or `messages` |

| `BUB_RUNTIME_MAX_STEPS` | `50` | Max tool-use loop iterations |

| `BUB_RUNTIME_MAX_TOKENS` | `1024` | Max tokens per model call |

| `BUB_RUNTIME_MODEL_TIMEOUT_SECONDS` | — | Model call timeout (seconds) |

We care less about whether an agent can finish a demo task, and more about whether it can coexist with real people under real conditions. Context is not baggage to carry forever — it is a working set, constructed when needed and let go when done.

Read more: [Context from Tape](https://tape.systems) · [Socialized Evaluation and Agent Partnership](https://bub.build/posts/2026-03-01-bub-socialized-evaluation-and-agent-partnership/)

- [Architecture](https://bub.build/architecture/) — lifecycle, hook precedence, error handling

- [Features](https://bub.build/features/) — what ships today and current boundaries

- [CLI](https://bub.build/cli/) — commands and comma mode

- [Skills](https://bub.build/skills/) — discovery and authoring

- [Extension Guide](https://bub.build/extension-guide/) — hooks, tools, plugin packaging

- [Channels](https://bub.build/channels/) — adapters and sessions

- [Deployment](https://bub.build/deployment/) — Docker, Telegram, operations

See [CONTRIBUTING.md](./CONTRIBUTING.md).

`bub` exposes four main commands (`run`, `gateway`, `chat`, `login`) plus two hidden ones (`hooks` for diagnostics, `message` as a compatibility alias for `gateway`).

Bub uses channel adapters to run the same pipeline across different I/O endpoints. Hooks don't know which channel they're in.

- `cli`: local interactive terminal — see [CLI](cli.md)

- `telegram`: Telegram bot — see [Telegram](telegram.md)

Every turn stage is a [pluggy](https://pluggy.readthedocs.io/) hook.

Builtins are ordinary plugins — override any stage by registering your own.

Both first-result hooks (override) and broadcast hooks (observer) are supported.

Safe fallback to prompt text when `run_model` returns no value (with `on_error` notification).

Automatic fallback outbound when `render_outbound` produces nothing.

Runtime events are recorded to tapes (default under `~/.bub/tapes`).

Context is reconstructed from tape records, not accumulated in session state.

- **CLI**: `run`, `chat`, `gateway`, `login`, `hooks` via Typer.

- **Model runtime**: agent loop with tool use, backed by [Republic](https://github.com/bubbuild/republic).

- **Comma commands**: `,help`, `,tools`, `,fs.read`, etc. Unknown commands fall back to shell.

- **Channels**: `cli` and `telegram` ship as defaults.

All of these are hook implementations. Replace what you need.

CLI and Telegram use the same `process_inbound()` path.

Hooks don't know which channel they're in.

Outbound routing is handled by `ChannelManager`.

Skills are `SKILL.md` files with validated frontmatter.

Plugins can ship their own by including a `skills/` directory.

External plugins are loaded via Python entry points (`group="bub"`).

Later-registered plugins run first and can override builtin behavior.

- `Envelope` is intentionally weakly typed (`Any` + accessor helpers).

- No builtin Discord adapter — implement one via `provide_channels`.