Pyscn README

English | 日本語 | 简体中文 | Français

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:

1. "Analyze the code quality of the app/ directory"

2. "Find duplicate code and help me refactor it"

3. "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

macOS Intel (x86_64): PyPI wheels are built for Apple Silicon only (the Intel wheel was dropped in v1.5.1), so uvx, pipx, uv, and pip cannot install pyscn on Intel Macs. Use brew install pyscn or go install github.com/ludo-technologies/pyscn/cmd/pyscn@latest instead.

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

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 --json --html --no-open .      # JSON and HTML reports from one run
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