heybabb — What It Is, How It Works, Why It Exists
What it does
heybabb is a command-line companion for Babb Works. It answers questions about what Babb is building, explains how each tool works, and reports on current development activity — all from the terminal.
The commands:
heybabb greet Babb
heybabb tools list everything Babb Works is building
heybabb tool <name> full breakdown of a specific tool
heybabb now what the team is working on right now
heybabb version knowledge base build info
heybabb ask "<question>" ask anything in natural language
heybabb ask --ai "<question>" same, powered by Claude
Without --ai, heybabb answers offline from a compiled knowledge base — no network required. With --ai, it uses the Claude API for richer, more conversational responses grounded in the same knowledge.
How it works
heybabb is a Python CLI built with Typer and Rich. It ships with a compiled knowledge file — a JSON snapshot of all Babb tools, their status, architecture, and current development activity — built from the organization’s GitHub repositories.
The knowledge base is generated by the character system, a companion project that scans a GitHub organization and produces a structured knowledge file any CLI can consume. The generation is automated: point it at your org, it reads your repos, and it builds the knowledge. heybabb is the consumer; character is the producer.
Architecture:
- CLI layer — Typer app with subcommands (
tools,tool,now,ask,version,sync,vision) - Knowledge layer — loads the compiled JSON knowledge base, performs local lookups and fuzzy matching
- Response layer — Rich-formatted terminal output with consistent styling
- AI layer (optional) — sends the question plus relevant knowledge context to Claude for natural language responses. Requires an Anthropic API key.
The offline-first design is intentional. A developer checking “what does BitPads do?” at 2 AM on a plane should get a useful answer without a network connection. The AI mode is for deeper, more conversational exploration when connectivity is available.
Why it exists
Developer documentation is where knowledge goes to die. READMEs get stale. Wikis get abandoned. Confluence pages multiply until nobody can find anything. The knowledge exists — scattered across 60+ repositories — but accessing it requires knowing which repo to look in, which file to read, and which section is current.
heybabb exists to collapse that search into a single command. Instead of navigating repos, you ask. Instead of reading READMEs, you get a synthesized answer. The compiled knowledge base ensures consistency — every answer comes from the same snapshot, not from whichever README was last updated.
heybabb also exists because Babb believes that every organization should be able to talk to itself from the terminal. The character system that powers heybabb is designed to work for any GitHub organization, not just Babb. Point it at your org, generate a knowledge base, build a CLI companion. The technology is not proprietary to Babb — the voice is.
Current status
- Version: 0.1.0
- Runtime: Python 3.11+
- Dependencies: Typer, Rich, Anthropic SDK (optional)
- Knowledge base: Compiled from Babb Works GitHub organization
- AI mode: Claude-powered, requires API key
- Related:
character(knowledge base generator for any org)