Code Quality Intelligence Agent (CQIA)

A powerful CLI tool that analyzes codebases across multiple languages, detects issues, and generates actionable reports with AI-powered insights.

🚀 Quick Start

# Install
pip install -r requirements.txt
pip install -e .

# Basic analysis
python -m cqia.cli analyze /path/to/repo --out report --model openrouter

# Interactive shell (recommended)
python -m cqia.cli shell

📋 Features

• Multi-language Support: Python, JavaScript, TypeScript
• AI-Powered Analysis: LLM integration with OpenRouter/Anthropic
• Interactive Shell: Real-time tool calling visibility
• RAG System: Vector stores (Chroma, FAISS) with progress tracking
• Static Analysis: Integration with Semgrep, Bandit, ESLint
• GitHub Integration: PR review comments and diff analysis
• Quality Metrics: Complexity, maintainability, technical debt
• SARIF Export: For CI/CD integration

🛠️ Installation

# Base installation
pip install -r requirements.txt
pip install -e .

# Optional: Full analyzers
pip install -e '.[full]'

# Optional: RAG & embeddings
pip install -e '.[rag]'

# Optional: Agents
pip install -e '.[agents]'

⚙️ Environment Setup

Create a .env file:

# LLM Providers (choose one)
OPENROUTER_API_KEY=sk-or-...          # Recommended
ANTHROPIC_API_KEY=sk-ant-...          # Alternative
OPENAI_API_KEY=sk-...                 # For embeddings

# Optional
GITHUB_TOKEN=ghp_...                  # For PR reviews
CQIA_POLICY=policy.yaml               # Custom policies

📖 Usage

Interactive Shell (Recommended)

python -m cqia.cli shell

Inside the shell:

• analyze --model openrouter - Run AI analysis
• index --store chroma --embedding hf - Build RAG index
• chat --model openrouter - Interactive Q&A
• status - Check environment and index
• help - Show all commands

Command Line Analysis

# AI-powered analysis
python -m cqia.cli analyze /path/to/repo --out report --model openrouter

# Static analysis only
python -m cqia.cli analyze /path/to/repo --static-only --out report

# Hybrid (static + AI)
python -m cqia.cli analyze /path/to/repo --hybrid --model openrouter --out report

# With SARIF export for CI
python -m cqia.cli analyze /path/to/repo --min-severity HIGH --sarif report.sarif --model openrouter

RAG & Chat

# Build index with progress tracking
python -m cqia.cli index /path/to/repo --store chroma --embedding hf

# Interactive chat with AI
python -m cqia.cli chat /path/to/repo --rag --model openrouter

# Retrieval-only (no AI)
python -m cqia.cli chat /path/to/repo --rag --model none

GitHub Integration

# Analyze diff between commits
python -m cqia.cli analyze-diff /path/to/repo --base <sha> --head <sha> --model openrouter

# Post PR review comment
python -m cqia.cli gh-review owner repo 123 --path /local/checkout --base <sha> --head <sha> --model openrouter

🔍 Analysis Types

Agent-Based Analysis (Primary)

• LLM-powered: Uses AI to detect security, performance, and quality issues
• Tool calling: Dynamic file exploration and AST analysis
• Real-time visibility: See exactly what tools the AI is using

Static Analysis

• Semgrep: Security and code quality rules
• Bandit: Python security issues
• ESLint: JavaScript/TypeScript issues
• JSCPD: Code duplication detection

Quality Metrics

• Cyclomatic Complexity: Code complexity measurement
• Maintainability Index: Code maintainability score
• Technical Debt Ratio: Estimated technical debt

📊 Output Formats

• Markdown Reports: Human-readable analysis results
• JSON Reports: Machine-readable structured data
• SARIF: Standard format for CI/CD integration
• LLM Summaries: AI-generated insights and recommendations

🎯 Issue Categories

• Security: Vulnerabilities, unsafe practices
• Performance: Slow code, memory leaks
• Quality: Code smells, best practices
• Documentation: Missing docs, unclear code
• Duplication: Repeated code patterns

🔧 CLI Commands

Command	Description
analyze	Run code analysis
index	Build RAG index
chat	Interactive Q&A
analyze-diff	Analyze git diff
gh-review	GitHub PR review
ingest	Clone and analyze repo
fix	Apply simple fixes

🚦 CI/CD Integration

# Fail on high-severity issues
python -m cqia.cli analyze . --min-severity HIGH --sarif report.sarif --model openrouter

# Exit code 1 if HIGH/CRITICAL issues found
echo $?  # Check exit code

📁 Project Structure

cqia/
├── agent/           # AI agent components
├── cqia/           # Core CLI and analysis
├── integrations/   # GitHub, git integrations
├── providers/      # LLM providers
├── rag/           # RAG system
└── mcp_servers/   # Tool servers

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• PR-Agent (Qodo AI)
• CodeRabbit engineering blogs
• Kodus-AI
• Agent building guides (Sid Bharath, Martin Fowler)

---

Need help? Run python -m cqia.cli --help or start the interactive shell with python -m cqia.cli shell