Skip to main content

CQ - Python Code Quality Analysis Tool

CI codecov PyPI version Python versions License

Run 14 code quality tools, aggregate results into one score, and surface the single most critical defect as a focused markdown prompt — ready to pipe to any LLM.

This can dramatically reduce the amount of noise for LLMs (and humans) and remove the need for them to know about these tools.

Note: It never edits your files. This is a job for you or an LLM. You may wish to run ruff check --fix and ruff format first.

cq check . -o llm     # top defect as markdown, pipe to an LLM
cq check .            # table overview of all scores
cq check . -o score   # numeric score only, exits 1 on errors (CI gate)

cq demo

Install

# install the `cq` command line tool from PyPi
uv tool install python-code-quality

# or, clone it then install 
git clone https://github.com/rhiza-fr/py-cq.git
cd py-cq
uv tool install .

Tools

These tools are run in parallel except: When running '-o llm', we run sequentially and exit early at the first error. coverage is a special case: it starts alongside pytest and is cancelled if pytest fails, scoring 0% without a second test run.

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)

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.

Diskcache is used to cache tool output for lightning fast re-runs. Sane defaults: <100 Mb, <5 days, stored as JSON (cq never writes pickles).

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 . --workers 1     # Run sequentially if you like things slow
cq check . --clear-cache   # Clear cached results before running (rarely needed)
cq check . -o llm --hint   # Append "run cq again to verify" (for human workflows)
cq config --path path/to/project/ # Show effective tool configuration
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, making it suitable as a CI gate:

cq check . && deploy        # block deploy on errors
cq check . -o score         # print score, exit 1 on errors

Fingerprint-based verification

-o llm-json returns a JSON object with a stable id fingerprint you can pass back to cq is-fixed to check whether a 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. Note that this only verifies the original issue is no longer present — a full project-wide scan is still needed to guarantee no regressions, assuming you have sufficient tests.

Python Library

py_cq can be used as a library — 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"])

Claude Code Integration

Add a stop hook to your project's .claude/settings.json so Claude automatically checks quality after each session and loops until clean:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cq check . -o score && echo 'CQ: all clear' || cq check . -o llm; true"
          }
        ]
      }
    ]
  }
}

When the score passes, Claude sees CQ: all clear (~5 tokens). When it fails, Claude receives the targeted fix prompt and continues working. This automates the cq check . -o llm | claude -p "fix this" loop.

Note: Use project-level .claude/settings.json, not global settings — this hook only makes sense in Python projects.

As a slash command (skill)

For manual invocation, create .claude/commands/cq-fix.md:

$(cq check . -o llm)

Then invoke it with /cq-fix in Claude Code. The $(...) embeds the live cq output directly into the prompt before Claude starts, so it sees the issue immediately without an extra tool call.

Hook vs skill:

  • Stop hook — automatic, runs after every session, best for unattended loops
  • Skill — manual /cq-fix, gives you explicit control over when to check

Table output

> cq check .
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ Tool             ┃     Time ┃                    Metric ┃ Score   ┃ Status   ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ compile          │    0.42s │                   compile │ 1.000   │ OK       │
│ ruff             │    0.17s │                      lint │ 1.000   │ OK       │
│ ty               │    0.33s │                type_check │ 1.000   │ OK       │
│ bandit           │    0.56s │                  security │ 1.000   │ OK       │
│ uv-audit         │    0.41s │              dependencies │ 1.000   │ OK       │
│ pytest           │    0.91s │                     tests │ 1.000   │ OK       │
│ coverage         │    1.26s │                  coverage │ 0.910   │ OK       │
│ vulture          │    0.32s │                 dead_code │ 1.000   │ OK       │
│ interrogate      │    0.36s │              doc_coverage │ 1.000   │ OK       │
│ radon-cc         │    0.32s │                simplicity │ 0.982   │ OK       │
│ radon-mi         │    0.38s │           maintainability │ 0.869   │ OK       │
│ radon-hal        │    0.30s │             file_bug_free │ 0.928   │ OK       │
│ radon-hal        │          │            file_smallness │ 0.851   │ OK       │
│ radon-hal        │          │        functions_bug_free │ 0.913   │ OK       │
│ radon-hal        │          │       functions_smallness │ 0.724   │ OK       │
│ ruff-format      │    0.12s │                 formatted │ 1.000   │ OK       │
│                  │          │                     Score │ 0.965   │          │
└──────────────────┴──────────┴───────────────────────────┴─────────┴──────────┘

