CQ - Python Code Quality Analysis Tool
Coding agents say "done" while tests fail, types are broken or a secret sits in the code. cq checks for them.
cq runs 14 code quality tools on a Python project, combines their results into one score, and shows the single most important defect as a short markdown prompt you can hand to an LLM. Fix that one issue, run cq again, and repeat until everything passes. Neither you nor the LLM has to know how to run or read the individual tools.
Use it by hand, as a Claude Code stop hook that keeps the agent working until the check passes, as a pre-commit hook, or as a CI gate.
cq never edits your files. You may want to run ruff check --fix and ruff format first so the easy fixes are already done.
Install
Requires Python 3.12+ and uv.
# install the `cq` command line tool from PyPI
uv tool install python-code-quality
# optional: secret scanning (see Tools below)
uv tool install kingfisher-bin
ty, pytest and coverage run inside your project's own environment with uv run, so they see your dependencies. If your project does not include them, uv adds them for that run only; your project files are not changed.
To install from source instead:
git clone https://github.com/rhiza-fr/py-cq.git
cd py-cq
uv tool install .
Quick start
From your project's root directory:
cq check . # table overview of all scores
cq check . -o llm # top defect as markdown, to pipe to an LLM
cq check . -o score # numeric score only, exits 1 on errors (CI gate)
cq check . -o llm prints one issue with the code around it, for example:
shop.py:6 - F821: Undefined name `discount`
```python
3:
4: def total(prices: list[float]) -> float:
5: """Return the sum of prices."""
6: return sum(prices) + discount
7:
8:
```
`discount` is not imported or defined anywhere else in this file.
Please fix only this issue.
To send it straight to an LLM: cq check . -o llm | claude -p "fix this".
Usage
cq check . # Table overview of scores for humans
cq check . -o llm # Top defect as markdown for LLMs
cq check . -o llm-json # Top defect as JSON with fingerprint (for automation)
cq check . -o score # Numeric score only for CI
cq check . -o json # Detailed parsed JSON output for jq
cq check . -o raw # Raw tool output for debug
cq check path/to/file.py # Just one file (skips pytest and coverage)
cq check . --only ruff,ty # Run only specific tools
cq check . --skip bandit # Skip specific tools
cq check . --exclude demo # Exclude paths from all tools
cq check . -o llm --limit 3 # Show the top 3 issues instead of 1
cq check . -o llm -s src/foo.py:42:E501 # Silence one issue (or a whole file: -s src/foo.py)
cq check . -o llm --order phase # Fix in tool order (syntax, lint, types, ...) instead of most severe first
cq check . -o llm --hint # Append "run cq again to verify" (for human workflows)
cq check . --workers 1 # Run sequentially if you like things slow
cq check . --clear-cache # Clear cached results before running (rarely needed)
cq config # Show the effective tools and thresholds for this project
cq is-fixed <fingerprint> # Check whether a specific issue has been resolved
Exit codes: cq check exits with code 1 if any tool metric falls below its error_threshold, so it works as a CI gate:
cq check . && deploy # block deploy on errors
cq check . -o score # print score, exit 1 on errors
Tools
| Order | Tool | Measures |
|---|---|---|
| 1 | compileall | Syntax errors |
| 2 | ruff | Lint / style |
| 3 | ty | Type errors |
| 4 | bandit | Security vulnerabilities |
| 5 | kingfisher | Hardcoded secrets (API keys, tokens, private keys) |
| 6 | uv audit | Known vulnerabilities in locked dependencies |
| 7 | pytest | Test pass rate |
| 8 | coverage | Test coverage |
| 9 | vulture | Dead code |
| 10 | interrogate | Docstring coverage |
| 11 | radon cc | Cyclomatic complexity |
| 12 | radon mi | Maintainability index |
| 13 | radon hal | Halstead volume / bug estimate |
| 14 | ruff format | Formatting (fraction of files already formatted) |
By default all tools run in parallel. With -o llm, tools run in this order and cq stops at the first tool that fails, since later results are not needed to pick the top issue. coverage starts alongside pytest and is cancelled if pytest fails, scoring 0% without a second test run.
Tool output is cached with diskcache, so re-runs on unchanged files are fast. The cache stays under 100 MB, keeps entries for up to 5 days, and is stored as JSON (cq never writes pickles).
Notes on specific tools
kingfisher scans the working tree for hardcoded secrets with Kingfisher (502 rules, Rust). It is not a Python dependency of cq: install it once with uv tool install kingfisher-bin (about 41 MB). When it is not on the PATH the tool is skipped with a warning. cq runs it offline (--no-validate --no-update-check) and with --redact, so secrets are never sent to provider APIs and never stored in the cache; the LLM message gives the file, line and rule but no source excerpt. Silence a test fixture or false positive with a kingfisher:ignore comment on that line.
uv audit checks the versions pinned in uv.lock against the OSV advisory database. It needs uv on the PATH, a uv.lock and network access; when any is missing the tool is skipped with a warning instead of failing. Only advisories that have a fix version are reported, since those are the ones an upgrade resolves. Results are cached like every other tool, so an advisory published after a run shows up when the project changes or the cache entry expires.
vulture runs at --min-confidence 60, the level at which it reports unused functions, classes, methods and variables. It cannot see dynamic use, so common framework decorators (@app.command, @app.route, @pytest.fixture, validators and similar) are ignored. For anything else that is used but never referenced by name, such as public API, add it to ignore_names under [tool.vulture] in your pyproject.toml.
Configuration
Add a [tool.cq] section to your project's pyproject.toml:
[tool.cq]
# Skip tools that are slow or not relevant to your project
disable = ["coverage", "interrogate"]
# Exclude paths from all tools (merged with --exclude CLI flag)
exclude = ["demo", "docs"]
# Lines of source context shown around each defect in LLM output (default: 15)
context_lines = 15
# Override warning/error thresholds per tool
[tool.cq.thresholds.coverage]
warning = 0.9
error = 0.7
Tool IDs are compile, ruff, ty, bandit, kingfisher, uv-audit, pytest, coverage, vulture, interrogate, radon-cc, radon-mi, radon-hal and ruff-format.
Run cq config to see the effective thresholds for a project after your overrides. The default commands and thresholds are defined in src/py_cq/config/config.toml.
Claude Code Integration
As a stop hook
Add a stop hook to your project's .claude/settings.json. Each time Claude finishes responding, cq checks the project; if it fails, Claude receives the fix prompt and keeps working until the check passes:
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "cq check \"$CLAUDE_PROJECT_DIR\" -o score > /dev/null || { cq check \"$CLAUDE_PROJECT_DIR\" -o llm >&2; exit 2; }"
}
]
}
]
}
}
$CLAUDE_PROJECT_DIR points at the project root even when Claude has changed into a subdirectory, where . would fail with Directory must contain pyproject.toml. Exit code 2 is what makes Claude Code block the stop and pass the hook's stderr (the fix prompt) to Claude. When the check passes, the hook exits 0 silently and Claude stops as normal. Claude keeps looping as long as the check fails, so use thresholds your project can actually meet.
Note: Use project-level
.claude/settings.json, not global settings. This hook only makes sense in Python projects.
As a slash command
For manual invocation, create .claude/commands/cq-fix.md:
---
allowed-tools: Bash(cq check:*)
---
!`cq check . -o llm`
Then run /cq-fix in Claude Code. The !`...` line runs cq when the command is invoked and puts its output in the prompt, so Claude sees the issue immediately without an extra tool call.
Hook or slash command:
- Stop hook: automatic, runs every time Claude stops, best for unattended loops
- Slash command: manual
/cq-fix, gives you explicit control over when to check
GitHub Action
Add cq as a quality gate to a workflow:
- uses: actions/checkout@v4
- uses: rhiza-fr/py-cq@v0.4.2
The step fails when any tool falls below its error threshold. The job summary shows the score table and, on failure, up to 3 issues from the first failing tool, with the code around each one.
Inputs, all optional:
| Input | Default | Meaning |
|---|---|---|
path |
. |
Project directory or file to check |
limit |
3 |
Number of issues to show on failure |
args |
Extra cq check arguments, for example --skip coverage |
|
package |
python-code-quality |
What uv tool install installs, for example python-code-quality==0.4.2 |
kingfisher |
true |
Install Kingfisher so the secret scan runs |
The action installs uv if the runner does not have it. It also works on Gitea Actions, which does not display the job summary; the table and issues are printed to the log as well.
pre-commit
Add to your .pre-commit-config.yaml:
- repo: https://github.com/rhiza-fr/py-cq
rev: v0.4.2
hooks:
- id: cq
The hook runs cq check . -o llm on the whole project when Python files change and blocks the commit if the gate fails, printing the top issue. It runs your tests, so it suits projects with a fast suite; cached results keep re-runs quick.
Fingerprint-based verification
-o llm-json returns a JSON object with a stable id fingerprint. Pass it back to cq is-fixed to check whether that specific issue has been resolved, without re-running all tools:
# Get the top defect as JSON
cq check . -o llm-json
{
"id": "ruff::my-project::src/foo.py::42::E501",
"file": "src/foo.py",
"project": "/home/user/my-project",
"message": "..."
}
# After fixing, verify only that issue (fast: reruns one tool on one file)
cq is-fixed "ruff::my-project::src/foo.py::42::E501"
This is most useful in automation: fix an issue, confirm it's gone, then fetch the next one. It only verifies that the original issue is gone. A full cq check is still needed to catch regressions, assuming you have sufficient tests.
Python Library
py_cq can be used as a library, with no subprocess required. Instantiate CQ with a project root; config is loaded once from pyproject.toml.
from py_cq import CQ
cq = CQ(".") # load config from ./pyproject.toml
cq = CQ(".", skip=["bandit"]) # skip specific tools
cq = CQ(".", only=["ruff", "ty"]) # run only specific tools
cq = CQ(".", workers=4) # control parallelism
Methods mirror the CLI and return data objects:
# list[ToolResult]: all parsed results before aggregation (-o raw / -o json)
results = cq.raw()
# CombinedToolResults: aggregated score and per-tool results (-o score / table)
combined = cq.check()
print(combined.score) # float
print(combined.tool_results) # list[ToolResult]
# dict: top defect as JSON, equivalent to -o llm-json
issue = cq.check_llm_json()
issue["id"] # fingerprint: "ruff::project::src/foo.py::42::E501"
issue["file"] # "src/foo.py"
issue["message"] # markdown prompt ready to send to an LLM
issue["project"] # absolute project root path
# bool: True if the fingerprinted issue is gone
# Reruns only the affected tool on the affected file, much faster than a full check.
# Pass the id from check_llm_json; also available as `cq is-fixed <id>` on the CLI.
fixed = cq.is_fixed(issue["id"])
check_llm_json accepts the same options as cq check . -o llm-json:
issue = cq.check_llm_json(limit=3, silence=["src/generated.py"], hint=True)
Typical automation loop:
from py_cq import CQ
cq = CQ(".")
while True:
issue = cq.check_llm_json()
if issue["id"] is None:
break # all clear
fix(issue["message"]) # call your LLM
assert cq.is_fixed(issue["id"])
Output formats
Table
> cq check .
┌──────────────────┬──────────┬───────────────────────────┬─────────┬──────────┐
│ Tool │ Time │ Metric │ Score │ Status │
├──────────────────┼──────────┼───────────────────────────┼─────────┼──────────┤
│ compile │ 0.54s │ compile │ 1.000 │ OK │
│ ruff │ 0.14s │ lint │ 1.000 │ OK │
│ ty │ 0.28s │ type_check │ 1.000 │ OK │
│ bandit │ 0.66s │ security │ 1.000 │ OK │
│ kingfisher │ 0.01s │ secrets │ 1.000 │ OK │
│ uv-audit │ 0.01s │ dependencies │ 1.000 │ OK │
│ pytest │ 8.23s │ tests │ 1.000 │ OK │
│ coverage │ 8.68s │ coverage │ 0.930 │ OK │
│ vulture │ 0.55s │ dead_code │ 1.000 │ OK │
│ interrogate │ 0.47s │ doc_coverage │ 0.891 │ OK │
│ radon-cc │ 0.44s │ simplicity │ 0.979 │ OK │
│ radon-mi │ 0.67s │ maintainability │ 0.784 │ OK │
│ radon-hal │ 0.45s │ file_bug_free │ 0.568 │ OK │
│ radon-hal │ │ functions_bug_free │ 0.601 │ OK │
│ ruff-format │ 0.13s │ formatted │ 1.000 │ OK │
│ Total │ 8.83s │ Score │ 0.941 │ │
└──────────────────┴──────────┴───────────────────────────┴─────────┴──────────┘
Score
> cq check . -o score
0.9405469171269684
The score is designed to approach but never quite reach 1.0.
JSON
> cq check . -o json
[
{
"tool_name": "compile",
"metrics": {
"compile": 1.0
},
"details": {},
"duration_s": 0.05611889995634556
}
...
]
Raw
> cq check . -o raw
[
{
"tool_name": "compile",
"command": "D:\\ai\\py-cq\\.venv\\Scripts\\python.exe -m compileall -r 10 -j 8 . -x \".*venv|\\.claude\"",
"stdout": "",
"stderr": "",
"return_code": 0,
"timestamp": "2026-02-20 10:01:22"
}
...
]
Both json and raw output pipe cleanly to jq:
# Get the coverage section
cq check . -o raw | jq '.[] | select(.tool_name == "coverage")'
# Get parsed coverage metrics only
cq check . -o json | jq '.[] | select(.tool_name == "coverage") | .metrics'
Respect
Many thanks to all the wonderful maintainers of:
Metadata
Release files for python-code-quality 0.4.2
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 |
|---|---|---|---|---|
| python_code_quality-0.4.2.tar.gz | 66.7 kB | With provenance | Details for python_code_quality-0.4.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| python_code_quality-0.4.2-py3-none-any.whl | Python 3 | none | any | Details for python_code_quality-0.4.2-py3-none-any.whl |
Total release size: 150.0 kB
Release files / python_code_quality-0.4.2.tar.gz
| Download URL | python_code_quality-0.4.2.tar.gz |
|---|---|
| Size | 66.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
193792e9c57d5f8e90568ba5069e64a243257054ade3a3281ace7550831ffd15
|
|
BLAKE2b-256 checksum How to use checksums |
6461e4c20744f9c5632c3298a8fdbe2304f30e72d3a54af5be78ad106771a247
|
| 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 16, 2026.
Transparency logRelease files / python_code_quality-0.4.2-py3-none-any.whl
| Download URL | python_code_quality-0.4.2-py3-none-any.whl |
|---|---|
| Size | 83.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
11b3781ca44896342c15b13eca61bd8e7b1138974452df26615e01e1ad19769e
|
|
BLAKE2b-256 checksum How to use checksums |
34881ebde2f5deb584e261a380b7c1c7d72c770bca4188ab7f537e1f3b51871a
|
| 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 16, 2026.
Transparency logSecurity for python-code-quality 0.4.2
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 python_code_quality-0.4.2.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 16, 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.