CodeCompass: AI-Powered Codebase Explorer

Mikongoi Warren — Wed, 04 Feb 2026 13:37:00 +0000

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:

🔍 Scan - Instantly visualize repository structure with intelligent file tree display
💬 Query - Ask natural language questions about your codebase ("how does authentication work?")
🔗 Trace - Map execution flows and function call chains across files
⚠️ Analyze - Detect security vulnerabilities, performance issues, and code smells
📚 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

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

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

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

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

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

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!

Copilot spotted it immediately and suggested:

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

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'
]

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:

🔗 GitHub: https://github.com/warrenshiv/code-compass
📦 PyPI: https://pypi.org/project/code-compass-cli/
📖 Docs: Auto-generated via codecompass gendocs

Built by: @warrenshiv

Forem: Mikongoi Warren