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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.