Why codeint · How it works · Quick start · Guide · Reference · Programmatic API · Plugins · llms.txt
Coding agents write locally valid code very quickly. Each pull request can pass tests and linters while quietly adding copied blocks, redundant branches, deeper functions, and tangled imports. Over dozens of changes, that structural drag compounds until both humans and agents slow down.
codeint measures Software entropy directly from the shape of source code so you see it grow before it compounds. It ships with built-in Language plugins for TypeScript/JavaScript, Rust, PHP, Dart, and Python, plus sandboxed WebAssembly Plugins for other languages and custom Metrics.
codeint reports four Metrics side by side and never collapses them into one grade or index (ADR 0003). A single score hides regressions when one Metric improves while another worsens.
-
Erosion : share of Function mass (
cyclomatic_complexity * sqrt(source_lines)) in functions with cyclomatic complexity over 10. -
Duplication : share of source lines in Clone groups (at least 75 normalized tokens and 14 distinct normalized tokens, catching renamed copy-paste while ignoring import lists and data tables).
-
Verbosity : share of source lines in zero-false-positive Flagged lines or Clone groups.
-
Import cycles : share of modules in at least one runtime Import cycle.
-
Pre-2023 Reference ranges : every built-in language is calibrated against 20 public repositories pinned before
2023-01-01(10th to 90th percentile), so raw numbers have grounded context. -
Strict Source-set separation : every file belongs to
production,test,generated, orvendored, so fixtures and generated code never distort Production ratios. -
Budgets and Regressions : Budgets cap absolute entropy in
codeint check, whilecodeint diff <base>ratchets every pull request against its Git merge-base. -
Version-free parsing : built-in Language plugins parse the modern superset of each language family, with no language-version pins needed in
codeint.json.
codeint is written in safe Rust (#![forbid(unsafe_code)], ADR 0004) around two clean seams: Language plugins lower source files into a language-neutral Code model, and Metric plugins compute Metrics and Findings over that model.
It reads tracked files and commit history directly from Git objects without modifying your working tree, scanning laravel/framework (132k Production lines) in 0.47s and flutter/packages (434k Production lines) in 3.68s on Apple Silicon.
Third-party WebAssembly Plugins run with mandatory SHA-256 verification, zero host capabilities, and configurable memory and time caps.
Read docs/guide/philosophy-and-architecture.md for the full architecture diagram and design rationale.
10th to 90th percentile across 20 pre-2023 open-source repositories per language (ADR 0008, ADR 0010, ADR 0011, ADR 0012, ADR 0013):
| Language | Erosion | Duplication | Verbosity | Import cycles |
|---|---|---|---|---|
| TypeScript / JavaScript | 35.2% to 60.0% | 1.7% to 34.6% | 1.8% to 34.7% | 0.0% to 30.8% |
| Rust | 38.0% to 64.2% | 5.0% to 32.5% | 6.0% to 32.9% | 2.1% to 50.6% |
| PHP | 5.5% to 67.7% | 4.1% to 29.0% | 4.2% to 29.2% | 0.0% to 10.7% |
| Dart | 4.7% to 41.9% | 7.3% to 25.6% | 8.0% to 25.9% | 7.3% to 52.4% |
| Python | 14.4% to 62.4% | 1.2% to 20.1% | 1.4% to 20.4% | 0.0% to 32.1% |
See docs/guide/languages.md for per-language rules and sample repository timings.
Install the standalone binary on macOS or Linux, on Windows, or run directly with npx:
curl -fsSL https://github.com/avidianity/codeint/releases/latest/download/install.sh | bash
irm https://github.com/avidianity/codeint/releases/latest/download/install.ps1 | iex
npx codeint check
Run codeint inside any Git repository:
codeint init
codeint check
codeint diff main
codeint trend
codeint initwrites a startercodeint.jsonwith a versioned$schema.codeint checkmeasures the working tree and prints each Metric with its Findings.codeint diff maincompares the working tree against the merge-base ofmainand fails on a Regression.codeint trendprints each Metric across the latest main-line commits.
Or call codeint programmatically from JavaScript/TypeScript (npm install codeint) or Rust ( codeint-cli):
import { check, diff } from "codeint";
const report = await check();
const prDiff = await diff({ base: "main" });
- Guide : modular walkthroughs forPhilosophy and Architecture ,Getting Started ,Configuration (
codeint.json) ,Built-in Languages , andCI and GitHub Actions . - Reference : tested reference for every command, flag, exit code, report format (
toon,json,sarif,markdown), andcodeint.jsonkey. - Programmatic API : JavaScript/TypeScript SDK and Rust library API.
- Plugins : build, hash, declare, and test external WebAssembly Language and Metric plugins.
- Glossary : canonical definitions of every domain term on this page.
- llms.txt : compact documentation index for coding agents and LLM tools.
You need Rust through rustup (rust-toolchain.toml), Node.js 24 and npm (package.json), and gitleaks plus lychee on your PATH.
npm ci
npx lefthook install
cargo test --workspace --locked
Agents and people follow the same rules: start with .rules. The repository checks are listed in docs/checks/README.md.