{"id":44145091,"url":"https://github.com/claylo/bito-lint","last_synced_at":"2026-03-06T06:05:25.075Z","repository":{"id":337332743,"uuid":"1153131858","full_name":"claylo/bito-lint","owner":"claylo","description":"Quality gate tooling for building-in-the-open artifacts","archived":false,"fork":false,"pushed_at":"2026-02-28T21:31:30.000Z","size":517,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-01T00:26:11.814Z","etag":null,"topics":["documentation","lint","mcp","mcp-server","readability","writing-quality"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/claylo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-MIT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"lovelesslabs","buy_me_a_coffee":"claylo"}},"created_at":"2026-02-08T23:50:50.000Z","updated_at":"2026-02-28T21:31:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/claylo/bito-lint","commit_stats":null,"previous_names":["claylo/bito-lint"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/claylo/bito-lint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fbito-lint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fbito-lint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fbito-lint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fbito-lint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/claylo","download_url":"https://codeload.github.com/claylo/bito-lint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fbito-lint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30164532,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T04:43:31.446Z","status":"ssl_error","status_checked_at":"2026-03-06T04:40:30.133Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","lint","mcp","mcp-server","readability","writing-quality"],"created_at":"2026-02-09T02:05:23.919Z","updated_at":"2026-03-06T06:05:25.048Z","avatar_url":"https://github.com/claylo.png","language":"Rust","funding_links":["https://github.com/sponsors/lovelesslabs","https://buymeacoffee.com/claylo"],"categories":[],"sub_categories":[],"readme":"# bito-lint\n\n[![CI](https://github.com/claylo/bito-lint/actions/workflows/ci.yml/badge.svg)](https://github.com/claylo/bito-lint/actions/workflows/ci.yml)\n[![Crates.io](https://img.shields.io/crates/v/bito-lint.svg)](https://crates.io/crates/bito-lint)\n[![docs.rs](https://docs.rs/bito-lint/badge.svg)](https://docs.rs/bito-lint)\n[![MSRV](https://img.shields.io/badge/MSRV-1.88.0-blue.svg)](https://github.com/claylo/bito-lint)\n\n**bito** = **b**uilding **i**n **t**he **o**pen.\n\nbito-lint is part of the [building-in-the-open](https://github.com/claylo/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.\n\nAI 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.\n\nbito-lint 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.\n\nThe goal: agent-generated documents that are clean enough to ship.\n\n```\n$ bito-lint analyze docs/architecture.md\n\ndocs/architecture.md\n\n  Readability: Grade 12.4, 24 sentences, 390 words\n  Grammar:     8 issues, 3 passive (12.5%)\n  Sticky:      Glue index 21.5%, 2 sticky sentences\n  Pacing:      Fast 62% / Medium 29% / Slow 8%\n  Length:      Avg 15.8 words, variety 10.0/10\n  Transitions: 0% of sentences, 0 unique\n  Overused:    \"template\" (1.3%), \"skill\" (1.1%), \"design\" (1.1%)\n  Diction:     2 vague words\n  Style:       Score 92/100, 2 adverbs, 0 hidden verbs\n```\n\n## What it checks\n\n**`analyze`** runs 18 checks in one pass:\n\n| Category | What it catches |\n|----------|----------------|\n| Readability | Flesch-Kincaid grade level — flag documents that demand too much of the reader |\n| Grammar | Passive voice, double negatives, subject-verb disagreement, missing punctuation |\n| Sticky sentences | High \"glue word\" density — sentences stuffed with *is*, *the*, *of*, *in* |\n| Pacing | Monotonous sentence rhythm — all short punches or all long slogs |\n| Sentence variety | Length distribution — a score of 1/10 means every sentence is the same length |\n| Transitions | Percentage of sentences using connective phrases — low means choppy reading |\n| Overused words | Repeated non-trivial words that make the text feel circular |\n| Repeated phrases | Bigrams and trigrams that recur too often |\n| Echoes | Same word appearing in adjacent sentences (unintentional repetition) |\n| Complex paragraphs | Paragraphs with too many ideas competing for attention |\n| Conjunction starts | Sentences opening with *But*, *And*, *So* — fine in moderation, a tic in excess |\n| Cliches | \"At the end of the day,\" \"move the needle,\" \"low-hanging fruit\" |\n| Diction | Vague words (*things*, *stuff*, *very*) that add length without meaning |\n| Sensory language | Percentage of concrete, sensory words — useful for judging descriptive writing |\n| Consistency | Mixed US/UK spelling (*color* and *colour* in the same document) |\n| Dialect enforcement | Flag spellings that violate your project's chosen dialect (en-us, en-gb, en-ca, en-au) |\n| Acronyms | Tracks acronym usage for consistency |\n| Style score | Combined metric: adverb density, hidden verbs (nominalizations), overall polish |\n\nEvery check is deterministic. No API calls, no LLM, no network. The same input produces the same output every time.\n\n**Focused checks** run individually when you need a specific gate:\n\n```bash\n# Does this handoff fit in 2,000 tokens?\n$ bito-lint tokens handoff.md --budget 2000\nPASS: handoff.md is 546 tokens (budget: 2000)\n\n# Is this user guide accessible to a general audience?\n$ bito-lint readability getting-started.md --max-grade 8\nError: getting-started.md scores 14.7 (max: 8). Simplify sentences or reduce jargon.\n\n# Does this ADR have all the sections it needs?\n$ bito-lint completeness docs/decisions/0001-my-decision.md --template adr\nPASS: docs/decisions/0001-my-decision.md (adr completeness check)\n\n# How's the grammar?\n$ bito-lint grammar changelog.md\nchangelog.md: 16 sentences analyzed\n  Passive voice: 2 instances (12.5%)\n  Grammar issues: 3\n    [MEDIUM] Sentence 3: Possible comma splice\n    [LOW] Sentence 9: Multiple consecutive spaces found\n    [MEDIUM] Sentence 16: Sentence missing terminal punctuation\n```\n\n## Installation\n\n### Homebrew (macOS and Linux)\n\n```bash\nbrew install claylo/brew/bito-lint\n```\n\n### From source\n\n```bash\ncargo install bito-lint\n```\n\n### Pre-built binaries\n\nDownload from the [releases page](https://github.com/claylo/bito-lint/releases). Binaries are available for macOS (Apple Silicon and Intel), Linux (x86_64 and ARM64), and Windows.\n\n## Usage\n\n### Config-driven linting\n\nDefine rules in your config file to map file paths to checks, then run them with one command:\n\n```bash\nbito-lint lint docs/handoff.md\nbito-lint lint --json docs/handoff.md   # structured output for CI\n```\n\nIf no rules match the file, it exits cleanly. See [docs/README.md](docs/README.md) for rules configuration, accumulation, specificity, and inline suppressions.\n\n### Full analysis\n\n```bash\nbito-lint analyze my-document.md\n```\n\nAdd `--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.\n\n### Quality gates\n\nQuality gates are pass/fail checks designed for CI, pre-commit hooks, and automation:\n\n```bash\n# Token counting with budget enforcement\nbito-lint tokens \u003cfile\u003e --budget \u003cmax\u003e\n\n# Readability with grade ceiling\nbito-lint readability \u003cfile\u003e --max-grade \u003cmax\u003e\n\n# Section completeness against a template\nbito-lint completeness \u003cfile\u003e --template \u003cname\u003e\n\n# Grammar and passive voice analysis\nbito-lint grammar \u003cfile\u003e\n```\n\nBuilt-in completeness templates: `adr`, `handoff`, `design-doc`. Define your own in a bito-lint config file.\n\nEvery command exits non-zero on failure, writes structured JSON with `--json`, and works in pipes.\n\n### Dialect enforcement\n\nSet a project dialect and bito-lint flags wrong-dialect spellings alongside mixed-spelling inconsistencies:\n\n```bash\n# Via flag\nbito-lint analyze README.md --dialect en-us\n\n# Via environment variable\nexport BITO_LINT_DIALECT=en-gb\n\n# Via config file (.bito-lint.toml)\ndialect = \"en-ca\"\n```\n\nSupported dialects: `en-us`, `en-gb`, `en-ca` (Canadian hybrid: US *-ize/-ise*, UK for the rest), `en-au`.\n\n### MCP server\n\nbito-lint includes a built-in [MCP](https://modelcontextprotocol.io/) server, so AI coding assistants can call quality gates directly during writing sessions:\n\n```json\n{\n  \"mcpServers\": {\n    \"bito-lint\": {\n      \"command\": \"bito-lint\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\nThis 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](docs/mcp-development.md) for context budget details.\n\n## Configuration\n\nDrop a config file in your project and it takes effect automatically:\n\n1. `.bito-lint.toml` (or `.yaml`, `.json`) in the current directory or any parent\n2. `bito-lint.toml` (without dot prefix) in the current directory or any parent\n3. `~/.config/bito-lint/config.toml` (user-wide defaults)\n\nCloser files win. All formats (TOML, YAML, JSON) work interchangeably.\n\nEnvironment variables override config files:\n\n- `BITO_LINT_LOG_PATH` — log file path (daily rotation appends `.YYYY-MM-DD`)\n- `BITO_LINT_LOG_DIR` — directory (file name defaults to `bito-lint.jsonl`)\n- `BITO_LINT_ENV` — environment tag (default: `dev`)\n- Config file key: `log_dir`\n\n```toml\n# .bito-lint.toml\ndialect = \"en-us\"\ntoken_budget = 2000\nmax_grade = 12.0\nlog_level = \"warn\"\n```\n\n## Shell completions\n\nIncluded in Homebrew installs and release archives. For manual setup:\n\n```bash\n# Bash\nbito-lint completions bash \u003e ~/.local/share/bash-completion/completions/bito-lint\n\n# Zsh\nbito-lint completions zsh \u003e ~/.zfunc/_bito-lint\n\n# Fish\nbito-lint completions fish \u003e ~/.config/fish/completions/bito-lint.fish\n```\n\n## Development\n\n```\ncrates/\n├── bito-lint/       # CLI binary\n└── bito-lint-core/  # Core library\n```\n\nPrerequisites: Rust 1.88.0+, [just](https://github.com/casey/just), [cargo-nextest](https://nexte.st/).\n\n```bash\njust check       # fmt + clippy + test\njust test        # tests only (nextest)\njust cov         # coverage report\n```\n\nCommit messages follow [Conventional Commits](https://www.conventionalcommits.org/). The project enforces safe Rust (`#![deny(unsafe_code)]`), clippy nursery lints, and `cargo deny` for dependency auditing.\n\n## License\n\nMIT ([LICENSE-MIT](LICENSE-MIT))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaylo%2Fbito-lint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclaylo%2Fbito-lint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaylo%2Fbito-lint/lists"}