Metadata-Version: 2.4
Name: bub
Version: 0.2.3
Summary: Bub it. Build it. A collaborative agent for shared delivery workflows.
Project-URL: Homepage, https://bub.build
Project-URL: Repository, https://github.com/bubbuild/bub
Project-URL: Documentation, https://bub.build
Author-email: Chojan Shang <psiace@apache.org>, Frost Ming <me@frostming.com>, Hong Yi <zouzou0208@gmail.com>
License-File: LICENSE
Keywords: python
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.12
Requires-Dist: aiohttp>=3.13.3
Requires-Dist: any-llm-sdk[anthropic,vertexai]>=1.8.0
Requires-Dist: apscheduler>=3.11.2
Requires-Dist: discord-py>=2.6.4
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: loguru>=0.7.2
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: python-telegram-bot>=21.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rapidfuzz>=3.14.1
Requires-Dist: republic>=0.5.2
Requires-Dist: requests>=2.32.5
Requires-Dist: rich>=13.0.0
Requires-Dist: telegramify-markdown>=0.5.4
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# Bub

[![Release](https://img.shields.io/github/v/release/bubbuild/bub)](https://github.com/bubbuild/bub/releases)
[![Build status](https://img.shields.io/github/actions/workflow/status/bubbuild/bub/main.yml?branch=main)](https://github.com/bubbuild/bub/actions/workflows/main.yml?query=branch%3Amain)
[![Commit activity](https://img.shields.io/github/commit-activity/m/bubbuild/bub)](https://github.com/bubbuild/bub/graphs/commit-activity)
[![License](https://img.shields.io/github/license/bubbuild/bub)](LICENSE)

> Bub it. Build it.

Bub is a collaborative agent for shared delivery workflows, evolving into a framework that helps other agents operate with the same collaboration model.
It is not a personal-assistant shell: it is designed for shared environments where work must be inspectable, handoff-friendly, and operationally reliable.

> Documentation: <https://bub.build>

Built on [Republic](https://github.com/bubbuild/republic), Bub treats context as explicit assembly from verifiable interaction history, rather than opaque inherited state.
This aligns with [Socialized Evaluation](https://psiace.me/posts/im-and-socialized-evaluation/): systems are judged by how well teams can inspect, review, and continue work together.

## What Bub Provides

- Multi-operator collaboration in shared delivery environments.
- Explicit command boundaries for predictable execution.
- Verifiable history (`tape`, `anchor`, `handoff`) for audit and continuity.
- Channel-neutral behavior across CLI and message channels.
- Extensible tools and skills with a unified operator-facing workflow.

## Quick Start

```bash
git clone https://github.com/bubbuild/bub.git
cd bub
uv sync
cp env.example .env
```

Minimal `.env`:

```bash
BUB_MODEL=openrouter:qwen/qwen3-coder-next
LLM_API_KEY=your_key_here
```

Start interactive CLI:

```bash
uv run bub
```

## Interaction Model

- `hello`: natural language routed to model.
- `,help`: internal command.
- `,git status`: shell command.
- `, ls -la`: shell command (space after comma is optional).

Common commands:

```text
,help
,tools
,tool.describe name=fs.read
,skills.list
,skills.describe name=friendly-python
,handoff name=phase-1 summary="bootstrap done"
,anchors
,tape.info
,tape.search query=error
,tape.reset archive=true
,quit
```

## Channel Runtime (Optional)

Telegram:

```bash
BUB_TELEGRAM_ENABLED=true
BUB_TELEGRAM_TOKEN=123456:token
BUB_TELEGRAM_ALLOW_FROM='["123456789","your_username"]'
uv run bub message
```

Discord:

```bash
BUB_DISCORD_ENABLED=true
BUB_DISCORD_TOKEN=discord_bot_token
BUB_DISCORD_ALLOW_FROM='["123456789012345678","your_discord_name"]'
BUB_DISCORD_ALLOW_CHANNELS='["123456789012345678"]'
uv run bub message
```

## Development

```bash
uv run ruff check .
uv run mypy
uv run pytest -q
just docs-test
```

## License

[Apache 2.0](./LICENSE)
