🔧 Compiler Copilot

AI-Powered Debugging & Compiler Analysis Tool with IBM BOB

A revolutionary compiler debugging and analysis tool that integrates IBM BOB (watsonx AI) with debuggers (GDB/LLDB) and compiler toolchains. Features autonomous debugging where AI takes complete control of debugging sessions, analyzes outputs, and provides comprehensive summaries.

✨ Key Features

🤖 Autonomous Debugging

Hands-off debugging: IBM BOB automatically runs debugging commands
AI-driven analysis: Analyzes each output and decides next steps
Comprehensive summaries: Detailed reports with findings and recommendations
Goal-oriented: Just specify what you want to find, BOB does the rest

🐛 Interactive Debugging

GDB & LLDB integration: Full debugger support
Natural language commands: Chat with your debugger
Real-time analysis: IBM BOB explains what's happening
Session history: All debugging sessions saved for review

🔬 Compiler Analysis

LLVM IR generation: Generate and analyze intermediate representation
Assembly analysis: Understand compiler output
Optimization insights: See what passes were applied
Binary analysis: nm, objdump, readelf, strings integration

🧪 Test Generation

AI-powered test cases: Generate tests from descriptions
Bug reproduction: Create test cases for customer issues
Edge case generation: Comprehensive test coverage

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/yourusername/CompilerCopilot.git
cd CompilerCopilot

# Run setup
./setup.sh

# Configure environment (interactive wizard)
./configure.sh

Configuration

The interactive configuration wizard will:

Auto-detect installed tools (GDB, LLDB, Clang, etc.)
Prompt for IBM watsonx credentials
Validate your configuration
Generate .env file

Or manually edit config/.env:

# IBM watsonx Configuration
IBM_BOB_API_KEY=your_api_key_here
IBM_BOB_PROJECT_ID=your_project_id_here
IBM_BOB_URL=https://us-south.ml.cloud.ibm.com

# Debugger Configuration
DEBUGGER_TYPE=gdb
GDB_PATH=/usr/bin/gdb
LLDB_PATH=/usr/bin/lldb

# Compiler Configuration
CLANG_PATH=/usr/bin/clang

Usage

# Start Compiler Copilot
./compiler-copilot.sh

# Or activate virtual environment and run directly
source venv/bin/activate
python -m src.shell.interactive_v2

📖 Usage Examples

Autonomous Debugging (Hands-off)

copilot> autodebug ./myprogram "Find cause of segmentation fault"

IBM BOB will:

Start the debugger
Run the program
Analyze the crash
Examine memory and registers
Identify the root cause
Provide fix recommendations

Output:

🤖 AUTONOMOUS DEBUGGING SESSION STARTED
Session ID: debug_1717567890
Program: ./myprogram
Goal: Find cause of segmentation fault

🔍 Step 1/50: Starting program...
🔍 Step 2/50: Analyzing crash location...
🔍 Step 3/50: Examining pointer values...

✅ Goal achieved!

📋 SUMMARY:
- Segmentation fault at line 15
- NULL pointer dereference
- Pointer 'ptr' never initialized

💡 RECOMMENDATIONS:
1. Initialize ptr: int *ptr = malloc(sizeof(int));
2. Add NULL check before use
3. Free memory after use

Manual Debugging

copilot> debug ./program
copilot> run
copilot> backtrace
copilot> print variable

Compiler Analysis

# Generate LLVM IR
copilot> generate ir main.c --opt O2

# Generate assembly
copilot> generate assembly main.c

# Analyze optimization passes
copilot> analyze ir main.c

Binary Analysis

# Show symbols
copilot> nm ./program

# Disassemble
copilot> objdump ./program

# Show ELF info
copilot> readelf ./program

Natural Language

copilot> "Why is my program crashing?"
copilot> "Explain this assembly code"
copilot> "Generate a test case for buffer overflow"

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                  User Interface                         │
│            (Interactive Shell / Chat)                   │
└─────────────────┬───────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────┐
│              IBM BOB (watsonx AI)                       │
│    • Command Interpretation                             │
│    • Output Analysis                                    │
│    • Decision Making                                    │
│    • Summary Generation                                 │
└─────────────────┬───────────────────────────────────────┘
                  │
        ┌─────────┴─────────┬─────────────┐
        ▼                   ▼             ▼
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│  Debuggers   │   │  Compiler    │   │   Binary     │
│  GDB/LLDB    │   │  Clang/LLVM  │   │   Analysis   │
│              │   │              │   │   Tools      │
└──────────────┘   └──────────────┘   └──────────────┘

