pyclichecker

pyclichecker is a read-only Python linter for high-signal defects and maintainability smells that often appear in rushed or generated code. It parses source with Python's AST and token APIs and has no runtime dependencies.

It is a code-quality tool, not an AI-authorship detector. The same finding can occur in human-written code, and every finding should be judged in context.

Quick start

The project requires Python 3.14. Run it directly without installing:

uvx pyclichecker .

For a persistent command, install it with uv:

uv tool install pyclichecker
pyclichecker .

It can lint one file, consume standard input, emit JSON for an agent, or emit GitHub workflow annotations:

pyclichecker app.py
printf 'def unfinished():\n    pass\n' | pyclichecker -
pyclichecker . --format json
pyclichecker . --format github

Pin a release when reproducibility matters:

uvx pyclichecker@2.4.1 .

Reading a result

Text diagnostics use the conventional path:line:column: code message shape:

app.py:8:1: SLP001 `load_config` is a concrete placeholder implementation
Found 1 issue(s) in 1 file(s).

A practical review loop is:

1. Open the reported file and line.
2. Decide whether the behavior is intentional.
3. Fix the implementation, error handling, or structure.
4. Run the same command again.
5. Suppress only the specific rule when the code is intentionally exceptional.

Rules

pyclichecker --list-rules reports these rules:

Rule selection accepts exact codes or prefixes:

pyclichecker . --select SLP001,SLP002
pyclichecker . --ignore SLP004,SLP008

Thresholds for function size, comment clusters, and duplicate bodies are exposed as command-line options. Run pyclichecker --help for their names and defaults.

For a first pass, fix error findings before reviewing warning findings. Warnings are prompts for engineering judgment, not proof that the code is wrong.

Suppressions

Inline suppression requires an explicit pyclichecker rule code:

def intentional_stub():  # noqa: SLP001
    pass


def another_stub():  # slop: ignore [SLP001]
    pass

Bare # noqa and unrelated codes such as # noqa: F401 do not suppress pyclichecker. Directive-like text inside a string is also ignored.

To suppress an entire file, place this real comment within its first five lines:

# slop: ignore-file

Exit codes

• 0: no finding met --fail-on, and the run had no operational error.
• 1: at least one finding met the configured failure severity.
• 2: the scan could not run completely, including missing paths, unreadable files, unsupported inputs, or no discovered Python files.

--fail-on warning is the default. --fail-on error reports warnings without failing, and --fail-on never reports all findings without failing.

Agent use

The repository includes a reusable pyclichecker Agent Skill. Skill-aware agents can load that folder and run the linter through uvx without permanently installing the package.

Agents should use the pinned release and JSON output for stable results:

uvx pyclichecker@2.4.1 changed_file.py --format json

JSON output contains the package version, number of files checked, findings, and operational errors. Each finding includes path, line, column, code, severity, and message.

Treat exit 1 as work to review and exit 2 as a broken or incomplete scan. Fix findings before adding suppressions, and keep every suppression scoped to one explicit rule.

An agent should finish only after the same command returns 0, or after it records why each remaining finding is intentional. It should never treat exit 2 as a clean result.

For agents that do not load skills, add this portable contract to the project's AGENTS.md:

## Python quality gate

After creating or changing Python code:

1. Run pyclichecker on every changed Python file:
   `uvx pyclichecker@2.4.1 changed_file.py --format json`
2. Treat exit 1 as findings to fix and exit 2 as an incomplete scan.
3. Fix findings and rerun relevant tests. Do not add broad suppressions.
4. Run the final repository gate with the same command, replacing
   `changed_file.py` with `.`, and finish only when it exits 0.

Development

The locked development environment contains Ruff and uses the standard-library unittest runner:

uv sync --locked
uv run python -m unittest discover -v
uv run ruff check .
uv run ruff format --check .
uv run pyclichecker src tests
uv build
uvx --from . pyclichecker --version

See CONTRIBUTING.md for rule and pull-request requirements.

The implementation has been exercised on macOS with CPython 3.14. The GitHub Actions workflow is configured to run the complete validation suite on Linux.

License

Released under the MIT License.