bito

bito = building in the open.

bito is part of the building-in-the-open approach to AI-assisted development — a set of practices, templates, and tools for teams that work with coding agents. It can be used entirely on its own; the broader framework just gives it more context to work with.

AI coding agents generate documentation as they work — ADRs, design docs, changelogs, handoff notes. The quality varies between sessions. Sometimes you get crisp, well-structured prose. Sometimes you get bloated walls of text that no one wants to review.

bito catches the problems before you commit. It runs 18 deterministic writing checks — readability scoring, token budgets, section completeness, grammar, dialect enforcement, and style analysis. No LLM, no API calls, no network. Same input, same result, every time.

The goal: agent-generated documents that are clean enough to ship.

$ bito analyze docs/architecture.md

docs/architecture.md

  Readability: Grade 12.4, 24 sentences, 390 words
  Grammar:     8 issues, 3 passive (12.5%)
  Sticky:      Glue index 21.5%, 2 sticky sentences
  Pacing:      Fast 62% / Medium 29% / Slow 8%
  Length:      Avg 15.8 words, variety 10.0/10
  Transitions: 0% of sentences, 0 unique
  Overused:    "template" (1.3%), "skill" (1.1%), "design" (1.1%)
  Diction:     2 vague words
  Style:       Score 92/100, 2 adverbs, 0 hidden verbs

What it checks

analyze runs 18 checks in one pass:

| Category | What it catches | |----------|----------------| | Readability | Flesch-Kincaid grade level — flag documents that demand too much of the reader | | Grammar | Passive voice, double negatives, subject-verb disagreement, missing punctuation | | Sticky sentences | High "glue word" density — sentences stuffed with is, the, of, in | | Pacing | Monotonous sentence rhythm — all short punches or all long slogs | | Sentence variety | Length distribution — a score of 1/10 means every sentence is the same length | | Transitions | Percentage of sentences using connective phrases — low means choppy reading | | Overused words | Repeated non-trivial words that make the text feel circular | | Repeated phrases | Bigrams and trigrams that recur too often | | Echoes | Same word appearing in adjacent sentences (unintentional repetition) | | Complex paragraphs | Paragraphs with too many ideas competing for attention | | Conjunction starts | Sentences opening with But, And, So — fine in moderation, a tic in excess | | Cliches | "At the end of the day," "move the needle," "low-hanging fruit" | | Diction | Vague words (things, stuff, very) that add length without meaning | | Sensory language | Percentage of concrete, sensory words — useful for judging descriptive writing | | Consistency | Mixed US/UK spelling (color and colour in the same document) | | Dialect enforcement | Flag spellings that violate your project's chosen dialect (en-us, en-gb, en-ca, en-au) | | Acronyms | Tracks acronym usage for consistency | | Style score | Combined metric: adverb density, hidden verbs (nominalizations), overall polish |

Every check is deterministic. No API calls, no LLM, no network. The same input produces the same output every time.

Focused checks run individually when you need a specific gate:

# Does this handoff fit in 2,000 tokens?
$ bito tokens handoff.md --budget 2000
PASS: handoff.md is 546 tokens (budget: 2000)

# Is this user guide accessible to a general audience?
$ bito readability getting-started.md --max-grade 8
Error: getting-started.md scores 14.7 (max: 8). Simplify sentences or reduce jargon.

# Does this ADR have all the sections it needs?
$ bito completeness docs/decisions/0001-my-decision.md --template adr
PASS: docs/decisions/0001-my-decision.md (adr completeness check)

# How's the grammar?
$ bito grammar changelog.md
changelog.md: 16 sentences analyzed
  Passive voice: 2 instances (12.5%)
  Grammar issues: 3
    [MEDIUM] Sentence 3: Possible comma splice
    [LOW] Sentence 9: Multiple consecutive spaces found
    [MEDIUM] Sentence 16: Sentence missing terminal punctuation

Installation

Homebrew (macOS and Linux)

brew install claylo/brew/bito

From source

cargo install bito

Pre-built binaries

Download from the releases page. Binaries are available for macOS (Apple Silicon and Intel), Linux (x86_64 and ARM64), and Windows.

Usage

Config-driven linting

Define rules in your config file to map file paths to checks, then run them with one command:

bito lint docs/handoff.md
bito lint --json docs/handoff.md   # structured output for CI

If no rules match the file, it exits cleanly. See docs/README.md for rules configuration, accumulation, specificity, and inline suppressions.

Full analysis

bito analyze my-document.md

Add --json for machine-readable output. Add --dialect en-gb to enforce British spelling. Add --checks readability,consistency to run only specific checks. Add --exclude style,jargon to skip specific checks.

Quality gates

Quality gates are pass/fail checks designed for CI, pre-commit hooks, and automation:

# Token counting with budget enforcement
bito tokens <file> --budget <max>

# Readability with grade ceiling
bito readability <file> --max-grade <max>

# Section completeness against a template
bito completeness <file> --template <name>

