One linter and formatter for every language in your repository.
polylint is a small binary, poly, driven by one poly.toml. It fetches the engine each language in your
repository needs — ruff, oxc, biome, mago, sqruff and more, as signed, checksum-verified components — uses the
canonical tools you already have (rustfmt, gofmt, shellcheck), and runs ecosystem linters such as
golangci-lint, hadolint, actionlint and buf as built-in recipes. Everything reports through one format, one exit
code and one cache.
40+ languages and file formats with a dedicated tool · tree-sitter formatting for 300+ more · git hooks and commit linting · monorepo-aware config · MCP server and agent plugins
How it works · Quick start · Languages · Why polylint · Install · Docs
flowchart LR
R["your repository"] --> C["poly core<br/>discover · plan · cache · hooks"]
C -->|"per language, on demand"| K["signed components<br/>ruff · oxc · biome · mago · sqruff · rubyfmt · shfmt …"]
C -->|"if installed"| H["host tools<br/>rustfmt · gofmt · shellcheck · zig fmt …"]
C -->|"opt-in"| P["recipes<br/>golangci-lint · hadolint · buf · checkstyle …"]
C -->|"everything else"| T["tree-sitter tier<br/>300+ grammars"]
K & H & P & T --> O["one report · one exit code<br/>pretty · JSON · TOON · MCP"]
- Components — the engines (Rust crates, plus a Go sidecar for shell and Go), signed and pinned to your poly version,
downloaded once per language and cached. No Python, Node or Ruby runtime is needed for them. A needed component
that cannot be installed is exit
2(or a counted skip, if you ask for that), never a silent downgrade. - Host tools — a language's canonical CLI when it is on
PATH:rustfmt,gofmtandshellcheckon by default,zig fmt,google-java-format,ktfmt,swift-format,dart format,gleam formatandstyleropt-in. Absent, the language falls through to tree-sitter formatting with a notice. - Recipes — ecosystem tools enabled with
[tools.<name>], run batched, with findings parsed per line. Most can download a checksummed release (install = "auto"); tools that need the JVM, Node or Python use the runtime already on your machine. polylint never bundles a runtime. - Tree-sitter tier — best-effort formatting for languages with nothing better. Grammars are fetched on demand.
- On every language — a code-quality metrics engine and a 42-rule ast-grep pack, at warning severity.
- Never silent — a file nothing could check is counted and named;
--deny-skipsmakes that a CI failure.
Files are discovered once (respecting .gitignore) and processed in parallel. The result cache is keyed by file
bytes, engine, engine version and resolved config, so an upgrade or a config change invalidates exactly what it
affects. --debug prints per-file engine timing and cache hits, and --timings prints per-phase wall time and a
per-engine table.
curl -fsSL https://raw.githubusercontent.com/polylint/polylint/main/install.sh | sh
poly lint # lint everything; the first run fetches the engines this repository needs
poly fmt --fix # format everything
poly hooks install # run both on every commit, without pre-commit or lefthookThe first poly lint downloads the components for the languages it finds (for a Python and TypeScript repository,
python and web among them), verifies each against the signed lock embedded in the binary, and caches it. Later
runs use the cache. The Linux musl build has every engine linked in and downloads nothing; see
Installation.
$ poly lint
./app.py
warning ruff T201 5:5 `print` found
warning ruff ANN201 4:5 Missing return type annotation for public function `main`
error ruff F401 1:8 `os` imported but unused
3 issues found.
2 files linted
1 issue fixable with the `--fix` optionpoly fmt without --fix is a dry run. Exit codes are a contract: 0 clean, 1 findings (or, for a poly fmt
dry run, files that would change), 2 the run verified less than it claims. poly fmt --fix exits 0 after
rewriting; add --exit-nonzero-on-fix for a CI step that must fail when the tree was not already formatted.
How it runs: component <name> is a signed download (linked in on the bundled build); host is a CLI used
when installed; recipe is an opt-in [tools.<name>] integration (↓ = polylint can download a pinned release on
macOS and Linux; RT = needs a host runtime); ts is the tree-sitter tier. Q = quality-tier lint, AG =
built-in ast-grep rules.
| Language or files | Lint | Format | How it runs |
|---|---|---|---|
| Python | ruff; ty or pyrefly (opt-in type check) · Q · AG | ruff | component python (pyrefly) |
| JavaScript, TypeScript, JSX, TSX | oxlint; skif (opt-in workspace check); tsrs (opt-in, experimental type check) · Q | oxc formatter | component web (tsrs) |
| JSON, JSONC | oxc parse errors | oxc formatter | component web |
| YAML | serde_yaml | oxc_formatter_yaml | component web |
| TOML | taplo | oxc_formatter_toml (taplo on request) | component web |
| Markdown, MDX | rumdl; adrlint (opt-in, ADRs) | oxc_formatter_markdown | component web |
| CSS, SCSS | biome | oxc_formatter_css (malva on request) | components web, biome |
| Less | — | oxc_formatter_css (malva on request) | component web |
| HTML, Vue, Svelte, Astro, Angular, XML, Jinja | — | markup_fmt | component web |
| GraphQL | graphql parse errors, biome | pretty_graphql | components misc, biome |
| SQL | sqruff | sqruff | component sql |
| PHP | mago | mago | component php |
| Ruby | Q · AG | rubyfmt | component ruby |
| Typst | — | typstyle | component misc |
| LaTeX | — | tex-fmt | component misc |
| Lua | selene | StyLua | component lua |
| Nix | — | alejandra | component nix |
| HCL, Terraform | hcl-edit; tflint (recipe ↓) | hclwrite port; tofu (recipe ↓), terraform (recipe) | component misc |
| Dockerfile | built-in rules; hadolint (recipe ↓) | — | component misc |
.env, INI |
dotenv, ini | — | component misc |
| Shell | shellcheck (host, default-on) | shfmt | component sh (Go sidecar) |
| Go | golangci-lint (recipe ↓) · Q · AG | gofumpt and goimports grouping (component go, Go sidecar; host gofmt in a bundled build); golangci-lint (recipe ↓) |
component go, recipe |
| Rust | cargo clippy, sort, machete, deny (whole-project phase) · Q · AG | rustfmt (host, default-on) | host |
| Java | checkstyle (recipe ↓, RT: JRE) · Q · AG | google-java-format (host, opt-in); palantir-java-format (recipe ↓, native) | host, recipe |
| Kotlin | Q · AG | ktfmt (host, opt-in) | host |
| Swift | AG | swift-format (host, opt-in) | host |
| Zig, Dart, Gleam | — | zig fmt, dart format, gleam format (host, opt-in) | host |
| R | jarl · Q | air (no R install); styler (host, opt-in) | component r |
| Groovy | npm-groovy-lint (recipe, RT: Node) | npm-groovy-lint | recipe |
| Protobuf | buf (recipe ↓) | buf | recipe |
| Starlark, Bazel | buildifier (recipe ↓) | buildifier | recipe |
| GitHub Actions workflows | actionlint (recipe ↓); gau (recipe) | — | recipe |
| Helm charts | helm, helm-template (recipe ↓) | — | recipe |
pyproject.toml |
— | pyproject-fmt (recipe, RT: Python) | recipe |
| C, C++, C# | Q (C# also AG) | tree-sitter | ts |
| Elixir | AG | tree-sitter | ts |
| 300+ other grammars | — | tree-sitter, best effort | ts |
| Any text | typos (opt-in) | — | component typos |
| Markdown prose, code comments | harper (opt-in, grammar and style) | — | component prose |
| Any language | uncomment (opt-in) | — | component uncomment |
348 more tools from the embedded mdsf catalog can be enabled per tool, with file-level verdicts. Recipe downloads are not available on Windows; install the tool yourself there. Full reference: Languages and engines and Toolchains, runtimes and recipes.
| If you use… | What changes |
|---|---|
| ruff, oxlint, biome, … individually | The same engines (ruff, oxc, biome and mago are linked as libraries), one config, one report format, one cache and one exit-code contract. No per-ecosystem toolchain for the built-in engines. |
| pre-commit or lefthook | poly hooks runs from poly.toml, checks a snapshot of the staged index rather than your worktree, and needs no Python environment. poly migrate converts .pre-commit-config.yaml and lefthook.yml. |
| MegaLinter or Super-Linter | No Docker image: a native binary fast enough for local runs and git hooks as well as CI, with a content-hash cache and per-line findings from parsed reports. Trade-off: they wrap more linters. |
| dprint | polylint lints as well as formats. |
Real recordings — vhs runs each command live. Tapes are in docs/media/tapes/.
Kubernetes: 31,303 files in one run.
Django is not a Python repo — it is Python, JavaScript, CSS, HTML, TOML, YAML and Markdown. One tool, one config, one pass.
Every report has a machine-readable form. --format toon is compact enough to hand to an agent; --format json
is there when you want a document to parse.
An agent can skip the terminal entirely. poly mcp speaks MCP over stdio and advertises fourteen tools that
mirror the CLI.
curl -fsSL https://raw.githubusercontent.com/polylint/polylint/main/install.sh | sh # macOS, Linux
brew install polylint/tap/polylint
pnpm add --global @polylint/polylint
pip install polylint
cargo binstall --git https://github.com/polylint/polylint poly-cliirm https://raw.githubusercontent.com/polylint/polylint/main/install.ps1 | iex
scoop bucket add polylint https://github.com/polylint/scoop-bucket
scoop install polyThe installers verify the archive against sha256sums.txt; set POLY_VERSION=0.35.0 to pin a release. Homebrew is
a rolling get-latest formula. The npm and PyPI packages are named polylint because poly is taken on both
registries; the command is poly on every channel, with polylint as an alias. Details:
docs/INSTALL-PACKAGES.md.
| Target | Build |
|---|---|
| Linux x86_64 (glibc), Linux aarch64 (glibc) | core |
| Linux x86_64 (musl) | bundled |
| macOS aarch64 (Apple silicon) | core |
| Windows x86_64 | core |
Intel macOS is not supported from the release after 0.34.0 (build from source); Windows arm64 and Linux musl aarch64 have no release binary.
A core build is under 22 MiB (16.5 MB on macOS arm64) and downloads engine components on first use. The bundled build links every engine and the MCP server in and downloads nothing. For controlled networks:
poly components sync . # install what this directory needs, ahead of time
poly components import <archive> # seed an air-gapped host
poly --offline lint . # forbid every download (also POLY_OFFLINE=1)POLY_COMPONENT_MIRROR points downloads at an internal mirror. See
Components and offline use.
- uses: actions/checkout@v4
- uses: polylint/polylint@v0
with:
version: from-config # the release that `required_version` in poly.toml allows
components: auto # pre-install and cache the components this repository needs
- run: poly fmt .
- run: poly lint --deny-skips .A fresh CI checkout is untrusted: add env: POLY_TRUST: "1" to the job when poly.toml sets
gated keys such as [hooks] jobs or [tools.<name>]
arguments. See ACTION_USAGE.md for every input.
polylint works with no config. When you want one:
# poly.toml
[discovery]
exclude = ["vendor/**"]
[engines.ruff]
extend_select = ["D"]
[tools.golangci-lint]
enabled = true
[hooks]
stages = ["pre-commit", "commit-msg"]
[hooks.builtin]
lint = true
fmt = true
commit = { stages = ["commit-msg"] }poly migratereads existing ruff, taplo, markdownlint and typos configs,.pre-commit-config.yamlandlefthook.yml, and folds what it can honor intopoly.toml(dry run by default;--writeapplies).- Nested
poly.tomlfiles cascade in a monorepo;poly.local.tomllayers local overrides;extendsshares a baseline across repositories;poly config showprints the effective result. - Unknown keys, sections and wrongly typed values are reported as warnings, never silently ignored.
- Keys that make poly run a program —
[tools.<name>]binpaths,env, extra arguments and download URLs, whole-project[hooks]jobs,[cache] dir— are ignored in a repository you have not trusted, with one note naming them. Runpoly trustonce per clone (poly trust --showlists what it would allow), or setPOLY_TRUST=1in CI. See Repository trust.
poly hooks install wires lint, format, file-safety and Conventional Commits checks into git from [hooks] in
poly.toml. Hooks run against a snapshot of the staged index, so unstaged edits neither hide nor cause failures.
poly commit lints and cleans commit messages. poly hooks install also records the repository as
trusted; poly hooks run and the git hooks refuse to run in
an untrusted repository, and after a pull that changes a gated key the next commit stops until you run poly trust
again. See Git hooks.
poly mcp is a stdio MCP server with fourteen tools that mirror the CLI (lint, format_check, lint_fix,
format_write, components, workspace_lint, …). Every result identifies the binary that answered and separates
checked, skipped and errored files, so an agent can gate on what was actually verified.
/plugin marketplace add polylint/polylint
/plugin install poly@poly
Any other MCP client runs it as { "command": "poly", "args": ["mcp"] }. Plugins ship for Claude, Codex, Cursor,
Gemini, Kimi, OpenCode, Factory, Hermes, Pi, Agent Plugins and Copilot, and assume poly is already on PATH;
see plugin/README.md and
Agents and MCP.
What runs out of the box
| Engine | What it enables by default |
|---|---|
| ruff (Python) | 22 selector groups: ruff's own F, E4, E7, E9, plus W6, I, UP, B, ANN, SIM, C4, RET, FURB, PERF, TRY, BLE, S110, C90, PLR, T20, TC, PTH, RUF, ARG. E1/E2/E3/W1/W2/W3 stay off because the formatter owns them, and seven noisy members are turned back off: B008, RUF100, ANN002, ANN003, ARG002, PLR2004, TRY003. Line length 120, docstring code formatted at width 120. |
| oxlint (JS/TS) | oxlint's own default is correctness only. poly adds suspicious, pedantic, complexity, typescript/no-explicit-any, typescript/no-non-null-assertion and no-console, all at warning. restriction, style and nursery stay off; no-underscore-dangle, max-lines-per-function, max-lines and max-classes-per-file are turned back off. |
| mago (PHP) | PHP 8.4, with six maintainability metrics downgraded from error to warning: cyclomatic-complexity (15), excessive-parameter-list (5), too-many-methods (10), too-many-properties (10), too-many-enum-cases (20), kan-defect (1). |
| rumdl (Markdown) | Five rumdl-proprietary stylistic rules disabled, plus four more for MDX. Line length 120. |
| biome (CSS/SCSS, GraphQL) | The correctness and suspicious rule groups. Accessibility, style, complexity, performance and security are opt-in. |
Two cross-cutting lint tiers are on by default for every language, and three more are opt-in:
- The code-quality engine (on) — tree-sitter metric rules, listed below.
- The built-in ast-grep pack (on) — 42 rules across C#, Elixir, Go, Java, Kotlin, Python, Ruby, Rust and Swift.
16 are on by default; the other 26 ship
severity: offand are one config line away. Your own rules under[engines.astgrep] rule_dirssit above the pack — a rule with the sameidreplaces the built-in one. typos(opt-in) — spell-checks identifiers, comments and strings:[engines.typos] enabled = true.uncomment(opt-in) — comment removal, built on uncomment.harper(opt-in) — grammar and style checks on Markdown and on the comments of every language with a loaded grammar:[engines.harper] enabled = true. Spell-checking stays off unless selected.
| Quality rule | Default |
|---|---|
file-too-long |
1000 lines |
function-too-long |
80 lines |
type-too-long |
300 lines |
too-many-parameters |
6 |
nesting-too-deep |
4 |
cyclomatic-complexity |
20 |
lazy-ignore |
on |
magic-number |
opt-in — allows −1, 0, 1, 2, 10, 100 |
law-of-demeter |
opt-in — chain depth 3 |
uncollected-test-file |
on for Python, Go, Ruby — a test name the runner will not collect |
The quality engine never duplicates an engine rule: where ruff or oxlint already covers a metric, it defers. It counts as lint coverage only for languages whose control flow it can model — Python, Rust, Go, JavaScript, JSX, TypeScript, TSX, Java, Kotlin, C, C++, C# and Ruby. Everything these tiers report is warning severity, and warnings alone do not fail a run, so turning polylint on does not redden an unconfigured CI.
adrlint is an opt-in MADR engine for numbered ADR files (NNNN-*.md),
enabled with [engines.adrlint] enabled = true; see
ADR 0037 and ADR 0041.
poly adr new <title> creates the next numbered record, and poly adr lock and
poly adr unlock <file> --reason <text> maintain adrlint.lock, with no standalone adrlint install.
Release build, Apple Silicon, cold cache (--no-cache), best of three runs on an idle machine.
poly lint --workspace never and poly fmt over the whole repository, counting the files
poly actually inspected. These are poly's own numbers — not a comparison against ruff,
oxlint, biome or anything else; no such benchmark was run.
| Project | poly lint |
Findings | Peak RSS | poly fmt |
|---|---|---|---|---|
| Django | 3,113 files in 0.82s | 66,839 | 0.21 GB | 5,539 files in 0.30s |
| home-assistant | 25,443 files in 3.5s | 376,829 | 0.48 GB | 25,559 files in 1.2s |
| Kubernetes | 21,657 files in 6.8s | 41,576 | 0.40 GB | 21,824 files in 12.9s |
| prettier | 7,057 files in 1.9s | 19,373 | 0.40 GB | 7,450 files in 0.44s |
| TypeScript | 32,606 files in 13.3s | 179,586 | 0.52 GB | 40,012 files in 4.0s |
Kubernetes is the one repository where formatting costs more than linting: its Go files go
through the host gofmt, one subprocess per file, and ~20,000 process spawns dominate the run.
Repeat runs are faster — Django re-lints in 0.71s warm against 0.82s cold: a cache hit skips the engine entirely, and everything else is split across cores.
- Quickstart — install, first run, first config.
- Adopting polylint in a polyglot repo — migration, rollout, CI.
- Configuration — every key, rule selection, inline suppression, monorepo cascading, shared and remote config.
- Toolchains, runtimes and recipes — host tools, recipe downloads, host runtimes, reproducibility.
- Components and offline use — bundled and core builds,
[components], mirrors, air-gapped hosts. - Git hooks —
poly hooks install, builtin hooks, staged isolation, timeouts, concurrency, caching. - Repository trust — which config keys run programs, what
poly trustrecords, CI and MCP. - Migrating to the v2 config schema — the
poly.tomlv2 schema and the removed CLI flags. - CLI reference — every subcommand and flag, and the exit-code contract.
Keep changes small and test-backed. A new or changed engine needs known-bad and known-unformatted fixtures under
crates/poly-core/tests/, and must preserve the uniform Engine boundary. Before committing:
poly hooks install # wires lint/format/cargo checks into git; they run on every commit
cargo test --workspace --no-fail-fastFor anything touching the runner, an engine, or the rule pack, also run the hardening harness. poly's
own fixtures are small and chosen to exercise a known path; the harness runs poly over real
third-party trees and checks the things fixtures cannot — that no file errored, that formatting
converges in two passes, that the cache never serves a different answer than a cold run, and that no
language poly claims to lint reports no lint rules for it:
mise run harden # pinned third-party repositories
mise run harden:local # the sibling working trees next door, read-only
mise run harden:generated # machine-generated code (corpus C)It also reports per-rule finding counts per repository, which is how a pack rule earns a default
severity. See docs/harden-corpus.md for what each corpus is allowed to
assert, and why a count needs a pinned input while an invariant does not.
For anything touching an engine component, run the component dev loop. components:dev builds the
named components (sql when none is named) in debug, packages them unsigned and writes a file://
lock under target/components/. components:parity then tests poly-core with engine-sql off and
the dev-lock feature on, so sql can only come from the component: the lint and format output must
match the in-process snapshots byte for byte, and a component whose hash differs from its lock must
fail the run:
mise run components:dev # build sql (or: mise run components:dev web ruby) and write the dev lock
mise run components:parity # components-mode tests; fails, never skips, if the lock is missingdev-lock makes poly read the lock named by POLY_COMPONENT_DEV_LOCK. It is for development only,
and the release workflow fails a binary that was built with it.
polylint is part of polylint, high-performance Rust linters and formatters built for agentic workflows. Sibling tools:
| Tool | What it does |
|---|---|
| skif | JS/TS dependency, manifest and dead-code linter for npm, pnpm, yarn and bun workspaces |
| adrlint | Linter for MADR architecture decision records |
| uncomment | Tree-sitter comment removal and linting |
poly embeds all three as opt-in engines. Install any of them from the Homebrew tap (brew tap polylint/tap) or
the Scoop bucket (scoop bucket add polylint https://github.com/polylint/scoop-bucket).
MIT - see LICENSE.