pyscn

A code quality analyzer for Python vibe coders.

Building with Cursor, Claude, or ChatGPT? pyscn performs structural analysis to keep your codebase maintainable.

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

https://github.com/user-attachments/assets/71d7a126-9c5e-4254-99f4-f2cdedd526ad

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 that are hard to read and test (cyclomatic and cognitive complexity)
🏗️ 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 --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

Pyscn Bot (GitHub App)

Pyscn Bot monitors your Python code quality automatically.

Features

PR Code Review - Automatic code review on every pull request
Weekly Code Audit - Scans your entire repository and creates issues for architectural problems

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pyscn-1.28.0-py3-none-win_amd64.whl (11.3 MB view details)

Uploaded Jul 25, 2026 Python 3Windows x86-64

pyscn-1.28.0-py3-none-manylinux_2_17_x86_64.whl (10.8 MB view details)

Uploaded Jul 25, 2026 Python 3manylinux: glibc 2.17+ x86-64

pyscn-1.28.0-py3-none-macosx_11_0_arm64.whl (9.9 MB view details)

Uploaded Jul 25, 2026 Python 3macOS 11.0+ ARM64

File details

Details for the file pyscn-1.28.0-py3-none-win_amd64.whl.

File metadata

Download URL: pyscn-1.28.0-py3-none-win_amd64.whl
Upload date: Jul 25, 2026
Size: 11.3 MB
Tags: Python 3, Windows x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pyscn-1.28.0-py3-none-win_amd64.whl
Algorithm	Hash digest
SHA256	`c9f760f9f716aa47ce510861b5b1d4f9ae41de4513dd68a05a3a9841be81bbbc`
MD5	`18f9184ffe83d7ae64c7a34a4a1400b2`
BLAKE2b-256	`22c837584de188b32823e0baa52bf66c66dc11dae9e89be546c607fbe8f24829`

See more details on using hashes here.

File details

Details for the file pyscn-1.28.0-py3-none-manylinux_2_17_x86_64.whl.

File metadata

Download URL: pyscn-1.28.0-py3-none-manylinux_2_17_x86_64.whl
Upload date: Jul 25, 2026
Size: 10.8 MB
Tags: Python 3, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pyscn-1.28.0-py3-none-manylinux_2_17_x86_64.whl
Algorithm	Hash digest
SHA256	`368e70a43319953341f519069ab222fed4deadba9125b50171455b8ca75c8431`
MD5	`124612109dccf73b01a387745ccd65a6`
BLAKE2b-256	`05c5ae63159f5e0eb6f9d7b74579f46f65e43f6483a0c57831af0c8d2cd58e98`

See more details on using hashes here.

File details

Details for the file pyscn-1.28.0-py3-none-macosx_11_0_arm64.whl.

File metadata

Download URL: pyscn-1.28.0-py3-none-macosx_11_0_arm64.whl
Upload date: Jul 25, 2026
Size: 9.9 MB
Tags: Python 3, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pyscn-1.28.0-py3-none-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`3ce509fc00a48c2bbc96452d127aface250731375f4a802a0deaf35906291390`
MD5	`40846dcf8d1ebceabe30104f981e1536`
BLAKE2b-256	`40b594c807c790187d8692d4cd89f112a752274c56625ddee4ecd38a88d808af`