DEV Community

Cover image for CodeCompass: AI-Powered Codebase Explorer
Mikongoi Warren
Mikongoi Warren

Posted on

CodeCompass: AI-Powered Codebase Explorer

#devchallenge #githubchallenge #cli #githubcopilot

GitHub Copilot CLI Challenge Submission

This is a submission for the GitHub Copilot CLI Challenge

What I Built

CodeCompass - An AI-powered Python CLI tool that helps developers navigate, analyze, and understand codebases quickly. It's like having a code expert in your terminal.

5 Core Features:

  1. 🔍 Scan - Instantly visualize repository structure with intelligent file tree display
  2. 💬 Query - Ask natural language questions about your codebase ("how does authentication work?")
  3. 🔗 Trace - Map execution flows and function call chains across files
  4. ⚠️ Analyze - Detect security vulnerabilities, performance issues, and code smells
  5. 📚 Gendocs - Auto-generate professional documentation (README, ARCHITECTURE, SETUP)

Why I built it: Onboarding to new projects is painful. I wanted a tool that answers "where's the auth code?" or "how does this work?" instantly, without reading thousands of lines.

Tech Stack: Python, Click, Rich | Status: Published on PyPI ✅

Demo

Installation 

pipx install code-compass-cli
Enter fullscreen mode Exit fullscreen mode

Quick Commands 

# Scan project structure
codecompass scan /path/to/project

# Ask questions
codecompass query "explain authentication" /path/to/project

# Trace function calls
codecompass trace "login" /path/to/project

# Analyze code quality
codecompass analyze /path/to/project

# Generate docs
codecompass gendocs /path/to/project
Enter fullscreen mode Exit fullscreen mode

Live Example - Query Command 

$ codecompass query "how does authentication work" ~/emailplatform

╭───────────────────╮
│ CodeCompass Query │
╰───────────────────╯

✓ Results found:

[1] app/Http/Middleware/Authenticate.php
    Function: handle (line 23)
    Function: redirectTo (line 45)

[2] app/Http/Controllers/Auth/LoginController.php  
    Function: login (line 34)
    Function: authenticated (line 67)

[3] app/Http/Controllers/AuthController.php
    Function: verify (line 89)

Found 3 authentication-related files with 6 functions
Enter fullscreen mode Exit fullscreen mode

Live Example - Analyze Command 

$ codecompass analyze ~/my-project

╭──────────────────────────────╮
│ CodeCompass Quality Analysis │
╰──────────────────────────────╯

Analysis Results:
  🔴 Critical: 2
  🟡 Warnings: 5
  🔵 Info: 12

━ CRITICAL ISSUES ━

1. SECURITY - Exposed Secret
   📄 config/settings.py:15
   api_key = "sk_live_abcd1234..."
   💡 Move secrets to environment variables

2. SECURITY - SQL Injection Risk  
   📄 database/queries.py:42
   query = f"SELECT * FROM users WHERE id={user_id}"
   💡 Use prepared statements
Enter fullscreen mode Exit fullscreen mode

Repository: https://github.com/warrenshiv/code-compass

PyPI Package: https://pypi.org/project/code-compass-cli/

Demo Video: https://asciinema.org/a/flre8Iul1xDF0ebx

My Experience with GitHub Copilot CLI

GitHub Copilot CLI transformed this project from a 3-4 day build into 8 hours of focused development. Here's how:

1. Instant Project Scaffolding

Instead of manually creating 13+ Python files, I described what I needed:

Create CodeCompass CLI with modules: scanner, query, analyzer, tracer, docs
Enter fullscreen mode Exit fullscreen mode

Copilot generated the entire project structure, proper package initialization, and Click command framework in seconds.

2. Complex Logic Generation

The Query module needed to intelligently search codebases. I told Copilot:

Build a query engine that searches files by keywords, extracts function definitions, 
shows line numbers, and excludes vendor/node_modules
Enter fullscreen mode Exit fullscreen mode

It generated 200+ lines of pattern matching, file parsing, and result formatting instantly.

3. Real-Time Bug Fixes

Hit a critical bug where variable names conflicted:

# Error: 'int' is not iterable
warnings = len(result["warning"])
for issue in warnings:  # TypeError!
Enter fullscreen mode Exit fullscreen mode

Copilot spotted it immediately and suggested:

warning_count = len(result["warning"])  
for issue in result["warning"]:  # Fixed!
Enter fullscreen mode Exit fullscreen mode

Saved 30+ minutes of debugging.

4. Security Pattern Detection

For the Analyze feature, I needed to detect SQL injection, hardcoded secrets, XSS. Copilot generated regex patterns and detection logic that would've taken hours of research:

# Generated by Copilot
sql_patterns = [
    r'execute\s*\(\s*["\'].*%s.*["\']',
    r'SELECT.*WHERE.*\+',
    r'query\s*=\s*f["\']SELECT'
]
Enter fullscreen mode Exit fullscreen mode

5. Professional Documentation

The Gendocs feature auto-generates README, ARCHITECTURE, and SETUP docs. Copilot created markdown templates with proper structure, code examples, and formatting - normally a 2-hour task, done in 5 minutes.

6. PyPI Publishing Setup

Needed setup.py and pyproject.toml for PyPI. Copilot generated both with correct entry points, dependencies, and metadata on first try. No Stack Overflow needed.

Impact Summary:

  • ⏱️ 5x faster development (40 hours → 8 hours)
  • 🐛 Fewer bugs - Caught issues during generation
  • 📦 Production-ready - Published to PyPI same day
  • 🎨 Better UX - Rich terminal formatting suggestions
  • 🧪 Comprehensive testing - Generated test scenarios for all features

The game-changer: Copilot doesn't just autocomplete - it understands context. When I added the 5th feature (gendocs), it automatically updated imports, maintained consistent styling, and integrated with existing Rich formatting patterns across multiple files.

Coolest Moment 🤯

Asked Copilot to "make the analyzer detect N+1 query problems". It not only generated the detection pattern but also added fix suggestions and severity levels. That level of understanding is wild.

GitHub Copilot CLI made CodeCompass possible in a weekend hackathon timeline. Without it, I'd still be writing boilerplate for the scanner module.

Links:

Built by: @warrenshiv

Top comments (0)