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:

1. Expanding support to JavaScript/TypeScript.




2. 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.

# Run analysis without installation

uvx pyscn analyze .

# or

pipx run pyscn analyze .

# Install with pipx (recommended)

pipx install pyscn



# Or with uv

uv tool install pyscn

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

cd pyscn

make build

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

Happy coding!