Summary
Are you riding the wave of Vibe Coding with AI assistants, churning out code faster than ever? The speed is thrilling — but how do you keep your codebase clean, maintainable, and scalable?
I've created pyscn, a high-speed code quality analyzer for Python, built with Go. It's designed specifically for modern developers who leverage AI tools like Claude Code, Codex, and more.
Why I Built It
AI coding assistants are powerful allies. However, as projects grow in scale and complexity, relying solely on AI-generated code can lead to a tangled mess. Many developers have experienced this: the codebase becomes difficult to navigate, and what started as rapid development slows to a crawl.
I noticed a few common pitfalls in this new era of vibe-driven development:
Code Duplication: Subtle variations of the same logic creeping into different parts of the codebase.
Complex Dependencies: Modules becoming tightly coupled without a clear architectural vision.
Deeply Nested Functions: Logic that is hard to read, test, and debug.
pyscn was born out of the need to address these issues. It analyzes your code for these specific problems, helping you catch "technical debt" introduced by AI-assisted coding before it becomes a major headache.
Getting Started
The easiest way to try pyscn is to run it without installation, directly in your project directory.
# If you use pipx
pipx run pyscn analyze .
# Or if you use uv
uvx pyscn analyze .
(Note: if you've ever tried pyscn before, use uvx pyscn@latest analyze . to use latest version.)
Usage
pyscn has two main commands to fit your workflow:
pyscn analyze: In-Depth Analysis & Reporting
This command performs a comprehensive analysis and generates a beautiful, interactive HTML report. It gives you a bird's-eye view of your project's health, highlighting dead code, overly complex functions, and code clones.
pyscn check: Quick Code Health Checks in Your Terminal
This command is designed for automation. It acts like a linter, scanning your code for issues and reporting them directly in the terminal. If it finds code that exceeds your configured thresholds (e.g., cyclomatic complexity greater than 15), it will exit with an error code, failing the check. This makes it perfect for integrating into your pre-commit hooks or CI/CD pipeline.
Here’s a quick example with uvx pyscn@latest check testdata:
testdata/python/simple/dead_code_simple.py:12:1: unreachable_after_return(critical)
testdata/python/edge_cases/nested_structures.py:0:1: main is too complex (23 > 10)
testdata/python/edge_cases/python310_features.py:116:1: clone of testdata/python/simple/control_flow.py:133:1 (similarity: 99.3%)
testdata/python/edge_cases/python310_features.py:49:1: clone of testdata/python/edge_cases/python310_features.py:143:1 (similarity: 99.2%)
As you can see, it pinpoints the exact location of issues like unreachable code and potential code clones.
The Reaction from Hacker News
I officially released version 1.0.0 last week and posted it on Hacker News. The response was far greater than I had imagined.
The post sparked a lively discussion around "Vibe Coding" and the challenges of maintaining code quality in the age of AI. It was incredibly valuable to hear from core developers. Comments like, "This could be really useful for reviewing AI-generated code" and "This is important for maintaining architectural sanity," affirmed that pyscn is solving a real-world problem.
What's Next
This is just the beginning for pyscn. I'm actively exploring new features, many of which are still in the conceptual stage beyond what's listed in the GitHub Issues.
Two of the most requested features are:
Expanding support to JavaScript/TypeScript.
Integration with AI agentic workflows (e.g., allowing AI agents to use
pyscn's analysis to autonomously review and refactor code).
I'm excited about the future of pyscn and would love to hear your ideas! Feel free to open an Issue or start a Discussion on GitHub.
ludo-technologies
/
pyscn
pyscn - An Intelligent Python Code Quality Analyzer
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
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…
Happy coding!
Top comments (0)