What is bub AGENTS.md?

A set of repository instructions for Bub, a Python command-line application with chat, messaging channels, tools, and bundled skills.

Use it when installing dependencies, running Bub, changing its Python or website code, or writing and checking tests.

It gives a coding agent one place to learn the project layout, coding rules, and commands instead of guessing how the repository works.

bub AGENTS.md — Instructions file by bubbuild

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add instructions/bubbuild/bub/agents-md

Clone the repo

git clone --depth 1 https://github.com/bubbuild/bub

Made for: Codex, OpenCode.

Per session 825 This file is loaded in full into every session.

When invoked 825 The same file — it is already loaded in full.

Security scan A 0 findings. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.00825	$0.00825
Opus 5	$0.00413	$0.00413
Sonnet 5	$0.00165	$0.00165
Haiku 4.5	$0.00082	$0.00082

Measured yesterday against content hash 9cbe896c37fa, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

bub AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

AGENTS.md · 64 lines

How it starts

The opening of the file, as written. The whole thing — 64 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Repository Guidelines

Project Structure & Module Organization

Core code lives under src/:

src/bub/__main__.py: Typer CLI entrypoint.
src/bub/framework.py: turn orchestration and outbound routing.
src/bub/hooks/: hook specifications, execution helpers, and interception contracts.
src/bub/channels/: channel bases, routing contracts, admission policy, and lifecycle manager.
src/bub/{envelope,turn,streaming,errors,model_selection}.py: small kernel vocabulary owned by each concern.
src/bub/builtin/: builtin runtime, CLI wiring, settings, tools, and tape services.
src/bub/channels/: channel abstractions plus CLI and Telegram adapters.
src/bub/skills.py / src/bub/tools.py: skill discovery and tool registry.
src/skills/: bundled skills shipped with Bub.

Tests live in tests/. The website and docs runtime lives in website/.

Build, Test, and Development Commands

uv sync: install or update the Python environment; enough to run Bub from source or for deployment-only hosts.
make install: full local development bootstrap; sync Python deps, install website deps, and install prek hooks.
uv run bub chat: run the interactive CLI.
uv run bub gateway: start channel listener mode.
uv run bub run "hello": run one inbound message through the full framework pipeline.
uv run bub hooks: inspect discovered hook bindings.
uv run ruff check .: run Ruff directly when you only want lint feedback.
uv run mypy src: run mypy directly against src/.
uv run pytest -q: run the main test suite without doctests.
make test: run pytest with doctests enabled.
make check: lock validation, prek, and typing.
make docs / make docs-test / make docs-preview: serve, build, or preview the Astro website/docs in website/.

Coding Style & Naming Conventions

Python 3.12+, 4-space indentation, and type hints for new or modified logic.
Use snake_case for modules/functions/variables, PascalCase for classes, and UPPER_CASE for constants.
Keep functions focused and composable; avoid hidden side effects.
Format and lint with Ruff. Keep line length within 120 unless an existing file clearly follows a different local convention.

Read the full file on GitHub · 64 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

yesterday First seen · 64 lines · 825 tokens per session scan A 9cbe896c37fa

Subscribe to this mod's changes

bub AGENTS.md is an instructions file published in the GitHub repository bubbuild/bub (1,591 stars, last pushed 6d ago), licensed Apache-2.0. It adds 825 tokens to every session, about $0.0041 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Languages Testing Writing and docs agent agents ai ai-agents aiagentframework python

bub AGENTS.md

Getting it into your agent

What it costs to keep this loaded

Grade A, and why

Nothing flagged

How it starts

Repository Guidelines

Project Structure & Module Organization

Build, Test, and Development Commands

Coding Style & Naming Conventions

What this file has done since we first saw it

Other instructions, from other repositories

mcp-toolbox GEMINI.md

open-agents AGENTS.md

relay AGENTS.md

agno CLAUDE.md

axonhub AGENTS.md

axonhub CLAUDE.md