Single score output

> cq check . -o score
0.9662730667181059 # this is designed to approach but not reach 1.0

Json output

> cq check . -o json
[
  {
    "tool_name": "compile",
    "metrics": {
      "compile": 1.0
    },
    "details": {},
    "duration_s": 0.05611889995634556
  }
  ...
]

Raw output

> cq check . -o raw
[
  {
    "tool_name": "compile",
    "command": "D:\\ai\\py-cq\\.venv\\Scripts\\python.exe -m compileall -r 10 -j 8 . -x .*venv",
    "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'

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 match the keys in src/py_cq/config/config.toml: compile, ruff, ty, bandit, kingfisher, uv-audit, pytest, coverage, radon-cc, radon-mi, radon-hal, vulture, interrogate, ruff-format.

Default config

Defined in src/py_cq/config/config.toml (sections are namespaced by language):

[python.compile]
command = "{python} -m compileall -r 10 -j 8 \"{context_path}\" -x .*venv|\\.claude"
parser = "CompileParser"
order = 1
warning_threshold = 0.9999
error_threshold = 0.9999
cache_invariant = "ast"

[python.ruff]
command = "{python} -m ruff check --output-format concise --no-cache \"{context_path}\" --extend-exclude .claude{exclude}"
exclude_format = " --extend-exclude {path}"
parser = "RuffParser"
order = 2
warning_threshold = 0.9999
error_threshold = 0.9

[python.ty]
command = "{python} -m ty check --output-format concise --color never \"{context_path}\" --exclude .claude{exclude}"
exclude_format = " --exclude {path}"
parser = "TyParser"
order = 3
warning_threshold = 0.9999
error_threshold = 0.8
run_in_target_env = true
extra_deps = ["ty"]

[python.bandit]
command = "{python} -m bandit -r {scan_targets} -f json -q -s B101 --severity-level medium{exclude}"
scan_exclude_names = [".venv", ".claude", "tests"]
exclude_format = " --exclude {abs_native_path}"
parser = "BanditParser"
order = 4
warning_threshold = 0.9999
error_threshold = 0.8

[python.kingfisher]
command = "kingfisher scan \"{context_path}\" --no-validate --no-update-check --git-history none --no-extract-archives --redact -q -f json --exclude .venv --exclude .git --exclude .hypothesis --exclude dist --exclude \"*_cache\" --exclude __pycache__ --exclude .claude{exclude}"
exclude_format = " --exclude {path}"
parser = "KingfisherParser"
order = 5
warning_threshold = 0.9999
error_threshold = 0.9999

[python.uv-audit]
command = "uv audit --project \"{abs_context_path}\" --frozen --output-format json"
parser = "UvAuditParser"
order = 6
warning_threshold = 0.9999
error_threshold = 0.8
skip_for_file = true

[python.pytest]
command = "{python} -m pytest -vv \"{context_path}\" --ignore .claude{exclude}"
exclude_format = " --ignore {path}"
parser = "PytestParser"
order = 7
warning_threshold = 1.0
error_threshold = 1.0
run_in_target_env = true
extra_deps = ["pytest"]
skip_for_file = true
cache_invariant = "ast"

[python.coverage]
command = "{python} -m coverage run --omit=*/tests/*,*/test_*.py,*/py_cq/runners/* \"{pytest_serial}\" \"{context_path}\" --ignore .claude{exclude} && {python} -m coverage report --show-missing --omit=*/tests/*,*/test_*.py,*/py_cq/runners/*"
exclude_format = " --ignore {path}"
parser = "CoverageParser"
order = 8
warning_threshold = 0.9
error_threshold = 0.5
run_in_target_env = true
extra_deps = ["coverage", "pytest"]
skip_for_file = true
skip_if = "pytest"
cache_invariant = "ast"

[python.vulture]
command = "{python} -m vulture \"{context_path}\" --min-confidence 60 --ignore-decorators \"@*.command,@*.callback,@*.route,@*.get,@*.post,@*.put,@*.delete,@*.patch,@*fixture,@*.task,@*hookimpl,@*validator,@*.errorhandler\" --exclude .venv,dist,.*_cache,docs,.git,.claude{exclude}"
exclude_format = ",{path}"
parser = "VultureParser"
order = 9
warning_threshold = 0.9999
error_threshold = 0.8
cache_invariant = "ast"

[python.interrogate]
command = "{python} -m interrogate \"{context_path}\" -e .claude -e \"{context_path}/tests\"{exclude} -v --fail-under 0"
exclude_format = " -e {path}"
parser = "InterrogateParser"
order = 10
warning_threshold = 0.8
error_threshold = 0.5

[python.interrogate.parser_config]
skip_empty_init = true

[python.radon-cc]
command = "{python} -m radon cc --json --exclude '.claude/**' \"{context_path}\""
parser = "ComplexityParser"
order = 11
warning_threshold = 0.6
error_threshold = 0.4

[python.radon-mi]
command = "{python} -m radon mi -s --json --exclude '.claude/**' \"{context_path}\""
parser = "MaintainabilityParser"
order = 12
warning_threshold = 0.6
error_threshold = 0.4

[python.radon-hal]
command = "{python} -m radon hal -f --json --exclude '.claude/**' \"{context_path}\""
parser = "HalsteadParser"
order = 13
warning_threshold = 0.35
error_threshold = 0.3

[python.ruff-format]
command = "{python} -m ruff format --check --output-format concise --no-cache \"{context_path}\" --extend-exclude .claude --config \"include=['*.py','*.pyi','*.ipynb']\"{exclude}"
exclude_format = " --extend-exclude {path}"
parser = "RuffFormatParser"
order = 14
warning_threshold = 0.9999
error_threshold = 0.5

Respect

Many thanks to all the wonderful maintainers of :

Metadata

Release files for python-code-quality 0.4.0

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

Source distribution (sdist)

Source distribution for python-code-quality 0.4.0
File Size Uploaded Provenance Actions
python_code_quality-0.4.0.tar.gz 63.3 kB With provenance Details for python_code_quality-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for python-code-quality 0.4.0
File Interpreter ABI Platform Actions
python_code_quality-0.4.0-py3-none-any.whl Python 3 none any Details for python_code_quality-0.4.0-py3-none-any.whl

Total release size: 142.8 kB

Release files / python_code_quality-0.4.0.tar.gz

Download URL python_code_quality-0.4.0.tar.gz
Size 63.3 kB
Tags Source
SHA-256 checksum
How to use checksums
6e07e5f25d92e2dcd9e99ab3a02046bda4b2bf8728dd2d17b39d824eb412f8c4
BLAKE2b-256 checksum
How to use checksums
fca44f45d18aba4987e2ea9e58e64731df27cf7d8b4dba440a0d1eb047159198
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 15, 2026.

Transparency log

Release files / python_code_quality-0.4.0-py3-none-any.whl

Download URL python_code_quality-0.4.0-py3-none-any.whl
Size 79.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7c1e7210a3c1c4475e769b2121c957c72a90b8d0fe6e7ae2c0c78ab02f29a26b
BLAKE2b-256 checksum
How to use checksums
68e16df0aeb9463a3d1b93b769aa259d967ed9bee7397e4efa09d96f66296174
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 15, 2026.

Transparency log

Security for python-code-quality 0.4.0

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 python_code_quality-0.4.0.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 15, 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.

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