pyscn - Python Code Quality Analyzer

pyscn is a code quality analyzer for Python vibe coders.

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

Quick Start

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

Demo

pyscn_20251005.mov

Features

• 🔍 CFG-based dead code detection – Find unreachable code after exhaustive if-elif-else chains
• 📋 Clone detection with APTED + LSH – Identify refactoring opportunities with tree edit distance
• 🔗 Coupling metrics (CBO) – Track architecture quality and module dependencies
• 📊 Cyclomatic complexity analysis – Spot functions that need breaking down

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

MCP Integration

Run pyscn analyses straight from AI coding assistants via the Model Context Protocol (MCP). The bundled pyscn-mcp server exposes the same tools used in the CLI to Claude Code, Cursor, ChatGPT, and other MCP clients.

Claude Code Setup

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

Cursor / Claude Desktop Setup

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"
      }
    }
  }
}

The instructions like "Analyze the code quality" trigger pyscn via MCP.

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 check

Fast CI-friendly quality gate

pyscn check .                      # Quick pass/fail check
pyscn check --max-complexity 15 .  # Custom thresholds

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

CI/CD Integration

# GitHub Actions
- uses: actions/checkout@v4
- run: pipx run pyscn check .    # Fail on quality issues

# Pre-commit hook
- repo: local
  hooks:
    - id: pyscn
      name: pyscn check
      entry: pipx run pyscn check .
      language: system
      pass_filenames: false
      types: [python]

---

Documentation

📚 Development Guide • Architecture • Testing

Enterprise Support

For commercial support, custom integrations, or consulting services, contact us at [email protected]

License

MIT License — see LICENSE

---

Built with ❤️ using Go and tree-sitter