https://github.com/psiace/bub
Bub it. Build it.
https://github.com/psiace/bub
agent ai clawdbot coding-agent openclaw python telegram
Last synced: 25 days ago
JSON representation
Bub it. Build it.
- Host: GitHub
- URL: https://github.com/psiace/bub
- Owner: PsiACE
- License: apache-2.0
- Created: 2025-07-13T06:16:21.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-02-21T11:59:13.000Z (28 days ago)
- Last Synced: 2026-02-21T17:55:56.713Z (28 days ago)
- Topics: agent, ai, clawdbot, coding-agent, openclaw, python, telegram
- Language: Python
- Homepage: http://bub.build/
- Size: 2.52 MB
- Stars: 399
- Watchers: 2
- Forks: 30
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Bub
[](https://github.com/psiace/bub/releases)
[](https://github.com/psiace/bub/actions/workflows/main.yml?query=branch%3Amain)
[](https://github.com/psiace/bub/graphs/commit-activity)
[](LICENSE)
> 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
```bash
git clone https://github.com/psiace/bub.git
cd bub
uv sync
cp env.example .env
```
Minimal `.env`:
```bash
BUB_MODEL=openrouter:qwen/qwen3-coder-next
OPENROUTER_API_KEY=your_key_here
```
Start interactive CLI:
```bash
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:
```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
```
## Telegram (Optional)
```bash
BUB_TELEGRAM_ENABLED=true
BUB_TELEGRAM_TOKEN=123456:token
BUB_TELEGRAM_ALLOW_FROM='["123456789","your_username"]'
uv run bub message
```
## Discord (Optional)
```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
```
## Documentation
- `docs/index.md`: getting started and usage overview
- `docs/deployment.md`: local + Docker deployment playbook
- `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
- `docs/discord.md`: Discord integration and operations
## Development
```bash
uv run ruff check .
uv run mypy
uv run pytest -q
just docs-test
```
## License
[Apache 2.0](./LICENSE)