pyscn

Code quality analysis for Python in the age of AI coding.

Building with Cursor, Claude, or ChatGPT? pyscn keeps AI-generated code maintainable with structural analysis.

Working with other languages? pyscn is part of polyscan — code quality analyzers for JavaScript/TypeScript and more

Quick Start

# Run analysis without installation
uvx pyscn@latest analyze .
# or
pipx run pyscn analyze .

Demo

Features

One command scores your whole codebase (0-100 with an A-F grade) and generates an HTML report that shows what to fix first.

pyscn looks at your code from five angles:

🧹 Dead code - unreachable code you can safely delete
📋 Duplicate code - copy-pasted and structurally similar code worth merging (Type 1-4 clone detection)
🌀 Complexity - functions and executable class suites that are hard to read and test (cyclomatic and cognitive complexity)
🔥 Module and directory hotspots - per-file quality and per-directory complexity rollups for prioritizing refactors
🏗️ Architecture - circular imports, layer rule violations (clean / layered / hexagonal / MVC presets), and auto-detected module communities that reveal how your code is actually structured
🧩 Class design - classes that do too much or depend on too much (CBO coupling, LCOM4 cohesion)

100,000+ lines/sec • Built with Go + tree-sitter

AI Agent Integration

pyscn ships Agent Skills that teach AI coding agents when and how to run each analysis: health checks, refactoring, architecture review, and CI-friendly reports.

Agent Skills (Recommended)

uvx add-skills ludo-technologies/pyscn

This installs the Skills into your project. They work with Claude Code, Cursor, Codex, Gemini CLI, and many other agents (add --agent cursor etc. to target one, --global for all projects).

Then just ask your agent:

"Analyze the code quality of the app/ directory"
"Find duplicate code and help me refactor it"
"Show me complex code and help me simplify it"

MCP Server (Optional)

For tighter integration, the bundled pyscn-mcp server exposes the same analyses as MCP tools to Claude Code, Cursor, ChatGPT, and other MCP clients.

Claude Code plugin (sets up the MCP server and the Skills together):

claude plugin marketplace add ludo-technologies/pyscn
claude plugin install pyscn-mcp@pyscn-marketplace

Manual setup for Claude Code:

claude mcp add pyscn-mcp uvx -- pyscn-mcp

Cursor / Claude Desktop: add to your MCP settings (~/.config/claude-desktop/config.json or Cursor settings):

{
  "mcpServers": {
    "pyscn-mcp": {
      "command": "uvx",
      "args": ["pyscn-mcp"],
      "env": {
        "PYSCN_CONFIG": "/path/to/.pyscn.toml"
      }
    }
  }
}

Dive deeper in mcp/README.md for setup walkthroughs and docs/MCP_INTEGRATION.md for architecture details.

Installation

# Install with pipx (recommended)
pipx install pyscn

# Or with uv
uv tool install pyscn

Alternative installation methods

Build from source

git clone https://github.com/ludo-technologies/pyscn.git
cd pyscn
make build

Go install

go install github.com/ludo-technologies/pyscn/cmd/pyscn@latest

Common Commands

`pyscn analyze`

Run comprehensive analysis with HTML report

pyscn analyze .                              # All analyses with HTML report
pyscn analyze --json .                       # Generate JSON report
pyscn analyze --json --output - . | jq       # JSON report on stdout
pyscn analyze --select complexity .          # Only complexity analysis
pyscn analyze --select deps .                # Only dependency analysis
pyscn analyze --select complexity,deps,deadcode . # Multiple analyses
pyscn analyze --skip-communities .           # Skip module community detection

`pyscn check`

Fast CI-friendly quality gate

pyscn check .                         # Quick pass/fail check
pyscn check --max-complexity 15 .     # Custom thresholds
pyscn check --max-cycles 0 .          # Only allow 0 cycle dependency
pyscn check --select deps .           # Check only for circular dependencies
pyscn check --select di .             # Detect DI anti-patterns (opt-in)
pyscn check --allow-circular-deps .   # Allow circular dependencies (warning only)

`pyscn init`

Create configuration file

pyscn init                         # Generate .pyscn.toml

💡 Run pyscn --help or pyscn <command> --help for complete options

Configuration

Create a .pyscn.toml file or add [tool.pyscn] to your pyproject.toml:

# .pyscn.toml
[complexity]
max_complexity = 15

[dead_code]
min_severity = "warning"

[output]
directory = "reports"

⚙️ Run pyscn init to generate a full configuration file with all available options

Don't want to run the CLI every week?

Install Polyscan on GitHub — it files a weekly health score as a GitHub Issue. Free for every repository.

Documentation

📖 pyscn documentation site — installation, rule catalog, CLI reference, configuration, output specification

For contributors: Development Guide • Architecture • Testing

Enterprise Support

For commercial support, custom integrations, or consulting services, contact us at contact@ludo-tech.org

License

MIT License — see LICENSE

Built with ❤️ using Go and tree-sitter

Metadata

Release files for pyscn 1.31.0

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

Built distributions (wheels)

Table of built distributions (wheels) for pyscn 1.31.0
File	Interpreter	ABI	Platform	Reset
pyscn-1.31.0-py3-none-win_amd64.whl 11.6 MB Sep 7, 2026	Python 3	none	Windows x86-64	Details
pyscn-1.31.0-py3-none-manylinux_2_17_x86_64.whl 11.2 MB Sep 7, 2026	Python 3	none	Linux glibc 2.17+ x86-64	Details
pyscn-1.31.0-py3-none-macosx_11_0_arm64.whl 10.2 MB Sep 7, 2026	Python 3	none	macOS 11.0+ ARM64	Details

Total release size: 33.0 MB

Release files / pyscn-1.31.0-py3-none-win_amd64.whl

Download URL	pyscn-1.31.0-py3-none-win_amd64.whl
Size	11.6 MB
Tags	Python 3 Windows x86-64
SHA-256 checksum How to use checksums	`b6603ccbc9df6ee8a544c1d2157fdafa1f0caf368f02491471508de1c1199066`
BLAKE2b-256 checksum How to use checksums	`95e023600df9c92605cf4d4c456321ca95338e7304bc709ef7c6f26f538956cc`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / pyscn-1.31.0-py3-none-manylinux_2_17_x86_64.whl

Download URL	pyscn-1.31.0-py3-none-manylinux_2_17_x86_64.whl
Size	11.2 MB
Tags	Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum How to use checksums	`3a59e578c5759e242a38ec9186558c8966443cb24b962816d3fec7a722ea7a9b`
BLAKE2b-256 checksum How to use checksums	`3f7a22517439cb71118090ba7fc43115e436f0c87b2d6d84a0e81fb9ba0de078`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / pyscn-1.31.0-py3-none-macosx_11_0_arm64.whl

Download URL	pyscn-1.31.0-py3-none-macosx_11_0_arm64.whl
Size	10.2 MB
Tags	Python 3 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`19481631d684f74752b43e800ece1ad3ab7599d79a1a6123241ce175cdc44905`
BLAKE2b-256 checksum How to use checksums	`a839186499a9762738038a02d86b8c3c68b3a152b39f80a7418c90ada7d530da`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`