{ "markdown": "\n
\n\n\"poly\"\n\n**One binary. ~30 languages. No toolchain to install.**\n\npoly lints and formats whole repositories in seconds: curated Rust backends for the languages\nthat matter, a tree-sitter fallback for everything else, and a Claude/Codex plugin plus an MCP\nserver so agents can drive it directly instead of shelling out.\n\nLint + format · one `poly.toml` · pure Rust, zero deps · blake3 cache + rayon parallelism · git\nhooks & commit checks · MCP + Claude/Codex plugin\n\n[![CI](https://img.shields.io/github/actions/workflow/status/Goldziher/poly/ci.yaml?style=flat-square&cacheSeconds=300)](https://github.com/Goldziher/poly/actions/workflows/ci.yaml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-goldziher.github.io%2Fpoly-blue?style=flat-square)](https://goldziher.github.io/poly)\n\n[Install](#installation) · [What You Get](#what-you-get) · [What Runs Out of the Box](#what-runs-out-of-the-box) ·\n[AI Agents & MCP](#ai-agents--mcp) · [Performance](#performance) ·\n[Docs](https://goldziher.github.io/poly) · [Contributing](#contributing)\n\n
\n\n---\n\n## What You Get\n\n\n\n| Capability | What it does |\n|---|---|\n| **Fast on real repos** | Lints Django in 0.82s and home-assistant's 25,000 files in 3.5s, cold cache; see [Performance](#performance). |\n| **One binary, no toolchain** | Compiled-in Rust backends for Python, JavaScript, TypeScript, JSX, TSX, JSON, YAML, TOML, Markdown, MDX, CSS, SCSS, Less, HTML, Vue, Svelte, Astro, Angular, XML, PHP, Ruby, SQL, GraphQL, Nix, HCL, Dockerfile, INI and `.env`. Go, Rust, Zig, Java, Kotlin, Swift, Dart, R, Gleam and shell use their own toolchain when it is installed, and a tree-sitter tier covers everything else. No Node, Python, or Ruby runtime needed. See the [language table](https://goldziher.github.io/poly/reference/backends/). |\n| **Built for agents** | A Claude/Codex plugin and a stdio MCP server ship in the box — an agent calls poly's tools directly instead of shelling out and parsing text. See [AI Agents & MCP](#ai-agents--mcp). |\n| **One config** | `poly.toml` drives linting, formatting, git hooks, and commit-message policy. |\n| **Cache + parallelism** | A blake3 content-hash cache skips unchanged work; rayon parallelizes the rest across cores. |\n| **Git hooks & commit checks** | `poly hooks install` wires lint, format, and Conventional-Commit checks into git — no external hook framework. |\n| **Two lint tiers on every language** | A code-quality metrics engine and a built-in 26-rule ast-grep pack (13 rules on by default) run on top of the backends above, at warning severity so they never redden an unconfigured CI. |\n| **Simple distribution** | Prebuilt binaries via a shell/PowerShell installer, a GitHub Action, Homebrew, Scoop, npm, and PyPI. |\n\n\n\n---\n\n## Installation\n\n### Quick install\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/Goldziher/poly/main/install.sh | sh\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/Goldziher/poly/main/install.ps1 | iex\n```\n\nBoth detect the platform, download the matching release archive, and verify it against\n`sha256sums.txt`. Set `POLY_VERSION=0.23.1` to pin an exact release.\n\n### GitHub Actions\n\n```yaml\n- uses: Goldziher/poly@v0\n with:\n version: v0.23.1 # omit for the latest release\n```\n\nForwards to `install.sh` and caches the installed binary by version and platform. See\n[`ACTION_USAGE.md`](ACTION_USAGE.md) for the full input/output reference.\n\n### Package managers\n\n```sh\nbrew install Goldziher/tap/poly\n```\n\n```powershell\nscoop bucket add goldziher https://github.com/Goldziher/scoop-bucket\nscoop install poly\n```\n\nHomebrew's tap is a single rolling formula with no versioned alias yet — treat it as a\nget-latest channel and use the installer script or the GitHub Action where a pinned version\nmatters. `cargo binstall --git https://github.com/Goldziher/poly poly-cli` also works, resolving\nthe same GitHub release archives.\n\n### npm and PyPI\n\n```sh\nnpm i -g @goldziher/polylint\npip install polylint\n```\n\nBoth install the same prebuilt `poly` binary. The package is named `polylint` (the unscoped\n`poly` name belongs to unrelated projects on both registries), but **the executable is `poly`\non every channel** — `polylint` also works everywhere as an alias for the same binary. Full\nper-platform detail in [docs/INSTALL-PACKAGES.md](docs/INSTALL-PACKAGES.md).\n\n### As an agent plugin\n\npoly ships its own Claude/Codex plugin, registering `poly mcp` as a stdio server plus 5 skills\nand 2 slash commands (`/poly-check`, `/poly-fix`):\n\n```text\n/plugin marketplace add Goldziher/poly\n/plugin install poly@poly\n```\n\nCodex: add the `Goldziher/poly` marketplace through your client's plugin manager (manifest at\n`.codex-plugin/plugin.json`). The plugin assumes `poly` is already on `PATH` — it does not\nbundle the binary — and its version tracks the `poly` binary version lock-step. See\n[AI Agents & MCP](#ai-agents--mcp).\n\n### As an MCP server\n\nAny MCP-capable client can run poly directly:\n\n```json\n{\n \"mcpServers\": {\n \"poly\": { \"command\": \"poly\", \"args\": [\"mcp\"] }\n }\n}\n```\n\n---\n\n## Quickstart\n\n```console\n$ poly lint\n./app.py\n warning ruff T201 5:5 `print` found\n warning ruff ANN201 4:5 Missing return type annotation for public function `main`\n error ruff F401 1:8 `os` imported but unused\n\n3 issues found.\n 2 files linted\n 1 issue fixable with the `--fix` option\n\n$ poly fmt --check\nwould reformat ./src/main.rs\n\n1 file will change.\n 2 files checked\n\n$ poly fmt --fix\nreformatted ./src/main.rs\n\n1 file reformatted.\n 2 files checked\n\n$ poly hooks install\n✓ Installed 2 git hooks in .git/hooks\n › commit-msg\n › pre-commit\n```\n\n`poly fmt` is a dry run by default (CI-friendly); add `--fix` to write changes, and `poly lint\n--fix` to apply lint autofixes. `poly hooks install` wires the git hooks once — lint, format, and\ncommit checks then run on every `git commit`.\n\nExit codes are a contract: `0` is clean, `2` means the run verified less than it claims, and `1`\nmeans findings — which for `poly fmt --fix` reports *that files were rewritten*, so a script\nrunning it in fix mode should treat `1` as success. Add `-q` to trim the per-file detail on a\nlarge repository; the summary keeps every count and reason.\n\n---\n\n## Demos\n\nReal recordings, not mockups — `vhs` runs each command live, so the timings on screen are the\ntimings you get. Tapes are in [`docs/media/tapes/`](docs/media/tapes/).\n\n**Kubernetes: 31,303 files, one binary, no Go toolchain.**\n\n![poly linting the Kubernetes repository](docs/media/scale.gif)\n\n**Django is not a Python repo** — it is Python, JavaScript, CSS, HTML, TOML, YAML and Markdown.\nOne tool, one config, one pass.\n\n![poly formatting and linting Django](docs/media/polyglot.gif)\n\n**Every report has a machine-readable form.** `--format toon` is compact enough to hand to an\nagent without burning its context; `--format json` is there when you want a document to parse.\n\n![poly emitting TOON output](docs/media/toon.gif)\n\n**And an agent can skip the terminal entirely.** `poly mcp` speaks MCP over stdio and advertises\nthe same eleven tools the CLI exposes.\n\n![the poly MCP server listing its tools](docs/media/agent.gif)\n\n---\n\n## How It Works\n\npoly discovers files once (respecting `.gitignore`), plans the engine list once per language, and runs the per-file\nwork in parallel on a rayon pool. Every backend — a linked-in Rust crate, the tree-sitter tier, or a wrapped CLI —\nreturns the same `Diagnostic` and `FormatOutput` shapes, so reporting, caching, and MCP output stay uniform.\n\n```mermaid\nflowchart LR\n A[\"paths\"]\n B[\"discover
gitignore aware\"]\n C[\"plan engines
per language\"]\n D[\"rayon file loop\"]\n E[\"blake3 cache\"]\n F[\"lint / format
reports\"]\n A --> B --> C --> D\n D <-->|hit / miss| E\n D --> F\n```\n\nThe default path needs no Python, Node, Go, or JVM — the backends are Rust crates compiled into the binary, and a\nlanguage without a dedicated backend falls through to a tree-sitter generic tier that is still pure Rust. The result\ncache is keyed by file bytes, engine name, engine version, and resolved engine config, so a tool upgrade or a config\nchange invalidates exactly the entries it affects. `--debug` prints per-file engine timing and cache hit/miss data.\n\n---\n\n## What Runs Out of the Box\n\npoly is useful with an empty `poly.toml`. This is what a run with no configuration actually does; anything opt-in is\nmarked as such.\n\n\n\n| Backend | What it enables by default |\n|---|---|\n| **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. |\n| **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. |\n| **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). |\n| **rumdl** (Markdown) | Five rumdl-proprietary stylistic rules disabled, plus four more for MDX. Line length 120. |\n| **biome** (CSS/SCSS, GraphQL) | The `correctness` and `suspicious` rule groups. Accessibility, style, complexity, performance and security are opt-in. |\n\n\n\n### Three tiers that run on every language\n\n- **`typos`** — spell-checks identifiers, comments and strings. Always on; it has no enable key.\n- **The code-quality engine** — tree-sitter metric rules, listed below.\n- **The built-in ast-grep pack** — 26 rules across C#, Elixir, Go, Java, Kotlin, Python, Ruby, Rust and Swift. **13\n are on by default**; the other 13 ship `severity: off` and are one config line away. Your own rules under\n `[rules] dirs` sit above the pack — a rule with the same `id` replaces the built-in one outright.\n\nA fourth cross-cutting engine, `uncomment` (comment removal), is off by default.\n\n| Quality rule | Default |\n|---|---|\n| `file-too-long` | 1000 lines |\n| `function-too-long` | 80 lines |\n| `type-too-long` | 300 lines |\n| `too-many-parameters` | 6 |\n| `nesting-too-deep` | 4 |\n| `cyclomatic-complexity` | 20 |\n| `lazy-ignore` | on |\n| `magic-number` | opt-in — allows −1, 0, 1, 2, 10, 100 |\n| `law-of-demeter` | opt-in — chain depth 3 |\n\nThe quality engine never duplicates a backend rule: where ruff or oxlint already covers a metric, it defers. It counts\nas lint *coverage* only for languages whose control flow it can model — Python, Rust, Go, JavaScript, JSX, TypeScript,\nTSX, Java, Kotlin, C, C++, C# and Ruby — while other languages still get the line-count rules.\n\nEverything these three tiers report is **warning** severity, and warnings alone do not fail a run, so turning poly on\ndoes not redden an unconfigured CI.\n\n### Native toolchain CLIs\n\n`gofmt`, `rustfmt` and `shellcheck` run automatically when found on `PATH`; `shellcheck` is the only one of the three\nthat lints. `zig fmt`, `shfmt`, `google-java-format`, `ktfmt`, `styler` (R), `swift-format`, `dart format` and\n`gleam format` are opt-in. When a tool is absent the language falls through to the tree-sitter tier, so the\nzero-dependency promise holds either way.\n\n---\n\n## Backend Coverage\n\n\n\n| Language | Backend | Lint | Format |\n|---|---|---:|---:|\n| Python | ruff | yes | yes |\n| JavaScript / TypeScript / JSX / TSX / JSON | oxc | yes | yes |\n| TOML | taplo | yes | yes |\n| YAML | saphyr + pretty_yaml | yes | yes |\n| Markdown / MDX | rumdl | yes | yes |\n| SQL | sqruff | yes | yes |\n| CSS / SCSS | malva + biome | yes | yes |\n| Less | malva | no | yes |\n| GraphQL | graphql + biome | yes | yes |\n| PHP | mago | yes | yes |\n| HCL / Terraform | hcl | yes | yes |\n| HTML / Vue / Svelte / Astro / XML | markup_fmt | no | yes |\n| Dockerfile | dockerfile | yes | no |\n| `.env` | dotenv | yes | no |\n| INI | ini | yes | no |\n| Ruby | rubyfmt | no | yes |\n| Nix | alejandra | no | yes |\n| Go | `gofmt`, automatic when installed | no | yes |\n| Rust | `rustfmt`, automatic when installed | no | yes |\n| Shell | `shellcheck` automatic, `shfmt` opt-in | yes | opt-in |\n| Zig / Java / Kotlin / R / Swift / Dart / Gleam | first-party CLI, opt-in | no | opt-in |\n| Everything else identified | tree-sitter generic tier | no | best effort |\n\n\n\nThe `Lint` column is the language's own backend; the three cross-cutting tiers add findings on top, including where\nthat column says `no`. Beyond this table, an opt-in catalog of 348 tools across 175 languages covers the long tail.\nFull per-language reference: [Backends](https://goldziher.github.io/poly/reference/backends/).\n\n---\n\n## AI Agents & MCP\n\npoly ships its agent integration in the box rather than expecting one to be bolted on.\n\n```text\n/plugin marketplace add Goldziher/poly\n/plugin install poly@poly\n```\n\nThat installs 5 skills and 2 slash commands (`/poly-check`, `/poly-fix`) that teach an agent poly's tiered backend\nmodel and when to reach for lint vs. format vs. hooks. Codex clients add the same marketplace through their own\nplugin manager.\n\n`poly mcp` is a stdio MCP server exposing eleven tools that mirror the CLI 1:1 — `lint`, `format_check`, `rules`,\n`config_show`, `cache_stats` and `version` (read-only), `lint_fix`, `format_write` and `cache_clean` (mutating), and\n`workspace_lint` / `workspace_lint_fix`. The last two run the multi-minute whole-project phase (`cargo clippy`,\n`cargo-sort`, `cargo-machete`, `cargo-deny`) and are exposed as async **Tasks**: the call returns a handle the client\npolls with `tasks/get`, falling back to a synchronous result for clients that do not declare the capability.\n\nEvery result carries a `poly` identity block (version, build id, channel, executable, pid, `engines` — a blake3\ndigest of every compiled-in backend's version) and separates three per-file outcomes — **checked**, **skipped**\n(poly declined the file) and **errored** (poly failed on a file it accepted). `isError` is set whenever anything\nerrored, so an agent can gate on it before trusting the payload.\n\nFull parameter reference: [`.ai-rulez/skills/poly-mcp/SKILL.md`](.ai-rulez/skills/poly-mcp/SKILL.md).\n\n---\n\n## Performance\n\nRelease build, Apple Silicon, cold cache (`--no-cache`), best of three runs on an idle machine.\n`poly lint --no-workspace` and `poly fmt --check` over the whole repository, counting the files\npoly actually inspected. These are poly's own numbers — **not** a comparison against ruff,\noxlint, biome or anything else; no such benchmark was run.\n\n\n\n| Project | `poly lint` | Findings | Peak RSS | `poly fmt --check` |\n|---|---|---|---|---|\n| Django | 3,113 files in **0.82s** | 66,839 | 0.21 GB | 5,539 files in 0.30s |\n| home-assistant | 25,443 files in **3.5s** | 376,829 | 0.48 GB | 25,559 files in 1.2s |\n| Kubernetes | 21,657 files in **6.8s** | 41,576 | 0.40 GB | 21,824 files in 12.9s |\n| prettier | 7,057 files in **1.9s** | 19,373 | 0.40 GB | 7,450 files in 0.44s |\n| TypeScript | 32,606 files in **13.3s** | 179,586 | 0.52 GB | 40,012 files in 4.0s |\n\n\n\nKubernetes is the one repository where formatting costs more than linting: its Go files go\nthrough `gofmt`, the one backend that is a subprocess rather than a linked-in crate, and ~20,000\nprocess spawns dominate the run.\n\nThe blake3 cache and rayon parallelism (see [How It Works](#how-it-works)) are what keep repeat\nruns fast — Django re-lints in 0.71s warm against 0.82s cold: a cache hit skips the engine\nentirely, and everything else is split across cores.\n\n---\n\n## Documentation\n\nA single `poly.toml` drives linting, formatting, git hooks, and commit-message policy; `poly.local.toml` layers local\noverrides on top, nested files cascade in a monorepo, and `poly config show` prints the effective merged result.\nUnknown keys, unknown sections and wrongly-typed values are reported as warnings, never silently ignored.\n\n- [Quickstart](https://goldziher.github.io/poly/start/quickstart/) — install, first run, first config.\n- [Configuration](https://goldziher.github.io/poly/guides/configuration/) — every key, rule selection, inline\n suppression, monorepo cascading, shared and remote config.\n- [Hooks](https://goldziher.github.io/poly/guides/hooks/) — `poly hooks install`, builtin hooks, staged isolation,\n timeouts, concurrency, caching.\n- [CLI reference](https://goldziher.github.io/poly/reference/cli/) — every subcommand and flag, and the exit-code\n contract.\n- [Backends](https://goldziher.github.io/poly/reference/backends/) — full language table and the tool catalog.\n\n---\n\n## Contributing\n\nKeep changes small and test-backed. A new or changed backend needs known-bad and known-unformatted fixtures under\n`crates/poly-core/tests/`, and must preserve the uniform `Engine` boundary. Before committing:\n\n```sh\npoly hooks install # wires lint/format/cargo checks into git; they run on every commit\ncargo test --workspace --no-fail-fast\n```\n\nFor anything touching the runner, an engine, or the rule pack, also run the hardening harness. poly's\nown fixtures are small and chosen to exercise a known path; the harness runs poly over real\nthird-party trees and checks the things fixtures cannot — that no file errored, that formatting\nconverges in two passes, that the cache never serves a different answer than a cold run, and that no\nlanguage poly claims to lint reports `no lint rules for` it:\n\n```sh\ntask harden # pinned third-party repositories\ntask harden:local # the sibling working trees next door, read-only\ntask harden:generated # machine-generated code (corpus C)\n```\n\nIt also reports per-rule finding counts per repository, which is how a pack rule earns a default\nseverity. See [`docs/harden-corpus.md`](docs/harden-corpus.md) for what each corpus is allowed to\nassert, and why a count needs a pinned input while an invariant does not.\n\n---\n\n## License\n\nMIT - see [LICENSE](LICENSE).\n", "bytes": 18772, "sha": "9193a92c512ba86edb4bde2f598bfbcef27d2526316116d7a8a3559892219e3e", "repo_slug": "goldziher/poly", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_goldziher_poly_9235d459/readme" }