A Gen Z tool to check your code vibes and analyze technical debt with style. No cap, this tool will tell you exactly what's mid in your codebase and how much it'll cost to make it fire again.
Built for Code with Kiro Hackathon 2025 π
- π Vibe Check Your Code: Identifies what's fire and what's mid in your codebase
- π° Real Cost Estimates: No cap on how much it'll cost to fix your technical debt
- π Priority Rankings: Shows you what to fix first (periodt)
- π Multiple Output Formats: Console, HTML, and JSON - whatever vibes you need
- π Modern Web Interface: Dark theme dashboard that actually slays
- π GitHub Integration: Clone and analyze any repo - even the sus ones
- β‘ CI/CD Ready: Automated vibe checks in your pipeline
- π³ Docker Ready: Containerized and ready to deploy anywhere
# Install dependencies
make install-dev
# Analyze the example project
make analyze
# Launch web interface (recommended)
make web
# Generate HTML report
make analyze-html
# Run all tests
make test
# See all available commands
make helpπ TECHNICAL DEBT ANALYSIS REPORT
============================================================
π SUMMARY:
Total Issues: 17
Estimated Hours: 36.3
Estimated Cost: $4,351.20
Average Impact: 3.9/10
π₯ TOP HIGH-IMPACT ISSUES:
1. [HIGH] High Complexity - Function has complexity 24
File: src/processor.py:45
Cost: $960.00 (8h)
- High Complexity Functions (cyclomatic complexity > 10)
- Long Functions (> 50 lines)
- TODO/FIXME Comments (unresolved technical debt)
- Long Lines (> 120 characters)
- Deep Nesting (excessive if/for/while nesting)
# Development Setup
make install-dev # Install development dependencies
make dev-setup # Complete development environment setup
# Analysis Commands
make analyze # Analyze the example project
make analyze-html # Generate HTML report for example project
make analyze-json # Generate JSON report for example project
# Web Interface
make web # Start web interface (development mode)
make web-prod # Start web interface (production mode)
make web-demo # Start web interface with demo data
# Docker Deployment
make docker-build # Build Docker image
make docker-run # Run Docker container
make docker-dev # Run Docker in development mode
make docker-prod # Run Docker in production mode
make deploy-docker # Deploy using Docker
# Development Tools
make test # Run unit tests
make lint # Run code linting
make format # Format code with black
make clean # Clean up generated files
# Production Deployment
make build # Build for production
make deploy # Deploy to production (using gunicorn)
make deploy-k8s # Deploy to Kubernetes
# Information
make help # Show all available commands
make info # Show system information# Basic vibe check
python code-vibes.py analyze examples/messy_codebase --no-cap
# Custom hourly rate
python code-vibes.py analyze examples/messy_codebase --rate 150 --slay
# HTML report
python code-vibes.py analyze examples/messy_codebase --output html --output-file vibes-report.html
# JSON report for CI/CD
python code-vibes.py analyze examples/messy_codebase --output json --output-file vibes.json
# Filter by severity
python code-vibes.py analyze examples/messy_codebase --min-severity high --periodt
# Verbose output (get all the tea)
python code-vibes.py analyze examples/messy_codebase --verbose --fr# Start the modern web interface (recommended)
make web
# Open http://localhost:8080
# Production mode
make web-prod
# Custom host and port
python code-vibes.py web --host 0.0.0.0 --port 8080 --debug --slayWeb Interface Features:
- π¨ Modern dark theme with Tailwind CSS
- π Local Project Analysis: Analyze projects on your filesystem
- π GitHub Integration: Clone and analyze any public GitHub repository
- π Interactive results with real-time cost calculations
- π± Mobile-friendly responsive design
- π Real-time analysis progress
- π Detailed issue breakdown with severity indicators
# Quick Docker setup
make docker-build
make docker-run
# Development with hot reload
make docker-dev
# Production deployment
make docker-prod
# Or manually
docker build -t code-vibes .
docker run -p 8080:8080 code-vibes# GitHub Actions example
- name: Technical Debt Analysis
run: |
make install
python code-vibes.py analyze . --output json --output-file vibes.json
# Parse results and fail if critical issues found
# GitLab CI example
technical_debt:
script:
- make analyze-json
- cat debt_report.json
artifacts:
reports:
junit: debt_report.jsoncode-vibes/
βββ code_vibes/ # Main package
β βββ analyzer.py # Core vibe analysis engine with AST parsing
β βββ reporter.py # Multi-format report generation
β βββ cli.py # Command-line interface with Gen Z energy
β βββ config.py # Configuration management
β βββ web/ # Web application with dark theme
β βββ app.py # Flask application factory
β βββ routes.py # Web routes and API endpoints
β βββ templates/ # HTML templates that actually slay
β βββ static/ # CSS, JS, and assets
βββ examples/ # Sample projects for testing vibes
β βββ messy_codebase/ # Demo project with sus code
βββ deploy/ # Deployment configurations
β βββ docker/ # Docker setup
β βββ kubernetes/ # K8s manifests
β βββ nginx/ # Nginx configuration
β βββ scripts/ # Deployment scripts
βββ tests/ # Unit tests
βββ Makefile # Development and deployment commands
βββ code-vibes.py # Main entry point β¨
make dev-setup # Complete setup
make web # Start development servermake docker-build # Build image
make docker-prod # Run in production modemake deploy-k8s # Deploy to cluster
kubectl get pods -l app=code-vibesmake deploy # Deploy with GunicornSee deploy/README.md for detailed deployment instructions.
- Commands Reference: Quick reference for all commands
- Usage Guide: Detailed usage examples and tutorials
- Deployment Guide: Production deployment instructions
- Examples: Sample projects and use cases
- API Documentation: Web interface API reference (when running)
# Run all tests
make test
# Run with coverage
make ci-test
# Lint code
make lint
# Format code
make formatThis tool bridges the gap between "we have technical debt" and "here's exactly what it costs and how to fix it." Perfect for:
- Engineering Managers: Get concrete cost estimates for planning sprints
- Developers: Prioritize refactoring work by business impact
- CTOs: Make data-driven decisions about technical debt investment
- Teams: Track debt reduction progress over time with metrics
- CI/CD Pipelines: Automated debt monitoring and reporting
- Practical Value: Solves a real problem every development team faces
- Business Impact: Translates technical concepts into business metrics ($$$)
- Easy Integration: Works with existing workflows and CI/CD pipelines
- Extensible Architecture: Easy to add new debt detection patterns
- Multiple Interfaces: CLI, modern web UI, and JSON API for different use cases
- Production Ready: Docker, Kubernetes, and cloud deployment support
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Run tests:
make test - Format code:
make format - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Transform your technical debt from a vague concern into actionable, prioritized work with concrete cost estimates! π