bito v1.0.0

#What’s New

AI coding agents write documentation as they work. ADRs, design docs, changelogs, handoff notes — artifacts that capture decisions and context alongside code. The quality varies wildly between sessions. Sometimes you get clean, well-structured prose. Sometimes you get bloated walls of text with passive voice, inconsistent spelling, and sections that say “TBD.”

bito catches the problems before you commit. 18 deterministic writing checks, no API calls, no network, same input same result. Readability scoring, grammar analysis, token budgets, style metrics, dialect enforcement, cliche detection, structural completeness validation. Everything a linter does for code, but for prose.

This is the 1.0.0 release — and a rename. The project was called bito-lint through v0.3.0. The name changed because bito-lint lint is a stutter that gets old fast. The new name is cleaner: bito = building in the open.

#What changed in 1.0.0

Token counting is now a separate crate. The inline Claude tokenizer (38,360 token vocabulary, Aho-Corasick automaton, pulldown-cmark table decomposition) moved to ah-ah-ah as a standalone library. bito depends on it via ah-ah-ah = "0.1". This dropped ~40,000 lines from the repo (mostly the embedded vocabulary) and let other projects use token counting without pulling in a documentation linter.

Crate and binary renamed. bito-lint becomes bito, bito-lint-core becomes bito-core. Environment variables changed from BITO_LINT_* to BITO_*. Config discovery still finds .bito-lint.* files for backward compatibility.

#The full toolkit (v0.1 through v1.0)

For anyone encountering bito for the first time, here’s what you get:

18 writing checks in a single bito analyze pass: readability (Flesch-Kincaid), grammar (passive voice, subject-verb, punctuation), sticky sentences (glue word density), pacing (sentence rhythm), length variety, transitions, overused words, repeated phrases, echoes, complex paragraphs, conjunction starts, cliches, diction, sensory language, consistency, dialect enforcement, acronyms, and a composite style score.

Quality gates for CI or hooks: bito tokens with budget enforcement, bito readability with max-grade thresholds, bito completeness for template validation (ADR, handoff, design-doc), bito grammar for passive voice and structural issues.

Path-based lint rules (v0.2.0): configure which checks run on which files via glob patterns in your config. Inline suppressions with <!-- bito disable grammar --> directives for intentional exceptions.

Config discovery (v0.3.0): walks the directory tree looking for .bito.toml, .bito.yaml, or .bito.json. Merges project config with user-level config. Environment variable overrides for CI.

MCP server with 7 tools: bito serve exposes analyze, tokens, readability, grammar, completeness, lint, and custom content retrieval over Model Context Protocol. Total schema cost: ~2,003 tokens. Drop it into a Claude Code plugin and agents get quality feedback in-loop.

Custom content entries: store reusable content (writer personas, style guides, boilerplate) in your config and retrieve it via CLI or MCP. The building-in-the-open plugin uses this to load writer personas.

#Getting Started

Install via Homebrew:

brew install claylo/tap/bito

Or cargo:

cargo install bito
# or faster via binstall:
cargo binstall bito

Run a check:

bito analyze docs/architecture.md
bito tokens handoff.md --budget 2000
bito readability getting-started.md --max-grade 8

#How We Built This

bito started in early February as the enforcement layer for a documentation methodology Clay was building. The idea: AI agents should produce documentation as they work, but someone has to check the output. Not a human — a tool. Deterministic checks that run the same way every time, catching the problems agents don’t notice: readability that drifts above grade 12, passive voice creeping in, “TBD” placeholders surviving into committed artifacts.

The first release (v0.1.0) shipped with the core engine: tokenizer, readability scorer, grammar checker, and a writing analysis module that ran 18 checks in one pass. The checks were designed to be individually callable — bito tokens, bito readability, bito grammar — but the real power was bito analyze, which orchestrated all 18 and produced a single report.

The hook integration is where it got interesting. Clay set up a PostToolUse hook that runs bito on every markdown file the agent writes. Exit code 0 means silent pass — the agent never sees it. Exit code 2 means failure, and the stderr goes back to the agent as context. The agent sees “readability grade 14.7, max allowed 8” and rewrites in the same turn. No human in the loop. The quality gate runs inside the agent’s work cycle, not after it.

v0.2.0 added path-based lint rules. Different files need different checks — a handoff document needs completeness validation but not dialect enforcement; a changelog needs grammar checks but not readability gates. Glob patterns in the config map files to rule sets. Inline suppressions handle intentional exceptions without disabling the check globally.

v0.3.0 brought config discovery: walk the directory tree, find the nearest config file, merge with user-level defaults. This made bito usable across multiple projects without per-project setup. Custom content entries landed here too — store writer personas, style guides, or boilerplate in your config and retrieve it programmatically.

The MCP server came from a practical observation: agents calling bito analyze via shell commands worked, but the output was unstructured text that the agent had to parse. An MCP server returns structured JSON — scores, issues, pass/fail — that agents can act on directly. Seven tools, ~2,003 tokens of schema. The hook integration is the reliable path: stderr feedback goes straight to the agent whether it wants it or not. The MCP server is the upgrade for agents that handle structured data well.

The token counting module grew heavier than expected. What started as a simple wrapper around a vocabulary file became a full tokenizer with two backends (Claude greedy matching, OpenAI exact BPE), a Decomposer trait for structured content boundaries, a three-tier fast-path heuristic for markdown tables, and 64 tests validated against live API responses. In March, Clay extracted it into ah-ah-ah — a standalone crate that any project could depend on. bito’s v1.0.0 replaced ~40,000 lines of inline tokenizer code with a single dependency.

The rename happened the same week. Clay had been living with bito-lint for six weeks, and the moment he typed bito-lint lint he knew. “When we got to ‘bito-lint lint’ I knew this was a bad choice.” The fix was clean: clone the repo with full history, update remotes, rename everything in one commit (108 files, 909 insertions, 40,235 deletions — mostly the extracted vocabulary). The old repo gets a deprecation notice. No GitHub rename, no redirect confusion. Two working repos, one active.

The value proposition shifted during development in a way Clay noticed in real time. bito was originally motivated by token budgets — making sure handoff documents fit within 2,000-token limits, keeping context windows manageable. Then 1M context windows arrived and token budgets stopped being the constraint they used to be. The value migrated to editorial quality: readability scores, grammar checks, structural enforcement. The checks that keep agent prose publishable, not just fittable. The token counting capability didn’t go away — it moved to ah-ah-ah, where it serves a broader audience — but the center of gravity for bito shifted to what a 1M context window still can’t fix: writing quality.

Ten releases in six weeks. v0.1.0 through v1.0.0. Every one shipped with tests, CI, pre-built binaries for five platforms (macOS x86/ARM, Linux x86/ARM, Windows x86). The pace was possible because the architecture was right from the start: each check is an independent module, config is declarative, the CLI is just a thin layer over the library. Adding a check meant writing a function that takes text and returns findings. No framework, no plugin system, no ceremony.