Skip to main content

pyhyi

Repository hygiene checker. It catches the mess that autonomous coding agents (and hurried humans) leave behind: dump folders, stale docs, broken doc links, forgotten TODOs, junk in the repo root, commits that ignore the convention.

Status: pre-alpha. The engine is in place; real hygiene rules come next.

Idea

Strong models know the conventions. They just don't follow the implicit ones unless someone enforces them. pyhyi turns those implicit expectations into explicit, checkable rules, so a tool slaps the agent's hands instead of a human.

  • Language-agnostic core — git history, file layout, text references between files. Works on any repository, not only Python ones.
  • Thin language adapters (planned) — precise dependency graphs where needed, built on existing tools rather than custom parsers.
  • Precision over recall — every finding should be worth reading. Suppressions require a reason; a baseline lets legacy repositories adopt it gradually.
  • Agent-friendly output — JSON reports an agent can act on directly.

Install

pip install pyhyi
# or run without installing
uvx pyhyi check

Requires Python 3.10+ and git on PATH.

Usage

pyhyi check                 # check the repository containing the current directory
pyhyi check path/to/repo --format json
pyhyi check --select rule-a,rule-b --ignore rule-c
pyhyi baseline              # record current issues; only new ones fail afterwards
pyhyi rules                 # list available rules

Exit codes: 0 no issues, 1 issues found, 2 usage, configuration or internal error.

pyhyi scans tracked files plus untracked files that are not git-ignored, so junk is caught before it is committed.

Configuration

Settings live in the repository root, in the first file found of pyhyi.toml, .pyhyi.toml (top-level keys) or pyproject.toml ([tool.pyhyi] table). Non-Python projects do not need a pyproject.toml.

[tool.pyhyi]
select = ["rule-a", "rule-b"]   # default: every rule enabled by default
ignore = ["rule-c"]
exclude = ["vendor", "*.min.js", "docs/generated/**"]
baseline = ".pyhyi-baseline.json"

[tool.pyhyi.per-path-ignores]
"tests/fixtures/**" = ["rule-a"]

[tool.pyhyi.rules.rule-a]
some-option = 10

Unknown keys, unknown rule ids and options of the wrong type are errors, so typos do not silently disable checks.

Path patterns use /. * matches within one path segment, ** across segments. A pattern without / matches a name at any depth (node_modules); a pattern with / is anchored at the root (docs/*.md, /build). Matching a directory covers everything inside it.

Suppressing a finding

Put a marker in a comment on the reported line, naming the rule and the reason:

data = load()  # pyhyi: ignore[rule-a] generated by the release script
<!-- pyhyi: ignore[rule-a] link to an external mirror -->

The comment opener (#, //, /*, <!--, --, ;, %, {#) must start the line or follow whitespace. A suppression without a reason is not applied, and the bad-suppression rule reports it together with markers that name unknown rules. Findings without a line (commits, repository layout) are silenced through ignore or per-path-ignores instead.

Baseline

On an existing repository the first run may report hundreds of issues. pyhyi baseline writes them to .pyhyi-baseline.json; pyhyi check then fails only on new ones. Entries are matched by rule, file and a line-independent key, so editing elsewhere in a file does not bring them back. When baselined issues get fixed, check says so; run pyhyi baseline again to shrink the file. Commit the baseline file.

Writing rules

A rule is a class with a kebab-case id, a one-line summary and a check method that yields findings:

from pyhyi.rules import Rule


class NoTmpFiles(Rule):
    id = "no-tmp-files"
    summary = "Temporary files must not be in the repository."
    default_options = {"suffixes": [".tmp", ".bak"]}

    def check(self, ctx):
        for path in ctx.files:
            if path.endswith(tuple(self.options["suffixes"])):
                yield self.finding("Temporary file in the repository", path=path)

ctx gives read-only access to the repository: files, exists(), read_text(), lines() and commits. Keep line numbers out of messages: the message doubles as the baseline key unless key= is passed.

Third-party packages register rules through an entry point:

[project.entry-points."pyhyi.rules"]
no-tmp-files = "my_package.rules:NoTmpFiles"

Development

uv sync
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run pyhyi check

Releases are described in docs/releasing.md.

License

MIT

Metadata

Release files for pyhyi 0.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyhyi 0.0.1
File Size Uploaded Provenance Actions
pyhyi-0.0.1.tar.gz 37.5 kB With provenance Details for pyhyi-0.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyhyi 0.0.1
File Interpreter ABI Platform Actions
pyhyi-0.0.1-py3-none-any.whl Python 3 none any Details for pyhyi-0.0.1-py3-none-any.whl

Total release size: 59.1 kB

Release files / pyhyi-0.0.1.tar.gz

Download URL pyhyi-0.0.1.tar.gz
Size 37.5 kB
Tags Source
SHA-256 checksum
How to use checksums
13975a7f2643ea2ec539ea52dd6e496fa282254c22e187a01e633994f11555ae
BLAKE2b-256 checksum
How to use checksums
8f30e40904359a33c7eb2e20bace39335e6cd8de5e7691907fe02c9121453c3b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / pyhyi-0.0.1-py3-none-any.whl

Download URL pyhyi-0.0.1-py3-none-any.whl
Size 21.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b37b8f83c737f37841fcc6e336c4fd856dfa99ec808a6fe6e7dcf620321e7403
BLAKE2b-256 checksum
How to use checksums
de41b819e075b582f83b888747206ce7757190583f7e66eb0c28ff5735c8172e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for pyhyi 0.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pyhyi-0.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page