Find your next open-source project

Search by name, purpose, or keyword — or paste a GitHub repository URL

brianbell-x/codehygiene

Developer Tools

A tiny NumPy neural scorer that rates code readability and flags style issues across 11 languages.

123
5
Python
1 day old

What it is

codehygiene scores how readable and maintainable source code looks, rather than whether it is syntactically valid. Conventional linters can pass a file that is still cryptic, over-nested, or padded with noisy comments. This project uses a small 574K-parameter 1.58-bit ternary network implemented in pure NumPy, with no regexes, tokenizers, or AST parsers, to produce hygiene scores for Python, C, C++, Rust, Go, Zig, JavaScript, TypeScript, Java, C#, and Lua.

A forward pass returns an overall 0.0–1.0 score, six sub-scores (flatness, naming, simplicity, comments, error_handling, layout), a style archetype (minimal, clean, enterprise, dense, or slop), and line-level squiggle diagnostics such as deep_nesting, noisy_comment, and swallowed_error.

The weights are not trained with gradient descent. They are compiled from explicit mathematical circuits in compile.py into ternary {-1, 0, +1} matrices stored in codehygiene/weights.npz (about 12.97 KiB), which keeps inference around 10 ms on CPU for small inputs.

Quickstart

Install the CLI with uvx or pip, then point it at a directory:

uvx --from git+https://github.com/brianbell-x/codehygiene codehygiene .

Or install it first:

pip install git+https://github.com/brianbell-x/codehygiene
codehygiene src/

Useful modes include --check to exit nonzero when a squiggle reaches the threshold (suitable for CI), --json for structured output, and -t to adjust the squiggle probability threshold. Piped stdin is also accepted:

codehygiene path/to/file.py --json
cat snippet.rs | codehygiene --json

To use it as an agent skill with Claude Code, Codex, Cursor, Antigravity, or Copilot, install through npx skills:

npx skills add brianbell-x/codehygiene
npx skills update codehygiene -y

There is also a zero-backend browser demo that downloads and runs the weights client-side against a pasted snippet or a public GitHub repository. To run it locally, serve the bundled docs directory:

python3 -m http.server 8123 -d docs

From Python, codehygiene.score(code) returns the full result, codehygiene.lint(code, threshold=0.55) returns squiggles, and codehygiene.rl_reward(code, tests_passed=True, weight=0.25) produces an RL reward that is zero whenever tests fail, to discourage reward-hacking with clean-looking broken code.

Constraints

The project only covers the 11 listed languages; other file types are not scored. It judges style and hygiene rather than correctness, so it does not replace tests or type checking. Scores are calibrated on the project's own production canon and diagnostic suites, so thresholds are heuristics that may need tuning for your codebase; -t handles that. The README declares no license. By default the CLI checks public release metadata at most once every 12 hours and prints a one-line stderr notice about updates; this can be disabled with --no-update-check or CODEHYGIENE_NO_UPDATE_CHECK=1, and it is skipped in CI. The browser demo requires a network connection to fetch a public repository when scoring a URL, though snippets are processed locally.

HotRepo's take

On the HotRepo new-project board for 2026-11-16, the repository recorded 118 stars and 18 added over roughly 1.5 hours, with the observed Star curve rising from 100 to 118 during the same window. That is an early snapshot from a young repository, so it says more about immediate attention than about adoption. The technical pitch is unusually specific for that stage: pure-NumPy inference, ternary weights, a reproducible compile step, a browser demo, and an agent-corpus benchmark comparing before and after refactoring of four GPT-OSS 120B-built apps. Readers evaluating it should weigh those details themselves, since the project's own benchmarks are the main evidence for its scoring behavior.

Written by AI from the project's README, updated . The project's own docs are the source of truth.