# Grammar and passive voice analysis
bito grammar <file>

Built-in completeness templates: adr, handoff, design-doc. Define your own in a bito config file.

Every command exits non-zero on failure, writes structured JSON with --json, and works in pipes.

Dialect enforcement

Set a project dialect and bito flags wrong-dialect spellings alongside mixed-spelling inconsistencies:

# Via flag
bito analyze README.md --dialect en-us

# Via environment variable
export BITO_DIALECT=en-gb

# Via config file (.bito.toml)
dialect = "en-ca"

Supported dialects: en-us, en-gb, en-ca (Canadian hybrid: US -ize/-ise, UK for the rest), en-au.

MCP server

bito includes a built-in MCP server, so AI coding assistants can call quality gates directly during writing sessions:

{
  "mcpServers": {
    "bito": {
      "command": "bito",
      "args": ["serve"]
    }
  }
}

This exposes seven tools: analyze_writing, count_tokens, check_readability, check_completeness, check_grammar, lint_file, and get_info. The lint_file tool resolves path-based rules from your config, so the agent can check quality before writing. Total schema cost: ~2,003 tokens. See docs/mcp-development.md for context budget details.

Configuration

Drop a config file in your project and it takes effect automatically:

1. .bito.toml (or .yaml, .json) in the current directory or any parent
2. bito.toml (without dot prefix) in the current directory or any parent
3. ~/.config/bito/config.toml (user-wide defaults)

For backward compatibility, .bito-lint.* config file names are also discovered.

Closer files win. All formats (TOML, YAML, JSON) work interchangeably.

Environment variables override config files:

• BITO_LOG_PATH — log file path (daily rotation appends .YYYY-MM-DD)
• BITO_LOG_DIR — directory (file name defaults to bito.jsonl)
• BITO_ENV — environment tag (default: dev)
• Config file key: log_dir

# .bito.toml
dialect = "en-us"
token_budget = 2000
max_grade = 12.0
log_level = "warn"

Shell completions

Included in Homebrew installs and release archives. For manual setup:

# Bash
bito completions bash > ~/.local/share/bash-completion/completions/bito

# Zsh
bito completions zsh > ~/.zfunc/_bito

# Fish
bito completions fish > ~/.config/fish/completions/bito.fish

Development

crates/
├── bito/       # CLI binary
└── bito-core/  # Core library

Prerequisites

• Rust 1.89.0+ (2024 edition)
• just (task runner)
• cargo-nextest (test runner)

Quick Start

just check       # fmt + clippy + test
just test        # tests only (nextest)
just cov         # coverage report

Build Tasks

| Command | Description | |---------|-------------| | just check | Format, lint, deny, and test | | just fmt | Format code with rustfmt | | just clippy | Run clippy lints | | just test | Run tests with nextest | | just doc-test | Run documentation tests | | just cov | Generate coverage report |

xtask Commands

The project includes an xtask crate for build automation:

# Generate man pages
cargo xtask man

# Generate shell completions
cargo xtask completions

# Generate for specific shell
cargo xtask completions --shell zsh

Architecture

Crate Organization

• bito — The CLI binary. Handles argument parsing, command dispatch, MCP server, and user interaction.
• bito-core — The core library. Configuration loading, writing analysis, lint engine, and all 18 deterministic checks.

Error Handling

• Libraries use thiserror for structured error types
• Binaries use anyhow for flexible error propagation
• All errors include context for debugging

Configuration System

The ConfigLoader provides flexible configuration discovery:

use bito_core::config::ConfigLoader;

let config = ConfigLoader::new()
    .with_project_search(std::env::current_dir()?)
    .with_user_config(true)
    .load()?;

Features:

• Walks up directory tree looking for config files
• Stops at repository boundaries (.git by default)
• Merges multiple config sources with clear precedence
• Supports explicit file paths for testing

CI/CD

This project uses GitHub Actions for continuous integration:

• Build & Test — Runs on every push and PR
• MSRV Check — Verifies minimum supported Rust version
• Clippy — Enforces lint rules
• Coverage — Tracks test coverage

Dependabot

This project uses Dependabot for security monitoring, but not for automatic pull requests. Instead:

1. Dependabot scans for vulnerabilities in dependencies
2. A weekly GitHub Actions workflow converts alerts into issues
3. Maintainers review and address updates manually

This approach provides:

• Full control over when and how dependencies are updated
• Opportunity to batch related updates together
• Time to test updates before merging
• Cleaner git history without automated PR noise

Security alerts appear as issues labeled dependabot-alert.

Contributing

Contributions welcome! Please see AGENTS.md for development conventions.

Commit Messages

This project uses Conventional Commits:

• feat: — New features
• fix: — Bug fixes
• docs: — Documentation changes
• perf: — Performance improvements
• chore: — Maintenance tasks

Code Style

• Rust 2024 edition
• #![deny(unsafe_code)] — Safe Rust only
• Follow rustfmt defaults
• Keep clippy clean

License

MIT (LICENSE-MIT)