CodexRay

The ultimate Python code health analyzer.

One command to understand the complete health of a Python repository — quality, security, types, architecture, complexity, dependencies, tests, and documentation — with prioritization that feels like a staff engineer review.

pip install py-codexray
codexray analyze .

Why CodexRay?

The Python ecosystem already has excellent specialized tools (Ruff, Bandit, Radon, Vulture, pip-audit, BasedPyright). Developers still have to run them separately, reconcile duplicate noise, and decide what matters.

CodexRay is the unified intelligence layer:

• Orchestrates best-in-class analyzers
• Adds native architecture, duplicate, and documentation analysis
• Deduplicates and clusters findings
• Computes a transparent repository health score
• Estimates cleanup effort and recommends what to fix first
• Emits terminal, Markdown, HTML, JSON, and SARIF reports

"Run CodexRay before you merge."

Install

pip install py-codexray

# Recommended full toolchain
pip install 'py-codexray[full]'

Requires Python 3.10+ to run CodexRay. You can still analyze projects on Python 3.6–3.14.

# Legacy company codebase on 3.6
codexray analyze . --python-version 3.6

# Untyped apps: keep type noise low (default)
codexray analyze . --type-mode basic

# Stricter typing audit
codexray analyze . --type-mode strict

Or in config:

[tool.codexray]
python_version = "3.6"

CodexRay also auto-detects from .python-version, runtime.txt, requires-python, and Ruff's target-version.

CLI

codexray analyze .                 # full health analysis
codexray report . -f html -o out.html
codexray fix .                     # safe autofixes via Ruff
codexray doctor .                  # environment & analyzer diagnosis
codexray graph .                   # import graph + cycles
codexray diff . --save             # save / compare baseline
codexray watch . --profile fast    # re-analyze on changes

Profiles

Exit codes

analyze exits 1 when the score is below --fail-under (default 70, configurable).

Missing tests

CodexRay reports:

Configuration

pyproject.toml:

[tool.codexray]
profile = "standard"
fail_under = 70
exclude = [".venv", "dist", "build"]
complexity_threshold = 10
ignore_rules = ["DOC001"]

Or codexray.toml:

[codexray]
profile = "fast"
fail_under = 80

Reports

codexray analyze . -f json -o report.json
codexray analyze . -f sarif -o results.sarif
codexray report . -f md -o HEALTH.md
codexray report . -f html -o health.html

Architecture (short)

See docs/architecture.md, docs/ecosystem-analysis.md, and docs/feature-matrix.md.

discover → parallel analyzers → normalize → intelligence → report / fix

Integrate, don't reinvent: Ruff, Bandit, Radon, Vulture, pip-audit, BasedPyright.

Native where tools fall short: import graphs, cycles, duplicates, health scoring, clustering.

Plugin API

Entry point group: codexray.analyzers

class MyAnalyzer:
    name = "mine"
    profiles = {"standard", "deep"}

    def is_available(self) -> bool:
        return True

    def analyze(self, ctx):
        return []  # list[Finding]

[project.entry-points."codexray.analyzers"]
mine = "mypkg:MyAnalyzer"

Development

python -m pip install -e '.[dev,full]'
pytest
codexray analyze src

License

MIT — © 2026 M SANTHOSH KUMAR

Repository: https://github.com/santhoshse7en/codexray