ludo-technologies/pyscn

pyscn – AI‑aware code‑quality analyzer for Python

What it does

• Runs a fast, static analysis of a whole Python code‑base and produces a single quality score (0‑100) with an A‑F grade.
• Generates an interactive HTML report (or JSON) that highlights the most urgent problems.

How it works

• The engine is written in Go and uses the tree‑sitter parser to walk the Python AST at >100 k lines / second.
• Five analysis “angles” are applied:
  1. Dead code – unreachable statements that can be removed.
  2. Duplicate code – clone detection (Type 1‑4) to spot copy‑pasted blocks.
  3. Complexity – cyclomatic and cognitive complexity metrics for functions and classes.
  4. Hotspots – per‑file and per‑directory quality/complexity roll‑ups to prioritize refactors.
  5. Architecture – circular imports, layer‑rule violations (clean, hexagonal, MVC presets) and automatically discovered module communities.
  6. Class design – coupling (CBO) and cohesion (LCOM4) checks.
• Results are visualised in a single HTML page that colour‑codes files, shows graphs of module relationships, and lists actionable recommendations.

Why it matters for AI‑assisted coding

• Modern AI pair‑programmers (Claude, Cursor, GitHub Copilot, Gemini, etc.) can suggest code that works but is hard to maintain. pyscn lets you verify that AI‑generated code stays clean, low‑complexity, and well‑structured.
• The tool ships Agent Skills that teach coding agents when to invoke each analysis (e.g., “run a dead‑code check before committing”).
• An optional MCP server (pyscn‑mcp) exposes the same analyses via the Model‑Code‑Protocol so agents like Claude Code or Cursor can call them directly from the chat UI.

Getting started

# One‑liner, no install needed
uvx pyscn@latest analyze .
# or, after installing with pipx
pipx install pyscn
pyscn analyze .   # HTML report opens automatically

• Use pyscn check in CI pipelines for a quick pass/fail gate (e.g., max complexity ≤ 15, no circular deps).
• Configuration lives in .pyscn.toml (or under [tool.pyscn] in pyproject.toml).

Integration points

• Polyscan App – a free GitHub App that posts a weekly audit report as an issue for public repos.
• Claude Code plugin – installs the MCP server and registers the Skills automatically.
• Cursor / other agents – add the MCP server entry to the agent’s config JSON.

Installation options

• Preferred: pipx install pyscn (or uv tool install pyscn).
• macOS Intel users need the Homebrew or go install route because the pre‑built wheels target Apple Silicon.
• You can also build from source with make build.

Who might use it

• Teams that rely heavily on AI code generators and want an automated guardrail against technical debt.
• Individual developers who want a quick, visual health check of a Python project.
• CI/CD pipelines that need a language‑agnostic quality gate (via the underlying polyscan for other languages).

Where to learn more

• Full docs: https://docs.codescan.dev/pyscn/
• Blog article introducing the tool: https://dev.to/daisukeyoda/pyscn-the-code-quality-analyzer-for-vibe-coders-18hk
• Source code and contribution guides are in the repository’s docs/ folder.

---

License: MIT