Qualgraph is a local, graph-aware code quality analyzer for Python repositories. It builds a code graph, annotates it with quality signals, ranks risky code, and renders a Markdown report plus an offline web viewer.
The core idea is that structure, static analysis, coverage, git history, security findings, profiler data, and optional LLM findings all live on the same NetworkX graph. That makes cross-signal findings possible, such as complex code with weak tests, hidden git co-change coupling, and risky vulnerable imports.
Until the package is published to PyPI, install from the repository:
python -m pip install "git+https://github.com/benzae1/qualgraph.git"For local development:
git clone https://github.com/benzae1/qualgraph.git
cd qualgraph
python -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"On Windows PowerShell:
git clone https://github.com/benzae1/qualgraph.git
cd qualgraph
python -m venv .venv
.\.venv\Scripts\python -m pip install -e ".[dev]"Run the full local workflow on the bundled tiny benchmark repository:
qualgraph analyze benchmarks/repos/tiny_repo --preset fast --coverage-mode skip --top-n 5This writes:
.qualgraph/graph.json.qualgraph/annotated.graph.json.qualgraph/report.md.qualgraph/export.json.qualgraph/runs/<run_id>/run_summary.json
Open the local viewer:
qualgraph serve .qualgraph/annotated.graph.json --openpython -m qualgraph --help works too.
The one-command path is:
qualgraph analyze <repo> --preset standardUseful focused commands:
qualgraph build <repo> --output .qualgraph/graph.json
qualgraph annotate <repo> --graph .qualgraph/graph.json --output .qualgraph/annotated.graph.json --annotators full
qualgraph report .qualgraph/annotated.graph.json --output .qualgraph/report.md
qualgraph export-json .qualgraph/annotated.graph.json --output .qualgraph/export.json
qualgraph serve .qualgraph/annotated.graph.json --openPresets:
fast: radon, ruff, docstring, and cross-signal findings.standard: fast plus git history and co-change.full: standard plus vulture, coverage/test linkage, and security tools.
If .qualgraph/runs is not writable, pass a run-log directory:
qualgraph analyze . --artifacts-dir /tmp/qualgraph-runsor set QUALGRAPH_ARTIFACTS_DIR.
Qualgraph does not require API keys. The subscription-friendly workflow exports focused task files for an agent to complete:
qualgraph llm export-tasks .qualgraph/annotated.graph.json --limit 20
qualgraph llm import-results .qualgraph/runs/<run_id> --graph .qualgraph/annotated.graph.json --output .qualgraph/final.graph.json
qualgraph report .qualgraph/final.graph.json --output .qualgraph/report.mdAPI-backed analysis is available for OpenAI, Anthropic, and local Ollama:
qualgraph llm analyze .qualgraph/annotated.graph.json --provider ollama --dry-run
qualgraph llm analyze .qualgraph/annotated.graph.json --provider openai --model gpt-4o-miniUser code stays local unless you explicitly choose an API provider.
Qualgraph also ships with a reusable agent skill for Codex-style LLM workflows.
If the agent is running inside this repository, the skill is already available
from .agents/skills/qualgraph.
See Agent Skill for:
- repo-local usage
- global Codex skill installation
- example prompts
- expected outputs
- Installation
- CLI Reference
- Configuration
- Viewer
- LLM Workflows
- Agent Skill
- Architecture
- Contributing
- Security
python -m pip install -e ".[dev]"
python -m ruff check .
python -m pytest
python -m build
python -m twine check dist/*Viewer browser checks require Chromium:
python -m playwright install chromium
python -m pytest tests/e2e -qAfter code changes in this repository, run:
graphify update .Qualgraph is alpha software. The public interface is useful, but the graph schema and scoring model may still evolve before a stable 1.0 release.