📚 Documentation

Quick Start Guide - Get started in 5 minutes
Autonomous Debugging - Complete guide to hands-off debugging
Architecture - System design and components
Flowcharts - Visual system flows
Virtual Environment Guide - Understanding local execution
Contributing - How to contribute
Project Summary - Detailed project overview

🎯 Use Cases

1. Customer Issue Investigation

# Reproduce customer issue
copilot> generate test "Customer reports crash when input > 1000"

# Debug autonomously
copilot> autodebug ./app "Find why crash occurs with large input"

# Analyze and fix
copilot> suggest fix app.c

2. Performance Analysis

# Generate optimized code
copilot> generate ir app.c --opt O3

# Analyze optimizations
copilot> analyze ir app.c

# Compare assembly
copilot> generate assembly app.c --opt O0
copilot> generate assembly app.c --opt O3

3. Memory Debugging

# Find memory leaks
copilot> autodebug ./program "Identify memory leak"

# Analyze allocations
copilot> debug ./program
copilot> break malloc
copilot> break free

4. Crash Analysis

# Analyze core dump
copilot> analyze crash ./program --core core.dump

# Get AI explanation
copilot> "Explain this crash"

🔧 Advanced Features

Session History

All interactions are saved:

# View session history
cat sessions/session_20260605_120000.md

# View autonomous debugging session
cat sessions/autodebug_debug_1717567890.json

MCP Integration

Model Context Protocol support for advanced tool integration:

# MCP server provides tools to AI
- execute_debugger_command
- analyze_compiler_output
- generate_test_case

Customization

# Adjust autonomous debugging steps
auto_debugger = AutonomousDebugger(
    max_steps=100,  # Increase for complex issues
    debugger_type='lldb'
)

🛠️ Requirements

System Requirements

OS: macOS, Linux (Windows WSL)
Python: 3.8 or higher
Debugger: GDB 8.0+ or LLDB 10.0+
Compiler: Clang/LLVM 10.0+

Python Dependencies

prompt_toolkit - Interactive shell
rich - Beautiful terminal output
requests - API communication
python-dotenv - Environment configuration

IBM watsonx Account

IBM Cloud account
watsonx.ai access
API key and project ID

📦 Project Structure

CompilerCopilot/
├── src/
│   ├── debugger/
│   │   ├── gdb_wrapper.py          # GDB integration
│   │   ├── lldb_wrapper.py         # LLDB integration
│   │   └── autonomous_debugger.py  # Autonomous debugging
│   ├── compiler/
│   │   ├── analyzer.py             # Compiler analysis
│   │   └── tools.py                # Binary analysis tools
│   ├── llm/
│   │   └── ibm_bob_client.py       # IBM BOB integration
│   ├── shell/
│   │   └── interactive_v2.py       # Interactive shell
│   └── mcp/
│       └── server.py               # MCP server
├── config/
│   └── env.example                 # Configuration template
├── docs/
│   ├── QUICKSTART.md
│   ├── AUTONOMOUS_DEBUGGING.md
│   ├── ARCHITECTURE.md
│   └── FLOWCHART.md
├── examples/
│   ├── sample_program.c
│   └── workflow_examples.md
├── sessions/                       # Session history storage
├── setup.sh                        # Setup script
├── configure.sh                    # Configuration wizard
├── compiler-copilot.sh            # Main launcher
└── README.md

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/yourusername/CompilerCopilot.git
cd CompilerCopilot

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run tests
python -m pytest tests/

📝 License

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

🙏 Acknowledgments

IBM watsonx - AI-powered analysis and decision making
GDB/LLDB - Powerful debugging capabilities
LLVM/Clang - Compiler infrastructure
Open Source Community - Various tools and libraries

📧 Contact

Issues: GitHub Issues
Discussions: GitHub Discussions

🗺️ Roadmap

⭐ Star History

If you find this project useful, please consider giving it a star!

Made with ❤️ by the Compiler Copilot Team

Empowering developers with AI-assisted debugging and compiler analysis

Name		Name	Last commit message	Last commit date
config		config
docs		docs
examples		examples
src		src
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CONTRIBUTING.md		CONTRIBUTING.md
FLOWCHART.md		FLOWCHART.md
LICENSE		LICENSE
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
VIRTUAL_ENV_GUIDE.md		VIRTUAL_ENV_GUIDE.md
compiler-copilot.sh		compiler-copilot.sh
configure.sh		configure.sh
requirements.txt		requirements.txt
setup.sh		setup.sh

Latest commit

History

Folders and files

Repository files navigation