Bub

Bub it. Build it.

Bub is a coding agent CLI built on republic. It is designed for real engineering workflows where execution must be predictable, inspectable, and recoverable.

Four Things To Know

1. Command boundary is strict: only lines starting with , are treated as commands.
2. The same routing model is applied to both user input and assistant output.
3. Successful commands return directly; failed commands fall back to the model with structured context.
4. Session context is append-only tape with explicit anchor/handoff transitions.

Quick Start

git clone https://github.com/psiace/bub.git
cd bub
uv sync
cp env.example .env

Minimal .env:

BUB_MODEL=openrouter:qwen/qwen3-coder-next
OPENROUTER_API_KEY=your_key_here

Start interactive CLI:

uv run bub

Interaction Rules

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

Common commands:

,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

Telegram (Optional)

BUB_TELEGRAM_ENABLED=true
BUB_TELEGRAM_TOKEN=123456:token
BUB_TELEGRAM_ALLOW_FROM=["123456789","your_username"]
uv run bub telegram

Documentation

• docs/index.md: getting started and usage overview
• docs/features.md: key capabilities and why they matter
• docs/cli.md: interactive CLI workflow and troubleshooting
• docs/architecture.md: agent loop, tape, anchor, and tool/skill design
• docs/telegram.md: Telegram integration and operations

Development

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

License

Apache 2.0